vsock

package
v0.2.9 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source 
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
)
View Source 
const (
	// ServicePortExec is the guest-agent exec and stream service port.
	ServicePortExec = 5000
	// ServicePortVFS is the guest VFS service port.
	ServicePortVFS = 5001
	// ServicePortReady is the guest ready-check service port.
	ServicePortReady = 5002
)
View Source 
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
	MsgTypePortForward uint8 = 13 // Request guest-agent to proxy raw TCP to an in-guest address
	MsgTypeWriteFile   uint8 = 14 // Write a file inside the guest filesystem
	MsgTypeReadFile    uint8 = 15 // Read a file from the guest filesystem
	MsgTypeListFiles   uint8 = 16 // List files in a guest directory
	MsgTypeFileResult  uint8 = 17 // Response for file operations
)

Protocol for command execution over vsock

Variables

View Source 
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

View Source 
var (
	ErrOpenDevice  = errors.New("open /dev/vsock")
	ErrGetLocalCID = errors.New("get local CID")
)

Device/CID errors

View Source 
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")

	ErrEncodePortForwardRequest = errors.New("encode port-forward request")
	ErrReadPortForwardResponse  = errors.New("read port-forward response")
	ErrPortForwardRejected      = errors.New("port-forward rejected")
	ErrUnexpectedPortForwardMsg = errors.New("unexpected port-forward response message")

	ErrEncodeFileRequest = errors.New("encode file request")
	ErrFileRemote        = errors.New("guest file operation")
)

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 

func GetLocalCID() (uint32, error)

GetLocalCID returns the local CID of the machine

func ListFilesVsock added in v0.1.25 

func ListFilesVsock(conn net.Conn, path string) ([]api.FileInfo, error)

ListFilesVsock lists files in a guest directory via the exec service vsock.

func OpenPortForward added in v0.1.20 

func OpenPortForward(conn net.Conn, host string, port uint16) error

OpenPortForward sends a port-forward request on an already-connected guest-agent vsock stream and waits for an ACK before switching to raw proxy mode.

func ReadFileVsock added in v0.1.25 

func ReadFileVsock(conn net.Conn, path string) ([]byte, error)

ReadFileVsock reads a file from the guest via the exec service vsock.

func ReadFull added in v0.1.12 

func ReadFull(conn net.Conn, buf []byte) (int, error)

ReadFull reads exactly len(buf) bytes from conn, retrying short reads.

func ReadMessage 

func ReadMessage(conn *Conn) (uint8, []byte, error)

ReadMessage reads a length-prefixed message from the connection

func SendMessage added in v0.1.12 

func SendMessage(conn net.Conn, msgType uint8, data []byte) error

SendMessage writes a framed vsock message (1-byte type + 4-byte big-endian length + payload) to conn.

func WriteFileVsock added in v0.1.25 

func WriteFileVsock(conn net.Conn, path string, content []byte, mode uint32) error

WriteFileVsock writes a file inside the guest via the exec service vsock.

func WriteMessage 

func WriteMessage(conn *Conn, msgType uint8, data []byte) error

WriteMessage writes a length-prefixed message to the connection

Types

type Addr 

type Addr struct {
	CID  uint32
	Port uint32
}

Addr represents a vsock address

func (*Addr) Network 

func (a *Addr) Network() string

func (*Addr) String 

func (a *Addr) String() string

type Conn 

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

Conn represents a vsock connection

func Dial 

func Dial(cid, port uint32) (*Conn, error)

Dial connects to a vsock address

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) File 

func (c *Conn) File() *os.File

func (*Conn) LocalAddr 

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read 

func (c *Conn) Read(b []byte) (int, error)

func (*Conn) RemoteAddr 

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline 

func (c *Conn) SetDeadline(t interface{}) error

func (*Conn) SetReadDeadline 

func (c *Conn) SetReadDeadline(t interface{}) error

func (*Conn) SetWriteDeadline 

func (c *Conn) SetWriteDeadline(t interface{}) error

func (*Conn) Write 

func (c *Conn) Write(b []byte) (int, error)

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 FileInfo added in v0.1.25 

type FileInfo struct {
	Name  string `json:"name"`
	Size  int64  `json:"size"`
	Mode  uint32 `json:"mode"`
	IsDir bool   `json:"is_dir"`
}

FileInfo holds file metadata returned by list_files.

type FileResponse added in v0.1.25 

type FileResponse struct {
	Content []byte     `json:"content,omitempty"`
	Files   []FileInfo `json:"files,omitempty"`
	Error   string     `json:"error,omitempty"`
}

FileResponse is the guest's reply to a file operation.

type ListFilesRequest added in v0.1.25 

type ListFilesRequest struct {
	Path string `json:"path"`
}

ListFilesRequest is sent from host to guest to list a directory.

type Listener 

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

Listener represents a vsock listener

func Listen 

func Listen(port uint32) (*Listener, error)

Listen creates a vsock listener on the given port

func ListenCID 

func ListenCID(cid, port uint32) (*Listener, error)

ListenCID creates a vsock listener on the given CID and port

func (*Listener) Accept 

func (l *Listener) Accept() (*Conn, error)

func (*Listener) Addr 

func (l *Listener) Addr() net.Addr

func (*Listener) Close 

func (l *Listener) Close() error

type PortForwardRequest added in v0.1.20 

type PortForwardRequest struct {
	Host string `json:"host,omitempty"`
	Port uint16 `json:"port"`
}

PortForwardRequest asks the guest agent to dial a TCP destination in guest network namespace and then switch the vsock stream into raw proxy mode.

type ReadFileRequest added in v0.1.25 

type ReadFileRequest struct {
	Path string `json:"path"`
}

ReadFileRequest is sent from host to guest to read a file.

type WindowSize 

type WindowSize struct {
	Rows uint16 `json:"rows"`
	Cols uint16 `json:"cols"`
}

WindowSize represents terminal dimensions

type WriteFileRequest added in v0.1.25 

type WriteFileRequest struct {
	Path    string `json:"path"`
	Content []byte `json:"content"`
	Mode    uint32 `json:"mode"`
}

WriteFileRequest is sent from host to guest to write a file.

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.