Help us shape the future of Go! Take the 2026 Go Developer Survey

proot

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package proot provides PRoot-based container isolation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendAndroidBinds 

func AppendAndroidBinds(args []string) []string

AppendAndroidBinds appends Android-specific bind mounts to proot args.

func BuildEnv added in v0.9.3 

func BuildEnv(userEnv []string, imageEnv []string) []string

BuildEnv builds the environment slice that the proot child process and its descendants will receive. It always runs StripHostEnv on the host environment and then layers the AndroidEnv() defaults, the image-defined env, and the user-supplied env, in that order (later wins for duplicates).

Callers should also have invoked os.Unsetenv on the LD_PRELOAD family in the current process, because exec.Command inherits the parent env unless cmd.Env is set; this function sets cmd.Env explicitly so the LD_PRELOAD unset is the only required step in the caller.

func BuildProotBaseArgs 

func BuildProotBaseArgs(rootfs string, uid, gid int) ([]string, error)

BuildProotBaseArgs returns the common proot arguments for all execution methods. If uid/gid are >= 0, adds -i flag to impersonate that user inside proot.

func DetectKernelRelease 

func DetectKernelRelease() string

DetectKernelRelease reads the actual kernel release from /proc.

func FindProotBinary 

func FindProotBinary() string

FindProotBinary locates the best available proot binary and verifies it exists. Searches for doki-proot first, then falls back to system proot. Returns the empty string when no usable proot binary is found, so callers can surface a clear error instead of "executable not found" at exec.Cmd time.

func IsAvailable 

func IsAvailable() bool

IsAvailable checks if proot (or doki-proot) is available on the system.

func IsTermuxProot 

func IsTermuxProot() bool

IsTermuxProot checks if the proot binary is the Termux-specific build.

func ShouldUseProot 

func ShouldUseProot() bool

ShouldUseProot returns true when proot should be the preferred execution mode. Typically on Android/Termux where user namespaces are not available.

func UnsetProotKillers added in v0.9.3 

func UnsetProotKillers()

UnsetProotKillers clears the LD_PRELOAD family and the Termux/Android vars from the *current* process env so that exec.Command(proot) does not inherit them. The guest env is sanitised separately by BuildEnv.

This must be called once per process before the first proot invocation. It is safe to call multiple times.

Types

type ContainerEvent 

type ContainerEvent struct {
	Type     EventType
	ID       string
	Data     string
	ExitCode int
}

ContainerEvent represents an event from a container.

type EventBus 

type EventBus struct {
	// contains filtered or unexported fields
}

EventBus manages event subscriptions for containers.

func NewEventBus 

func NewEventBus() *EventBus

NewEventBus creates a new event bus.

func (*EventBus) Publish 

func (b *EventBus) Publish(event ContainerEvent)

Publish sends an event to all subscribers of the container.

func (*EventBus) Subscribe 

func (b *EventBus) Subscribe(containerID string, fn EventSubscriber)

Subscribe registers a subscriber for a container's events.

func (*EventBus) SubscriberCount 

func (b *EventBus) SubscriberCount(containerID string) int

SubscriberCount returns the number of subscribers for a container.

func (*EventBus) Unsubscribe 

func (b *EventBus) Unsubscribe(containerID string)

Unsubscribe removes all subscribers for a container.

type EventSubscriber 

type EventSubscriber func(event ContainerEvent)

EventSubscriber receives container events.

type EventType 

type EventType string

EventType is the type of container event. 

const (
	EventStdout EventType = "stdout"
	EventStderr EventType = "stderr"
	EventExit   EventType = "exit"
	EventError  EventType = "error"
	EventReady  EventType = "ready"
)

type IPCClient 

type IPCClient struct {
	// contains filtered or unexported fields
}

IPCClient communicates with the doki-proot daemon via Unix socket.

func NewIPCClient 

func NewIPCClient(socketPath string) *IPCClient

NewIPCClient creates a new IPC client.

func (*IPCClient) Close 

func (c *IPCClient) Close() error

Close closes the connection.

func (*IPCClient) Config 

func (c *IPCClient) Config(hidden []string, ports []PortMap) error

Config sends configuration (hidden files, port maps).

func (*IPCClient) Connect 

func (c *IPCClient) Connect(ctx context.Context) error

Connect connects to the daemon socket. If the socket doesn't exist, attempts to start the daemon.

func (*IPCClient) Exec 

func (c *IPCClient) Exec(ctx context.Context, id string, cmd []string, env []string, cwd string) (<-chan ContainerEvent, error)

Exec sends an exec command to the daemon and returns a channel of events.

func (*IPCClient) Health 

func (c *IPCClient) Health() (*Response, error)

Health checks daemon health.

func (*IPCClient) IsConnected 

func (c *IPCClient) IsConnected() bool

IsConnected returns true if connected to daemon.

func (*IPCClient) Shutdown 

func (c *IPCClient) Shutdown() error

Shutdown shuts down the daemon.

func (*IPCClient) Signal 

func (c *IPCClient) Signal(id string, sig string) error

Signal sends a signal to a container.

func (*IPCClient) SocketPath 

func (c *IPCClient) SocketPath() string

SocketPath returns the socket path.

func (*IPCClient) Subscribe 

func (c *IPCClient) Subscribe(id string, fn EventSubscriber)

Subscribe subscribes to events for a container.

func (*IPCClient) Unsubscribe 

func (c *IPCClient) Unsubscribe(id string)

Unsubscribe unsubscribes from events for a container.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager provides proot-based container support for Android kernels that lack full user namespace support.

func NewManager 

func NewManager(rootfsDir string) *Manager

NewManager creates a new proot manager.

func (*Manager) Exec 

func (m *Manager) Exec(rootfs string, args []string, env []string, _ string) (string, error)

Exec executes a command in a proot-based environment.

type MessageType 

type MessageType string

MessageType is the type of IPC message. 

const (
	// Requests (Doki → doki-proot)
	TypeExec        MessageType = "exec"
	TypeConfig      MessageType = "config"
	TypeSignal      MessageType = "signal"
	TypeHealth      MessageType = "health"
	TypeShutdown    MessageType = "shutdown"
	TypeSubscribe   MessageType = "subscribe"
	TypeUnsubscribe MessageType = "unsubscribe"

	// Responses (doki-proot → Doki)
	TypeStdout         MessageType = "stdout"
	TypeStderr         MessageType = "stderr"
	TypeExit           MessageType = "exit"
	TypeReady          MessageType = "ready"
	TypeError          MessageType = "error"
	TypeExecError      MessageType = "exec_error"
	TypeConfigAck      MessageType = "config_ack"
	TypeSignalAck      MessageType = "signal_ack"
	TypeHealthResp     MessageType = "health"
	TypeShutdownAck    MessageType = "shutdown_ack"
	TypeSubscribeAck   MessageType = "subscribe_ack"
	TypeUnsubscribeAck MessageType = "unsubscribe_ack"
	TypeLog            MessageType = "log"
)

type PortMap 

type PortMap struct {
	GuestBind int    `json:"guest_bind"`
	HostBind  int    `json:"host_bind"`
	Proto     string `json:"proto"`
}

PortMap is a guest→host port mapping.

type ProotInfo added in v0.9.3 

type ProotInfo struct {
	Binary  string
	Version string
}

ProotInfo describes a resolved proot binary and the version string it reports via "proot --version". The version is parsed from the first line of the command output and is "unknown" when the binary does not answer.

func Version added in v0.9.3 

func Version(bin string) ProotInfo

Version invokes "<bin> --version" (or "-V") and returns the first matching numeric version token. The returned struct never has nil fields: Version is "unknown" on any failure so callers can render diagnostics without an extra error check.

type Request 

type Request struct {
	Type    MessageType `json:"type"`
	ID      string      `json:"id,omitempty"`
	Cmd     []string    `json:"cmd,omitempty"`
	Env     []string    `json:"env,omitempty"`
	Cwd     string      `json:"cwd,omitempty"`
	Sig     string      `json:"sig,omitempty"`
	Hidden  []string    `json:"hidden_files,omitempty"`
	PortMap []PortMap   `json:"port_map,omitempty"`
}

Request is a message sent to the doki-proot daemon.

func NewConfigRequest 

func NewConfigRequest(hidden []string, ports []PortMap) *Request

NewConfigRequest creates a config request.

func NewExecRequest 

func NewExecRequest(id string, cmd []string, env []string, cwd string) *Request

NewExecRequest creates an exec request.

func NewHealthRequest 

func NewHealthRequest() *Request

NewHealthRequest creates a health check request.

func NewShutdownRequest 

func NewShutdownRequest() *Request

NewShutdownRequest creates a shutdown request.

func NewSignalRequest 

func NewSignalRequest(id string, sig string) *Request

NewSignalRequest creates a signal request.

func NewSubscribeRequest 

func NewSubscribeRequest(id string) *Request

NewSubscribeRequest creates a subscribe request.

func NewUnsubscribeRequest 

func NewUnsubscribeRequest(id string) *Request

NewUnsubscribeRequest creates an unsubscribe request.

func (*Request) Marshal 

func (r *Request) Marshal() ([]byte, error)

Marshal serializes the request to newline-delimited JSON.

type Response 

type Response struct {
	Type   MessageType `json:"type"`
	ID     string      `json:"id,omitempty"`
	Data   string      `json:"data,omitempty"`
	Code   int         `json:"code,omitempty"`
	Status string      `json:"status,omitempty"`
	PID    int         `json:"pid,omitempty"`
	Socket string      `json:"socket,omitempty"`
	Msg    string      `json:"msg,omitempty"`
}

Response is a message received from the doki-proot daemon.

func UnmarshalResponse 

func UnmarshalResponse(data []byte) (*Response, error)

UnmarshalResponse deserializes a response from JSON bytes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.