Documentation
¶
Overview ¶
wire.go provides net.Conn-based helpers for the vsock framed message protocol.
The vsock package has two message I/O layers:
- vsock.go: WriteMessage/ReadMessage operating on *Conn (raw AF_VSOCK fd wrapper)
- wire.go: SendMessage/ReadFull operating on net.Conn (standard Go interface)
Both exist because *Conn does not satisfy net.Conn (its SetDeadline methods accept interface{} instead of time.Time). The net.Conn variants in this file are used by the VM backends (Darwin uses Virtualization.framework's net.Conn, Linux uses UDS-forwarded net.Conn) and by ExecPipe.
Index ¶
- Constants
- Variables
- func ExecPipe(ctx context.Context, conn net.Conn, command string, opts *api.ExecOptions) (*api.ExecResult, error)
- func GetLocalCID() (uint32, error)
- func ReadFull(conn net.Conn, buf []byte) (int, error)
- func ReadMessage(conn *Conn) (uint8, []byte, error)
- func SendMessage(conn net.Conn, msgType uint8, data []byte) error
- func WriteMessage(conn *Conn, msgType uint8, data []byte) error
- type Addr
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) File() *os.File
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) Read(b []byte) (int, error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) SetDeadline(t interface{}) error
- func (c *Conn) SetReadDeadline(t interface{}) error
- func (c *Conn) SetWriteDeadline(t interface{}) error
- func (c *Conn) Write(b []byte) (int, error)
- type ExecRequest
- type ExecResponse
- type ExecTTYRequest
- type Listener
- type WindowSize
Constants ¶
const ( // AF_VSOCK is the address family for vsock AF_VSOCK = 40 // VMADDR_CID_ANY accepts connections from any CID VMADDR_CID_ANY = 0xFFFFFFFF // VMADDR_CID_HYPERVISOR is the CID for the hypervisor (host from guest perspective) VMADDR_CID_HYPERVISOR = 0 // VMADDR_CID_LOCAL is the CID for local communication VMADDR_CID_LOCAL = 1 // VMADDR_CID_HOST is the CID for the host VMADDR_CID_HOST = 2 // VMADDR_PORT_ANY accepts connections on any port VMADDR_PORT_ANY = 0xFFFFFFFF // IOCTL_VM_SOCKETS_GET_LOCAL_CID gets the local CID IOCTL_VM_SOCKETS_GET_LOCAL_CID = 0x7B9 )
const ( MsgTypeExec uint8 = 1 MsgTypeExecResult uint8 = 2 MsgTypeStdout uint8 = 3 MsgTypeStderr uint8 = 4 MsgTypeSignal uint8 = 5 MsgTypeReady uint8 = 6 MsgTypeStdin uint8 = 7 // TTY: stdin data from host MsgTypeResize uint8 = 8 // TTY: window resize MsgTypeExecTTY uint8 = 9 // TTY: exec with PTY MsgTypeExit uint8 = 10 // TTY: process exited MsgTypeExecStream uint8 = 11 // Streaming batch: stdout/stderr sent as chunks, then ExecResult MsgTypeExecPipe uint8 = 12 // Pipe mode: like ExecStream but also accepts MsgTypeStdin, sends MsgTypeExit )
Protocol for command execution over vsock
Variables ¶
var ( ErrCreateSocket = errors.New("create vsock socket") ErrBind = errors.New("bind vsock") ErrListen = errors.New("listen on vsock") ErrAccept = errors.New("accept vsock connection") ErrConnect = errors.New("connect to vsock") )
Socket lifecycle errors
var ( ErrOpenDevice = errors.New("open /dev/vsock") ErrGetLocalCID = errors.New("get local CID") )
Device/CID errors
var ( ErrEncodeExecRequest = errors.New("encode exec request") ErrWriteHeader = errors.New("write header") ErrWriteRequest = errors.New("write request") ErrReadResponseHeader = errors.New("read response header") ErrReadResponseData = errors.New("read response data") )
Wire protocol errors
Functions ¶
func ExecPipe ¶ added in v0.1.12
func ExecPipe(ctx context.Context, conn net.Conn, command string, opts *api.ExecOptions) (*api.ExecResult, error)
ExecPipe executes a command over a vsock connection with bidirectional stdin/stdout/stderr piping (no PTY). The caller must supply an already-dialed conn; ExecPipe takes ownership and closes it when done.
func GetLocalCID ¶
GetLocalCID returns the local CID of the machine
func ReadFull ¶ added in v0.1.12
ReadFull reads exactly len(buf) bytes from conn, retrying short reads.
func ReadMessage ¶
ReadMessage reads a length-prefixed message from the connection
func SendMessage ¶ added in v0.1.12
SendMessage writes a framed vsock message (1-byte type + 4-byte big-endian length + payload) to conn.
Types ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn represents a vsock connection
func (*Conn) RemoteAddr ¶
func (*Conn) SetDeadline ¶
func (*Conn) SetReadDeadline ¶
func (*Conn) SetWriteDeadline ¶
type ExecRequest ¶
type ExecRequest struct {
Command string `json:"command"`
Args []string `json:"args,omitempty"`
WorkingDir string `json:"working_dir,omitempty"`
Env map[string]string `json:"env,omitempty"`
Stdin []byte `json:"stdin,omitempty"`
User string `json:"user,omitempty"` // "uid", "uid:gid", or username
}
ExecRequest is sent from host to guest to execute a command
type ExecResponse ¶
type ExecResponse struct {
ExitCode int `json:"exit_code"`
Stdout []byte `json:"stdout,omitempty"`
Stderr []byte `json:"stderr,omitempty"`
Error string `json:"error,omitempty"`
}
ExecResponse is sent from guest to host with execution results
type ExecTTYRequest ¶
type ExecTTYRequest struct {
Command string `json:"command"`
Args []string `json:"args,omitempty"`
WorkingDir string `json:"working_dir,omitempty"`
Env map[string]string `json:"env,omitempty"`
Rows uint16 `json:"rows"`
Cols uint16 `json:"cols"`
User string `json:"user,omitempty"` // "uid", "uid:gid", or username
}
ExecTTYRequest is sent from host to guest for interactive execution
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
Listener represents a vsock listener
type WindowSize ¶
WindowSize represents terminal dimensions
Source Files