guest

package
v0.0.6 Latest Latest
Warning

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

Go to latest
Published: Feb 16, 2026 License: MIT Imports: 25 Imported by: 0

README

Guest Agent

Remote guest VM operations via vsock - command execution and file copying.

Architecture

Client (WebSocket)
    ↓
API Server (/instances/{id}/exec, /instances/{id}/cp)
    ↓
lib/guest/client.go (ExecIntoInstance, CopyToInstance, CopyFromInstance)
    ↓
Cloud Hypervisor vsock socket
    ↓
Guest: guest-agent (lib/system/guest_agent)
    ↓
Container (chroot /overlay/newroot)

Features

Command Execution (Exec)
  • ExecIntoInstance(): Execute commands with bidirectional stdin/stdout streaming
  • TTY support: Interactive shells with terminal control
  • Concurrent exec: Multiple simultaneous commands per VM (separate streams)
  • Exit codes: Proper process exit status reporting
File Copy (CP)
  • CopyToInstance(): Copy files/directories from host to guest
  • CopyFromInstance(): Copy files/directories from guest to host
  • Streaming: Efficient chunked transfer for large files
  • Permissions: Preserve file mode and ownership where possible

How It Works

1. API Layer
  • WebSocket endpoint: GET /instances/{id}/exec - command execution
  • WebSocket endpoint: GET /instances/{id}/cp - file copy operations
  • Note: Uses GET method because WebSocket connections MUST be initiated with GET per RFC 6455.
  • Upgrades HTTP to WebSocket for bidirectional streaming
  • Calls guest.ExecIntoInstance() or guest.CopyTo/FromInstance() with the instance's vsock socket path
  • Logs audit trail: JWT subject, instance ID, operation, start/end time
2. Client (lib/guest/client.go)
  • Connects to Cloud Hypervisor's vsock Unix socket
  • Performs vsock handshake: CONNECT 2222\nOK <cid>
  • Creates gRPC client over the vsock connection (pooled per VM for efficiency)
  • Streams data bidirectionally

Concurrency: Multiple calls to the same VM share the underlying gRPC connection but use separate streams.

3. Protocol (guest.proto)

gRPC streaming RPC with protobuf messages:

Exec Request (client → server):

  • ExecStart: Command, TTY flag, environment variables, working directory, timeout
  • stdin: Input data bytes

Exec Response (server → client):

  • stdout: Output data bytes
  • stderr: Error output bytes (non-TTY only)
  • exit_code: Final message with command's exit status

Copy Request (client → server):

  • CopyStart: Destination path, file mode
  • data: File content chunks
  • done: Indicates transfer complete

Copy Response (server → client):

  • data: File content chunks (for CopyFromInstance)
  • error: Error message if operation failed
  • done: Indicates transfer complete
4. Guest Agent (lib/system/guest_agent/main.go)
  • Embedded binary injected into microVM via initrd
  • Runs inside container namespace (chrooted to /overlay/newroot) for proper file access
  • Listens on vsock port 2222 inside guest
  • Implements gRPC GuestService server
  • Executes commands and handles file operations directly
5. Embedding
  • guest-agent binary built by Makefile
  • Embedded into host binary via lib/system/guest_agent_binary.go
  • Injected into initrd at VM creation time
  • Auto-started by init script in guest

Why vsock?

  • Low latency: Direct host-guest communication without networking
  • No network setup: Works even if container has no network
  • Secure: No exposed ports, isolated to host-guest boundary
  • Simple: No SSH keys, passwords, or network configuration

Security & Authorization

  • All authentication and authorization is handled at the API layer via JWT
  • The guest agent trusts that the host has properly authorized the request
  • Commands and file operations run in the container context, not the VM context

Documentation

Index

Constants

View Source
const (
	GuestService_Exec_FullMethodName          = "/guest.GuestService/Exec"
	GuestService_CopyToGuest_FullMethodName   = "/guest.GuestService/CopyToGuest"
	GuestService_CopyFromGuest_FullMethodName = "/guest.GuestService/CopyFromGuest"
	GuestService_StatPath_FullMethodName      = "/guest.GuestService/StatPath"
	GuestService_Shutdown_FullMethodName      = "/guest.GuestService/Shutdown"
)

Variables

View Source
var File_lib_guest_guest_proto protoreflect.FileDescriptor
View Source
var GuestService_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "guest.GuestService",
	HandlerType: (*GuestServiceServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "StatPath",
			Handler:    _GuestService_StatPath_Handler,
		},
		{
			MethodName: "Shutdown",
			Handler:    _GuestService_Shutdown_Handler,
		},
	},
	Streams: []grpc.StreamDesc{
		{
			StreamName:    "Exec",
			Handler:       _GuestService_Exec_Handler,
			ServerStreams: true,
			ClientStreams: true,
		},
		{
			StreamName:    "CopyToGuest",
			Handler:       _GuestService_CopyToGuest_Handler,
			ClientStreams: true,
		},
		{
			StreamName:    "CopyFromGuest",
			Handler:       _GuestService_CopyFromGuest_Handler,
			ServerStreams: true,
		},
	},
	Metadata: "lib/guest/guest.proto",
}

GuestService_ServiceDesc is the grpc.ServiceDesc for GuestService service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func CloseConn

func CloseConn(dialerKey string)

CloseConn removes a connection from the pool by key (call when VM is deleted). We only remove from pool, not explicitly close - the connection will fail naturally when the VM dies, and grpc will clean up.

func CopyFromInstance

func CopyFromInstance(ctx context.Context, dialer hypervisor.VsockDialer, opts CopyFromInstanceOptions) error

CopyFromInstance copies a file or directory from an instance via vsock. The dialer is a hypervisor-specific VsockDialer that knows how to connect to the guest.

func CopyToInstance

func CopyToInstance(ctx context.Context, dialer hypervisor.VsockDialer, opts CopyToInstanceOptions) error

CopyToInstance copies a file or directory to an instance via vsock. The dialer is a hypervisor-specific VsockDialer that knows how to connect to the guest.

func GetOrCreateConn

func GetOrCreateConn(ctx context.Context, dialer hypervisor.VsockDialer) (*grpc.ClientConn, error)

GetOrCreateConn returns an existing connection or creates a new one using a VsockDialer. This supports multiple hypervisor types (Cloud Hypervisor, QEMU, etc.).

func RegisterGuestServiceServer

func RegisterGuestServiceServer(s grpc.ServiceRegistrar, srv GuestServiceServer)

func SetMetrics

func SetMetrics(m *Metrics)

SetMetrics sets the global metrics instance.

func ShutdownInstance added in v0.0.6

func ShutdownInstance(ctx context.Context, dialer hypervisor.VsockDialer, sig int32) error

ShutdownInstance sends a shutdown signal to the guest VM's init process (PID 1). The guest-agent forwards the signal to init, which forwards it to the entrypoint. sig is the signal number to send (0 = SIGTERM default).

Types

type AgentVSockDialError

type AgentVSockDialError struct {
	Err error
}

AgentVSockDialError indicates the vsock dial to the guest agent failed. This typically means the VM is still booting or the agent hasn't started yet.

func (*AgentVSockDialError) Error

func (e *AgentVSockDialError) Error() string

func (*AgentVSockDialError) Unwrap

func (e *AgentVSockDialError) Unwrap() error

type CopyFromGuestEnd

type CopyFromGuestEnd struct {
	Final bool `protobuf:"varint,1,opt,name=final,proto3" json:"final,omitempty"` // True if this is the final file
	// contains filtered or unexported fields
}

CopyFromGuestEnd signals the end of a file or transfer

func (*CopyFromGuestEnd) Descriptor deprecated

func (*CopyFromGuestEnd) Descriptor() ([]byte, []int)

Deprecated: Use CopyFromGuestEnd.ProtoReflect.Descriptor instead.

func (*CopyFromGuestEnd) GetFinal

func (x *CopyFromGuestEnd) GetFinal() bool

func (*CopyFromGuestEnd) ProtoMessage

func (*CopyFromGuestEnd) ProtoMessage()

func (*CopyFromGuestEnd) ProtoReflect added in v0.0.6

func (x *CopyFromGuestEnd) ProtoReflect() protoreflect.Message

func (*CopyFromGuestEnd) Reset

func (x *CopyFromGuestEnd) Reset()

func (*CopyFromGuestEnd) String

func (x *CopyFromGuestEnd) String() string

type CopyFromGuestError

type CopyFromGuestError struct {
	Message string `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"` // Error message
	Path    string `protobuf:"bytes,2,opt,name=path,proto3" json:"path,omitempty"`       // Path that caused error (if applicable)
	// contains filtered or unexported fields
}

CopyFromGuestError reports an error during copy

func (*CopyFromGuestError) Descriptor deprecated

func (*CopyFromGuestError) Descriptor() ([]byte, []int)

Deprecated: Use CopyFromGuestError.ProtoReflect.Descriptor instead.

func (*CopyFromGuestError) GetMessage

func (x *CopyFromGuestError) GetMessage() string

func (*CopyFromGuestError) GetPath

func (x *CopyFromGuestError) GetPath() string

func (*CopyFromGuestError) ProtoMessage

func (*CopyFromGuestError) ProtoMessage()

func (*CopyFromGuestError) ProtoReflect added in v0.0.6

func (x *CopyFromGuestError) ProtoReflect() protoreflect.Message

func (*CopyFromGuestError) Reset

func (x *CopyFromGuestError) Reset()

func (*CopyFromGuestError) String

func (x *CopyFromGuestError) String() string

type CopyFromGuestHeader

type CopyFromGuestHeader struct {
	Path       string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`                               // Relative path from copy root
	Mode       uint32 `protobuf:"varint,2,opt,name=mode,proto3" json:"mode,omitempty"`                              // File mode (permissions)
	IsDir      bool   `protobuf:"varint,3,opt,name=is_dir,json=isDir,proto3" json:"is_dir,omitempty"`               // True if this is a directory
	IsSymlink  bool   `protobuf:"varint,4,opt,name=is_symlink,json=isSymlink,proto3" json:"is_symlink,omitempty"`   // True if this is a symbolic link
	LinkTarget string `protobuf:"bytes,5,opt,name=link_target,json=linkTarget,proto3" json:"link_target,omitempty"` // Symlink target (if is_symlink)
	Size       int64  `protobuf:"varint,6,opt,name=size,proto3" json:"size,omitempty"`                              // File size (0 for directories)
	Mtime      int64  `protobuf:"varint,7,opt,name=mtime,proto3" json:"mtime,omitempty"`                            // Modification time (Unix timestamp)
	Uid        uint32 `protobuf:"varint,8,opt,name=uid,proto3" json:"uid,omitempty"`                                // User ID
	Gid        uint32 `protobuf:"varint,9,opt,name=gid,proto3" json:"gid,omitempty"`                                // Group ID
	// contains filtered or unexported fields
}

CopyFromGuestHeader provides metadata about a file being copied

func (*CopyFromGuestHeader) Descriptor deprecated

func (*CopyFromGuestHeader) Descriptor() ([]byte, []int)

Deprecated: Use CopyFromGuestHeader.ProtoReflect.Descriptor instead.

func (*CopyFromGuestHeader) GetGid

func (x *CopyFromGuestHeader) GetGid() uint32

func (*CopyFromGuestHeader) GetIsDir

func (x *CopyFromGuestHeader) GetIsDir() bool
func (x *CopyFromGuestHeader) GetIsSymlink() bool

func (*CopyFromGuestHeader) GetLinkTarget

func (x *CopyFromGuestHeader) GetLinkTarget() string

func (*CopyFromGuestHeader) GetMode

func (x *CopyFromGuestHeader) GetMode() uint32

func (*CopyFromGuestHeader) GetMtime

func (x *CopyFromGuestHeader) GetMtime() int64

func (*CopyFromGuestHeader) GetPath

func (x *CopyFromGuestHeader) GetPath() string

func (*CopyFromGuestHeader) GetSize

func (x *CopyFromGuestHeader) GetSize() int64

func (*CopyFromGuestHeader) GetUid

func (x *CopyFromGuestHeader) GetUid() uint32

func (*CopyFromGuestHeader) ProtoMessage

func (*CopyFromGuestHeader) ProtoMessage()

func (*CopyFromGuestHeader) ProtoReflect added in v0.0.6

func (x *CopyFromGuestHeader) ProtoReflect() protoreflect.Message

func (*CopyFromGuestHeader) Reset

func (x *CopyFromGuestHeader) Reset()

func (*CopyFromGuestHeader) String

func (x *CopyFromGuestHeader) String() string

type CopyFromGuestRequest

type CopyFromGuestRequest struct {
	Path        string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`                                   // Source path in guest
	FollowLinks bool   `protobuf:"varint,2,opt,name=follow_links,json=followLinks,proto3" json:"follow_links,omitempty"` // Follow symbolic links (like -L flag)
	// contains filtered or unexported fields
}

CopyFromGuestRequest initiates a copy-from-guest operation

func (*CopyFromGuestRequest) Descriptor deprecated

func (*CopyFromGuestRequest) Descriptor() ([]byte, []int)

Deprecated: Use CopyFromGuestRequest.ProtoReflect.Descriptor instead.

func (x *CopyFromGuestRequest) GetFollowLinks() bool

func (*CopyFromGuestRequest) GetPath

func (x *CopyFromGuestRequest) GetPath() string

func (*CopyFromGuestRequest) ProtoMessage

func (*CopyFromGuestRequest) ProtoMessage()

func (*CopyFromGuestRequest) ProtoReflect added in v0.0.6

func (x *CopyFromGuestRequest) ProtoReflect() protoreflect.Message

func (*CopyFromGuestRequest) Reset

func (x *CopyFromGuestRequest) Reset()

func (*CopyFromGuestRequest) String

func (x *CopyFromGuestRequest) String() string

type CopyFromGuestResponse

type CopyFromGuestResponse struct {

	// Types that are valid to be assigned to Response:
	//
	//	*CopyFromGuestResponse_Header
	//	*CopyFromGuestResponse_Data
	//	*CopyFromGuestResponse_End
	//	*CopyFromGuestResponse_Error
	Response isCopyFromGuestResponse_Response `protobuf_oneof:"response"`
	// contains filtered or unexported fields
}

CopyFromGuestResponse streams file data from guest

func (*CopyFromGuestResponse) Descriptor deprecated

func (*CopyFromGuestResponse) Descriptor() ([]byte, []int)

Deprecated: Use CopyFromGuestResponse.ProtoReflect.Descriptor instead.

func (*CopyFromGuestResponse) GetData

func (x *CopyFromGuestResponse) GetData() []byte

func (*CopyFromGuestResponse) GetEnd

func (*CopyFromGuestResponse) GetError

func (*CopyFromGuestResponse) GetHeader

func (*CopyFromGuestResponse) GetResponse

func (x *CopyFromGuestResponse) GetResponse() isCopyFromGuestResponse_Response

func (*CopyFromGuestResponse) ProtoMessage

func (*CopyFromGuestResponse) ProtoMessage()

func (*CopyFromGuestResponse) ProtoReflect added in v0.0.6

func (x *CopyFromGuestResponse) ProtoReflect() protoreflect.Message

func (*CopyFromGuestResponse) Reset

func (x *CopyFromGuestResponse) Reset()

func (*CopyFromGuestResponse) String

func (x *CopyFromGuestResponse) String() string

type CopyFromGuestResponse_Data

type CopyFromGuestResponse_Data struct {
	Data []byte `protobuf:"bytes,2,opt,name=data,proto3,oneof"` // File content chunk
}

type CopyFromGuestResponse_End

type CopyFromGuestResponse_End struct {
	End *CopyFromGuestEnd `protobuf:"bytes,3,opt,name=end,proto3,oneof"` // End of file/transfer marker
}

type CopyFromGuestResponse_Error

type CopyFromGuestResponse_Error struct {
	Error *CopyFromGuestError `protobuf:"bytes,4,opt,name=error,proto3,oneof"` // Error during copy
}

type CopyFromGuestResponse_Header

type CopyFromGuestResponse_Header struct {
	Header *CopyFromGuestHeader `protobuf:"bytes,1,opt,name=header,proto3,oneof"` // File/directory metadata
}

type CopyFromInstanceOptions

type CopyFromInstanceOptions struct {
	SrcPath     string // Source path in guest
	DstPath     string // Local destination path
	FollowLinks bool   // Follow symbolic links
}

CopyFromInstanceOptions configures a copy-from-instance operation

type CopyToGuestEnd

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

CopyToGuestEnd signals the end of a file transfer

func (*CopyToGuestEnd) Descriptor deprecated

func (*CopyToGuestEnd) Descriptor() ([]byte, []int)

Deprecated: Use CopyToGuestEnd.ProtoReflect.Descriptor instead.

func (*CopyToGuestEnd) ProtoMessage

func (*CopyToGuestEnd) ProtoMessage()

func (*CopyToGuestEnd) ProtoReflect added in v0.0.6

func (x *CopyToGuestEnd) ProtoReflect() protoreflect.Message

func (*CopyToGuestEnd) Reset

func (x *CopyToGuestEnd) Reset()

func (*CopyToGuestEnd) String

func (x *CopyToGuestEnd) String() string

type CopyToGuestRequest

type CopyToGuestRequest struct {

	// Types that are valid to be assigned to Request:
	//
	//	*CopyToGuestRequest_Start
	//	*CopyToGuestRequest_Data
	//	*CopyToGuestRequest_End
	Request isCopyToGuestRequest_Request `protobuf_oneof:"request"`
	// contains filtered or unexported fields
}

CopyToGuestRequest represents messages for copying files to guest

func (*CopyToGuestRequest) Descriptor deprecated

func (*CopyToGuestRequest) Descriptor() ([]byte, []int)

Deprecated: Use CopyToGuestRequest.ProtoReflect.Descriptor instead.

func (*CopyToGuestRequest) GetData

func (x *CopyToGuestRequest) GetData() []byte

func (*CopyToGuestRequest) GetEnd

func (x *CopyToGuestRequest) GetEnd() *CopyToGuestEnd

func (*CopyToGuestRequest) GetRequest

func (x *CopyToGuestRequest) GetRequest() isCopyToGuestRequest_Request

func (*CopyToGuestRequest) GetStart

func (x *CopyToGuestRequest) GetStart() *CopyToGuestStart

func (*CopyToGuestRequest) ProtoMessage

func (*CopyToGuestRequest) ProtoMessage()

func (*CopyToGuestRequest) ProtoReflect added in v0.0.6

func (x *CopyToGuestRequest) ProtoReflect() protoreflect.Message

func (*CopyToGuestRequest) Reset

func (x *CopyToGuestRequest) Reset()

func (*CopyToGuestRequest) String

func (x *CopyToGuestRequest) String() string

type CopyToGuestRequest_Data

type CopyToGuestRequest_Data struct {
	Data []byte `protobuf:"bytes,2,opt,name=data,proto3,oneof"` // File content chunk
}

type CopyToGuestRequest_End

type CopyToGuestRequest_End struct {
	End *CopyToGuestEnd `protobuf:"bytes,3,opt,name=end,proto3,oneof"` // End of file marker
}

type CopyToGuestRequest_Start

type CopyToGuestRequest_Start struct {
	Start *CopyToGuestStart `protobuf:"bytes,1,opt,name=start,proto3,oneof"` // Initial copy request with metadata
}

type CopyToGuestResponse

type CopyToGuestResponse struct {
	Success      bool   `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`                               // Whether the copy succeeded
	Error        string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`                                    // Error message if failed
	BytesWritten int64  `protobuf:"varint,3,opt,name=bytes_written,json=bytesWritten,proto3" json:"bytes_written,omitempty"` // Total bytes written
	// contains filtered or unexported fields
}

CopyToGuestResponse is the response after a copy-to-guest operation

func (*CopyToGuestResponse) Descriptor deprecated

func (*CopyToGuestResponse) Descriptor() ([]byte, []int)

Deprecated: Use CopyToGuestResponse.ProtoReflect.Descriptor instead.

func (*CopyToGuestResponse) GetBytesWritten

func (x *CopyToGuestResponse) GetBytesWritten() int64

func (*CopyToGuestResponse) GetError

func (x *CopyToGuestResponse) GetError() string

func (*CopyToGuestResponse) GetSuccess

func (x *CopyToGuestResponse) GetSuccess() bool

func (*CopyToGuestResponse) ProtoMessage

func (*CopyToGuestResponse) ProtoMessage()

func (*CopyToGuestResponse) ProtoReflect added in v0.0.6

func (x *CopyToGuestResponse) ProtoReflect() protoreflect.Message

func (*CopyToGuestResponse) Reset

func (x *CopyToGuestResponse) Reset()

func (*CopyToGuestResponse) String

func (x *CopyToGuestResponse) String() string

type CopyToGuestStart

type CopyToGuestStart struct {
	Path  string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`                 // Destination path in guest
	Mode  uint32 `protobuf:"varint,2,opt,name=mode,proto3" json:"mode,omitempty"`                // File mode (permissions)
	IsDir bool   `protobuf:"varint,3,opt,name=is_dir,json=isDir,proto3" json:"is_dir,omitempty"` // True if this is a directory
	Size  int64  `protobuf:"varint,4,opt,name=size,proto3" json:"size,omitempty"`                // Expected total size (0 for directories)
	Mtime int64  `protobuf:"varint,5,opt,name=mtime,proto3" json:"mtime,omitempty"`              // Modification time (Unix timestamp)
	Uid   uint32 `protobuf:"varint,6,opt,name=uid,proto3" json:"uid,omitempty"`                  // User ID (archive mode only, 0 = use default)
	Gid   uint32 `protobuf:"varint,7,opt,name=gid,proto3" json:"gid,omitempty"`                  // Group ID (archive mode only, 0 = use default)
	// contains filtered or unexported fields
}

CopyToGuestStart initiates a copy-to-guest operation

func (*CopyToGuestStart) Descriptor deprecated

func (*CopyToGuestStart) Descriptor() ([]byte, []int)

Deprecated: Use CopyToGuestStart.ProtoReflect.Descriptor instead.

func (*CopyToGuestStart) GetGid

func (x *CopyToGuestStart) GetGid() uint32

func (*CopyToGuestStart) GetIsDir

func (x *CopyToGuestStart) GetIsDir() bool

func (*CopyToGuestStart) GetMode

func (x *CopyToGuestStart) GetMode() uint32

func (*CopyToGuestStart) GetMtime

func (x *CopyToGuestStart) GetMtime() int64

func (*CopyToGuestStart) GetPath

func (x *CopyToGuestStart) GetPath() string

func (*CopyToGuestStart) GetSize

func (x *CopyToGuestStart) GetSize() int64

func (*CopyToGuestStart) GetUid

func (x *CopyToGuestStart) GetUid() uint32

func (*CopyToGuestStart) ProtoMessage

func (*CopyToGuestStart) ProtoMessage()

func (*CopyToGuestStart) ProtoReflect added in v0.0.6

func (x *CopyToGuestStart) ProtoReflect() protoreflect.Message

func (*CopyToGuestStart) Reset

func (x *CopyToGuestStart) Reset()

func (*CopyToGuestStart) String

func (x *CopyToGuestStart) String() string

type CopyToInstanceOptions

type CopyToInstanceOptions struct {
	SrcPath string      // Local source path
	DstPath string      // Destination path in guest
	Mode    fs.FileMode // Optional: override file mode (0 = preserve source)
}

CopyToInstanceOptions configures a copy-to-instance operation

type ExecOptions

type ExecOptions struct {
	Command      []string
	Stdin        io.Reader
	Stdout       io.Writer
	Stderr       io.Writer
	TTY          bool
	Env          map[string]string  // Environment variables
	Cwd          string             // Working directory (optional)
	Timeout      int32              // Execution timeout in seconds (0 = no timeout)
	WaitForAgent time.Duration      // Max time to wait for agent to be ready (0 = no wait, fail immediately)
	Rows         uint32             // Initial terminal rows (0 = default 24)
	Cols         uint32             // Initial terminal cols (0 = default 80)
	ResizeChan   <-chan *WindowSize // Optional: channel to receive resize events (pointer to avoid copying mutex)
}

ExecOptions configures command execution

type ExecRequest

type ExecRequest struct {

	// Types that are valid to be assigned to Request:
	//
	//	*ExecRequest_Start
	//	*ExecRequest_Stdin
	//	*ExecRequest_Resize
	Request isExecRequest_Request `protobuf_oneof:"request"`
	// contains filtered or unexported fields
}

ExecRequest represents messages from client to server

func (*ExecRequest) Descriptor deprecated

func (*ExecRequest) Descriptor() ([]byte, []int)

Deprecated: Use ExecRequest.ProtoReflect.Descriptor instead.

func (*ExecRequest) GetRequest

func (x *ExecRequest) GetRequest() isExecRequest_Request

func (*ExecRequest) GetResize added in v0.0.6

func (x *ExecRequest) GetResize() *WindowSize

func (*ExecRequest) GetStart

func (x *ExecRequest) GetStart() *ExecStart

func (*ExecRequest) GetStdin

func (x *ExecRequest) GetStdin() []byte

func (*ExecRequest) ProtoMessage

func (*ExecRequest) ProtoMessage()

func (*ExecRequest) ProtoReflect added in v0.0.6

func (x *ExecRequest) ProtoReflect() protoreflect.Message

func (*ExecRequest) Reset

func (x *ExecRequest) Reset()

func (*ExecRequest) String

func (x *ExecRequest) String() string

type ExecRequest_Resize added in v0.0.6

type ExecRequest_Resize struct {
	Resize *WindowSize `protobuf:"bytes,3,opt,name=resize,proto3,oneof"` // Window resize event
}

type ExecRequest_Start

type ExecRequest_Start struct {
	Start *ExecStart `protobuf:"bytes,1,opt,name=start,proto3,oneof"` // Initial exec request
}

type ExecRequest_Stdin

type ExecRequest_Stdin struct {
	Stdin []byte `protobuf:"bytes,2,opt,name=stdin,proto3,oneof"` // Stdin data
}

type ExecResponse

type ExecResponse struct {

	// Types that are valid to be assigned to Response:
	//
	//	*ExecResponse_Stdout
	//	*ExecResponse_Stderr
	//	*ExecResponse_ExitCode
	Response isExecResponse_Response `protobuf_oneof:"response"`
	// contains filtered or unexported fields
}

ExecResponse represents messages from server to client

func (*ExecResponse) Descriptor deprecated

func (*ExecResponse) Descriptor() ([]byte, []int)

Deprecated: Use ExecResponse.ProtoReflect.Descriptor instead.

func (*ExecResponse) GetExitCode

func (x *ExecResponse) GetExitCode() int32

func (*ExecResponse) GetResponse

func (x *ExecResponse) GetResponse() isExecResponse_Response

func (*ExecResponse) GetStderr

func (x *ExecResponse) GetStderr() []byte

func (*ExecResponse) GetStdout

func (x *ExecResponse) GetStdout() []byte

func (*ExecResponse) ProtoMessage

func (*ExecResponse) ProtoMessage()

func (*ExecResponse) ProtoReflect added in v0.0.6

func (x *ExecResponse) ProtoReflect() protoreflect.Message

func (*ExecResponse) Reset

func (x *ExecResponse) Reset()

func (*ExecResponse) String

func (x *ExecResponse) String() string

type ExecResponse_ExitCode

type ExecResponse_ExitCode struct {
	ExitCode int32 `protobuf:"varint,3,opt,name=exit_code,json=exitCode,proto3,oneof"` // Command exit code (final message)
}

type ExecResponse_Stderr

type ExecResponse_Stderr struct {
	Stderr []byte `protobuf:"bytes,2,opt,name=stderr,proto3,oneof"` // Stderr data
}

type ExecResponse_Stdout

type ExecResponse_Stdout struct {
	Stdout []byte `protobuf:"bytes,1,opt,name=stdout,proto3,oneof"` // Stdout data
}

type ExecStart

type ExecStart struct {
	Command []string          `protobuf:"bytes,1,rep,name=command,proto3" json:"command,omitempty"` // Command and arguments
	Tty     bool              `protobuf:"varint,2,opt,name=tty,proto3" json:"tty,omitempty"`        // Allocate pseudo-TTY
	Env     map[string]string ``                                                                    // Environment variables
	/* 133-byte string literal not displayed */
	Cwd            string `protobuf:"bytes,4,opt,name=cwd,proto3" json:"cwd,omitempty"`                                              // Working directory (optional)
	TimeoutSeconds int32  `protobuf:"varint,5,opt,name=timeout_seconds,json=timeoutSeconds,proto3" json:"timeout_seconds,omitempty"` // Execution timeout in seconds (0 = no timeout)
	Rows           uint32 `protobuf:"varint,6,opt,name=rows,proto3" json:"rows,omitempty"`                                           // Initial terminal rows (0 = default 24)
	Cols           uint32 `protobuf:"varint,7,opt,name=cols,proto3" json:"cols,omitempty"`                                           // Initial terminal cols (0 = default 80)
	// contains filtered or unexported fields
}

ExecStart initiates command execution

func (*ExecStart) Descriptor deprecated

func (*ExecStart) Descriptor() ([]byte, []int)

Deprecated: Use ExecStart.ProtoReflect.Descriptor instead.

func (*ExecStart) GetCols added in v0.0.6

func (x *ExecStart) GetCols() uint32

func (*ExecStart) GetCommand

func (x *ExecStart) GetCommand() []string

func (*ExecStart) GetCwd

func (x *ExecStart) GetCwd() string

func (*ExecStart) GetEnv

func (x *ExecStart) GetEnv() map[string]string

func (*ExecStart) GetRows added in v0.0.6

func (x *ExecStart) GetRows() uint32

func (*ExecStart) GetTimeoutSeconds

func (x *ExecStart) GetTimeoutSeconds() int32

func (*ExecStart) GetTty

func (x *ExecStart) GetTty() bool

func (*ExecStart) ProtoMessage

func (*ExecStart) ProtoMessage()

func (*ExecStart) ProtoReflect added in v0.0.6

func (x *ExecStart) ProtoReflect() protoreflect.Message

func (*ExecStart) Reset

func (x *ExecStart) Reset()

func (*ExecStart) String

func (x *ExecStart) String() string

type ExitStatus

type ExitStatus struct {
	Code int
}

ExitStatus represents command exit information

func ExecIntoInstance

func ExecIntoInstance(ctx context.Context, dialer hypervisor.VsockDialer, opts ExecOptions) (*ExitStatus, error)

ExecIntoInstance executes command in instance via vsock using gRPC. The dialer is a hypervisor-specific VsockDialer that knows how to connect to the guest. If WaitForAgent is set, it will retry on connection errors until the timeout.

type FileHandler

type FileHandler func(header *CopyFromGuestHeader, data io.Reader) error

FileHandler is called for each file received from the instance

type GuestServiceClient

type GuestServiceClient interface {
	// Exec executes a command with bidirectional streaming
	Exec(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[ExecRequest, ExecResponse], error)
	// CopyToGuest streams file data to the guest filesystem
	CopyToGuest(ctx context.Context, opts ...grpc.CallOption) (grpc.ClientStreamingClient[CopyToGuestRequest, CopyToGuestResponse], error)
	// CopyFromGuest streams file data from the guest filesystem
	CopyFromGuest(ctx context.Context, in *CopyFromGuestRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[CopyFromGuestResponse], error)
	// StatPath returns information about a path in the guest filesystem
	StatPath(ctx context.Context, in *StatPathRequest, opts ...grpc.CallOption) (*StatPathResponse, error)
	// Shutdown requests graceful VM shutdown by signaling init (PID 1)
	Shutdown(ctx context.Context, in *ShutdownRequest, opts ...grpc.CallOption) (*ShutdownResponse, error)
}

GuestServiceClient is the client API for GuestService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

GuestService provides remote operations in guest VMs

type GuestServiceServer

type GuestServiceServer interface {
	// Exec executes a command with bidirectional streaming
	Exec(grpc.BidiStreamingServer[ExecRequest, ExecResponse]) error
	// CopyToGuest streams file data to the guest filesystem
	CopyToGuest(grpc.ClientStreamingServer[CopyToGuestRequest, CopyToGuestResponse]) error
	// CopyFromGuest streams file data from the guest filesystem
	CopyFromGuest(*CopyFromGuestRequest, grpc.ServerStreamingServer[CopyFromGuestResponse]) error
	// StatPath returns information about a path in the guest filesystem
	StatPath(context.Context, *StatPathRequest) (*StatPathResponse, error)
	// Shutdown requests graceful VM shutdown by signaling init (PID 1)
	Shutdown(context.Context, *ShutdownRequest) (*ShutdownResponse, error)
	// contains filtered or unexported methods
}

GuestServiceServer is the server API for GuestService service. All implementations must embed UnimplementedGuestServiceServer for forward compatibility.

GuestService provides remote operations in guest VMs

type GuestService_CopyFromGuestClient

type GuestService_CopyFromGuestClient = grpc.ServerStreamingClient[CopyFromGuestResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type GuestService_CopyFromGuestServer

type GuestService_CopyFromGuestServer = grpc.ServerStreamingServer[CopyFromGuestResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type GuestService_CopyToGuestClient

type GuestService_CopyToGuestClient = grpc.ClientStreamingClient[CopyToGuestRequest, CopyToGuestResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type GuestService_CopyToGuestServer

type GuestService_CopyToGuestServer = grpc.ClientStreamingServer[CopyToGuestRequest, CopyToGuestResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type GuestService_ExecClient

type GuestService_ExecClient = grpc.BidiStreamingClient[ExecRequest, ExecResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type GuestService_ExecServer

type GuestService_ExecServer = grpc.BidiStreamingServer[ExecRequest, ExecResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type Metrics

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

Metrics holds the metrics instruments for guest operations.

var GuestMetrics *Metrics

GuestMetrics is the global metrics instance for the guest package. Set this via SetMetrics() during application initialization.

func NewMetrics

func NewMetrics(meter metric.Meter) (*Metrics, error)

NewMetrics creates guest metrics instruments. If meter is nil, returns nil (metrics disabled).

func (*Metrics) RecordCpSession

func (m *Metrics) RecordCpSession(ctx context.Context, start time.Time, direction string, success bool, bytesTransferred int64)

RecordCpSession records metrics for a completed cp (copy) session. direction should be "to" (copy to instance) or "from" (copy from instance).

func (*Metrics) RecordExecSession

func (m *Metrics) RecordExecSession(ctx context.Context, start time.Time, exitCode int, bytesSent, bytesReceived int64)

RecordExecSession records metrics for a completed exec session.

type ShutdownRequest added in v0.0.6

type ShutdownRequest struct {
	Signal int32 `protobuf:"varint,1,opt,name=signal,proto3" json:"signal,omitempty"` // Signal to send to init (PID 1), 0 = SIGTERM (default)
	// contains filtered or unexported fields
}

ShutdownRequest requests graceful VM shutdown

func (*ShutdownRequest) Descriptor deprecated added in v0.0.6

func (*ShutdownRequest) Descriptor() ([]byte, []int)

Deprecated: Use ShutdownRequest.ProtoReflect.Descriptor instead.

func (*ShutdownRequest) GetSignal added in v0.0.6

func (x *ShutdownRequest) GetSignal() int32

func (*ShutdownRequest) ProtoMessage added in v0.0.6

func (*ShutdownRequest) ProtoMessage()

func (*ShutdownRequest) ProtoReflect added in v0.0.6

func (x *ShutdownRequest) ProtoReflect() protoreflect.Message

func (*ShutdownRequest) Reset added in v0.0.6

func (x *ShutdownRequest) Reset()

func (*ShutdownRequest) String added in v0.0.6

func (x *ShutdownRequest) String() string

type ShutdownResponse added in v0.0.6

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

ShutdownResponse acknowledges the shutdown request

func (*ShutdownResponse) Descriptor deprecated added in v0.0.6

func (*ShutdownResponse) Descriptor() ([]byte, []int)

Deprecated: Use ShutdownResponse.ProtoReflect.Descriptor instead.

func (*ShutdownResponse) ProtoMessage added in v0.0.6

func (*ShutdownResponse) ProtoMessage()

func (*ShutdownResponse) ProtoReflect added in v0.0.6

func (x *ShutdownResponse) ProtoReflect() protoreflect.Message

func (*ShutdownResponse) Reset added in v0.0.6

func (x *ShutdownResponse) Reset()

func (*ShutdownResponse) String added in v0.0.6

func (x *ShutdownResponse) String() string

type StatPathRequest

type StatPathRequest struct {
	Path        string `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`                                   // Path to stat
	FollowLinks bool   `protobuf:"varint,2,opt,name=follow_links,json=followLinks,proto3" json:"follow_links,omitempty"` // Follow symbolic links
	// contains filtered or unexported fields
}

StatPathRequest requests information about a path

func (*StatPathRequest) Descriptor deprecated

func (*StatPathRequest) Descriptor() ([]byte, []int)

Deprecated: Use StatPathRequest.ProtoReflect.Descriptor instead.

func (x *StatPathRequest) GetFollowLinks() bool

func (*StatPathRequest) GetPath

func (x *StatPathRequest) GetPath() string

func (*StatPathRequest) ProtoMessage

func (*StatPathRequest) ProtoMessage()

func (*StatPathRequest) ProtoReflect added in v0.0.6

func (x *StatPathRequest) ProtoReflect() protoreflect.Message

func (*StatPathRequest) Reset

func (x *StatPathRequest) Reset()

func (*StatPathRequest) String

func (x *StatPathRequest) String() string

type StatPathResponse

type StatPathResponse struct {
	Exists     bool   `protobuf:"varint,1,opt,name=exists,proto3" json:"exists,omitempty"`                          // Whether the path exists
	IsDir      bool   `protobuf:"varint,2,opt,name=is_dir,json=isDir,proto3" json:"is_dir,omitempty"`               // True if this is a directory
	IsFile     bool   `protobuf:"varint,3,opt,name=is_file,json=isFile,proto3" json:"is_file,omitempty"`            // True if this is a regular file
	IsSymlink  bool   `protobuf:"varint,4,opt,name=is_symlink,json=isSymlink,proto3" json:"is_symlink,omitempty"`   // True if this is a symbolic link (only if follow_links=false)
	LinkTarget string `protobuf:"bytes,5,opt,name=link_target,json=linkTarget,proto3" json:"link_target,omitempty"` // Symlink target (if is_symlink)
	Mode       uint32 `protobuf:"varint,6,opt,name=mode,proto3" json:"mode,omitempty"`                              // File mode (permissions)
	Size       int64  `protobuf:"varint,7,opt,name=size,proto3" json:"size,omitempty"`                              // File size
	Error      string `protobuf:"bytes,8,opt,name=error,proto3" json:"error,omitempty"`                             // Error message if stat failed (e.g., permission denied)
	// contains filtered or unexported fields
}

StatPathResponse contains information about a path

func (*StatPathResponse) Descriptor deprecated

func (*StatPathResponse) Descriptor() ([]byte, []int)

Deprecated: Use StatPathResponse.ProtoReflect.Descriptor instead.

func (*StatPathResponse) GetError

func (x *StatPathResponse) GetError() string

func (*StatPathResponse) GetExists

func (x *StatPathResponse) GetExists() bool

func (*StatPathResponse) GetIsDir

func (x *StatPathResponse) GetIsDir() bool

func (*StatPathResponse) GetIsFile

func (x *StatPathResponse) GetIsFile() bool
func (x *StatPathResponse) GetIsSymlink() bool

func (*StatPathResponse) GetLinkTarget

func (x *StatPathResponse) GetLinkTarget() string

func (*StatPathResponse) GetMode

func (x *StatPathResponse) GetMode() uint32

func (*StatPathResponse) GetSize

func (x *StatPathResponse) GetSize() int64

func (*StatPathResponse) ProtoMessage

func (*StatPathResponse) ProtoMessage()

func (*StatPathResponse) ProtoReflect added in v0.0.6

func (x *StatPathResponse) ProtoReflect() protoreflect.Message

func (*StatPathResponse) Reset

func (x *StatPathResponse) Reset()

func (*StatPathResponse) String

func (x *StatPathResponse) String() string

type UnimplementedGuestServiceServer

type UnimplementedGuestServiceServer struct{}

UnimplementedGuestServiceServer must be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedGuestServiceServer) Exec

func (UnimplementedGuestServiceServer) Shutdown added in v0.0.6

func (UnimplementedGuestServiceServer) StatPath

type UnsafeGuestServiceServer

type UnsafeGuestServiceServer interface {
	// contains filtered or unexported methods
}

UnsafeGuestServiceServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to GuestServiceServer will result in compilation errors.

type WindowSize added in v0.0.6

type WindowSize struct {
	Rows uint32 `protobuf:"varint,1,opt,name=rows,proto3" json:"rows,omitempty"`
	Cols uint32 `protobuf:"varint,2,opt,name=cols,proto3" json:"cols,omitempty"`
	// contains filtered or unexported fields
}

WindowSize represents terminal window dimensions for resize events

func (*WindowSize) Descriptor deprecated added in v0.0.6

func (*WindowSize) Descriptor() ([]byte, []int)

Deprecated: Use WindowSize.ProtoReflect.Descriptor instead.

func (*WindowSize) GetCols added in v0.0.6

func (x *WindowSize) GetCols() uint32

func (*WindowSize) GetRows added in v0.0.6

func (x *WindowSize) GetRows() uint32

func (*WindowSize) ProtoMessage added in v0.0.6

func (*WindowSize) ProtoMessage()

func (*WindowSize) ProtoReflect added in v0.0.6

func (x *WindowSize) ProtoReflect() protoreflect.Message

func (*WindowSize) Reset added in v0.0.6

func (x *WindowSize) Reset()

func (*WindowSize) String added in v0.0.6

func (x *WindowSize) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL