guest

package
v0.0.5 Latest Latest
Warning

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

Go to latest
Published: Jan 16, 2026 License: MIT Imports: 23 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"
)

Variables

View Source
var GuestService_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "guest.GuestService",
	HandlerType: (*GuestServiceServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "StatPath",
			Handler:    _GuestService_StatPath_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.

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"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

CopyFromGuestEnd signals the end of a file or transfer

func (*CopyFromGuestEnd) Descriptor

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

func (*CopyFromGuestEnd) GetFinal

func (m *CopyFromGuestEnd) GetFinal() bool

func (*CopyFromGuestEnd) ProtoMessage

func (*CopyFromGuestEnd) ProtoMessage()

func (*CopyFromGuestEnd) Reset

func (m *CopyFromGuestEnd) Reset()

func (*CopyFromGuestEnd) String

func (m *CopyFromGuestEnd) String() string

func (*CopyFromGuestEnd) XXX_DiscardUnknown

func (m *CopyFromGuestEnd) XXX_DiscardUnknown()

func (*CopyFromGuestEnd) XXX_Marshal

func (m *CopyFromGuestEnd) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyFromGuestEnd) XXX_Merge

func (m *CopyFromGuestEnd) XXX_Merge(src proto.Message)

func (*CopyFromGuestEnd) XXX_Size

func (m *CopyFromGuestEnd) XXX_Size() int

func (*CopyFromGuestEnd) XXX_Unmarshal

func (m *CopyFromGuestEnd) XXX_Unmarshal(b []byte) error

type CopyFromGuestError

type CopyFromGuestError struct {
	Message              string   `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
	Path                 string   `protobuf:"bytes,2,opt,name=path,proto3" json:"path,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

CopyFromGuestError reports an error during copy

func (*CopyFromGuestError) Descriptor

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

func (*CopyFromGuestError) GetMessage

func (m *CopyFromGuestError) GetMessage() string

func (*CopyFromGuestError) GetPath

func (m *CopyFromGuestError) GetPath() string

func (*CopyFromGuestError) ProtoMessage

func (*CopyFromGuestError) ProtoMessage()

func (*CopyFromGuestError) Reset

func (m *CopyFromGuestError) Reset()

func (*CopyFromGuestError) String

func (m *CopyFromGuestError) String() string

func (*CopyFromGuestError) XXX_DiscardUnknown

func (m *CopyFromGuestError) XXX_DiscardUnknown()

func (*CopyFromGuestError) XXX_Marshal

func (m *CopyFromGuestError) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyFromGuestError) XXX_Merge

func (m *CopyFromGuestError) XXX_Merge(src proto.Message)

func (*CopyFromGuestError) XXX_Size

func (m *CopyFromGuestError) XXX_Size() int

func (*CopyFromGuestError) XXX_Unmarshal

func (m *CopyFromGuestError) XXX_Unmarshal(b []byte) error

type CopyFromGuestHeader

type CopyFromGuestHeader struct {
	Path                 string   `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
	Mode                 uint32   `protobuf:"varint,2,opt,name=mode,proto3" json:"mode,omitempty"`
	IsDir                bool     `protobuf:"varint,3,opt,name=is_dir,json=isDir,proto3" json:"is_dir,omitempty"`
	IsSymlink            bool     `protobuf:"varint,4,opt,name=is_symlink,json=isSymlink,proto3" json:"is_symlink,omitempty"`
	LinkTarget           string   `protobuf:"bytes,5,opt,name=link_target,json=linkTarget,proto3" json:"link_target,omitempty"`
	Size                 int64    `protobuf:"varint,6,opt,name=size,proto3" json:"size,omitempty"`
	Mtime                int64    `protobuf:"varint,7,opt,name=mtime,proto3" json:"mtime,omitempty"`
	Uid                  uint32   `protobuf:"varint,8,opt,name=uid,proto3" json:"uid,omitempty"`
	Gid                  uint32   `protobuf:"varint,9,opt,name=gid,proto3" json:"gid,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

CopyFromGuestHeader provides metadata about a file being copied

func (*CopyFromGuestHeader) Descriptor

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

func (*CopyFromGuestHeader) GetGid

func (m *CopyFromGuestHeader) GetGid() uint32

func (*CopyFromGuestHeader) GetIsDir

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

func (*CopyFromGuestHeader) GetLinkTarget

func (m *CopyFromGuestHeader) GetLinkTarget() string

func (*CopyFromGuestHeader) GetMode

func (m *CopyFromGuestHeader) GetMode() uint32

func (*CopyFromGuestHeader) GetMtime

func (m *CopyFromGuestHeader) GetMtime() int64

func (*CopyFromGuestHeader) GetPath

func (m *CopyFromGuestHeader) GetPath() string

func (*CopyFromGuestHeader) GetSize

func (m *CopyFromGuestHeader) GetSize() int64

func (*CopyFromGuestHeader) GetUid

func (m *CopyFromGuestHeader) GetUid() uint32

func (*CopyFromGuestHeader) ProtoMessage

func (*CopyFromGuestHeader) ProtoMessage()

func (*CopyFromGuestHeader) Reset

func (m *CopyFromGuestHeader) Reset()

func (*CopyFromGuestHeader) String

func (m *CopyFromGuestHeader) String() string

func (*CopyFromGuestHeader) XXX_DiscardUnknown

func (m *CopyFromGuestHeader) XXX_DiscardUnknown()

func (*CopyFromGuestHeader) XXX_Marshal

func (m *CopyFromGuestHeader) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyFromGuestHeader) XXX_Merge

func (m *CopyFromGuestHeader) XXX_Merge(src proto.Message)

func (*CopyFromGuestHeader) XXX_Size

func (m *CopyFromGuestHeader) XXX_Size() int

func (*CopyFromGuestHeader) XXX_Unmarshal

func (m *CopyFromGuestHeader) XXX_Unmarshal(b []byte) error

type CopyFromGuestRequest

type CopyFromGuestRequest struct {
	Path                 string   `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
	FollowLinks          bool     `protobuf:"varint,2,opt,name=follow_links,json=followLinks,proto3" json:"follow_links,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

CopyFromGuestRequest initiates a copy-from-guest operation

func (*CopyFromGuestRequest) Descriptor

func (*CopyFromGuestRequest) Descriptor() ([]byte, []int)
func (m *CopyFromGuestRequest) GetFollowLinks() bool

func (*CopyFromGuestRequest) GetPath

func (m *CopyFromGuestRequest) GetPath() string

func (*CopyFromGuestRequest) ProtoMessage

func (*CopyFromGuestRequest) ProtoMessage()

func (*CopyFromGuestRequest) Reset

func (m *CopyFromGuestRequest) Reset()

func (*CopyFromGuestRequest) String

func (m *CopyFromGuestRequest) String() string

func (*CopyFromGuestRequest) XXX_DiscardUnknown

func (m *CopyFromGuestRequest) XXX_DiscardUnknown()

func (*CopyFromGuestRequest) XXX_Marshal

func (m *CopyFromGuestRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyFromGuestRequest) XXX_Merge

func (m *CopyFromGuestRequest) XXX_Merge(src proto.Message)

func (*CopyFromGuestRequest) XXX_Size

func (m *CopyFromGuestRequest) XXX_Size() int

func (*CopyFromGuestRequest) XXX_Unmarshal

func (m *CopyFromGuestRequest) XXX_Unmarshal(b []byte) error

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"`
	XXX_NoUnkeyedLiteral struct{}                         `json:"-"`
	XXX_unrecognized     []byte                           `json:"-"`
	XXX_sizecache        int32                            `json:"-"`
}

CopyFromGuestResponse streams file data from guest

func (*CopyFromGuestResponse) Descriptor

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

func (*CopyFromGuestResponse) GetData

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

func (*CopyFromGuestResponse) GetEnd

func (*CopyFromGuestResponse) GetError

func (*CopyFromGuestResponse) GetHeader

func (*CopyFromGuestResponse) GetResponse

func (m *CopyFromGuestResponse) GetResponse() isCopyFromGuestResponse_Response

func (*CopyFromGuestResponse) ProtoMessage

func (*CopyFromGuestResponse) ProtoMessage()

func (*CopyFromGuestResponse) Reset

func (m *CopyFromGuestResponse) Reset()

func (*CopyFromGuestResponse) String

func (m *CopyFromGuestResponse) String() string

func (*CopyFromGuestResponse) XXX_DiscardUnknown

func (m *CopyFromGuestResponse) XXX_DiscardUnknown()

func (*CopyFromGuestResponse) XXX_Marshal

func (m *CopyFromGuestResponse) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyFromGuestResponse) XXX_Merge

func (m *CopyFromGuestResponse) XXX_Merge(src proto.Message)

func (*CopyFromGuestResponse) XXX_OneofWrappers

func (*CopyFromGuestResponse) XXX_OneofWrappers() []interface{}

XXX_OneofWrappers is for the internal use of the proto package.

func (*CopyFromGuestResponse) XXX_Size

func (m *CopyFromGuestResponse) XXX_Size() int

func (*CopyFromGuestResponse) XXX_Unmarshal

func (m *CopyFromGuestResponse) XXX_Unmarshal(b []byte) error

type CopyFromGuestResponse_Data

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

type CopyFromGuestResponse_End

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

type CopyFromGuestResponse_Error

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

type CopyFromGuestResponse_Header

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

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 {
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

CopyToGuestEnd signals the end of a file transfer

func (*CopyToGuestEnd) Descriptor

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

func (*CopyToGuestEnd) ProtoMessage

func (*CopyToGuestEnd) ProtoMessage()

func (*CopyToGuestEnd) Reset

func (m *CopyToGuestEnd) Reset()

func (*CopyToGuestEnd) String

func (m *CopyToGuestEnd) String() string

func (*CopyToGuestEnd) XXX_DiscardUnknown

func (m *CopyToGuestEnd) XXX_DiscardUnknown()

func (*CopyToGuestEnd) XXX_Marshal

func (m *CopyToGuestEnd) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyToGuestEnd) XXX_Merge

func (m *CopyToGuestEnd) XXX_Merge(src proto.Message)

func (*CopyToGuestEnd) XXX_Size

func (m *CopyToGuestEnd) XXX_Size() int

func (*CopyToGuestEnd) XXX_Unmarshal

func (m *CopyToGuestEnd) XXX_Unmarshal(b []byte) error

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"`
	XXX_NoUnkeyedLiteral struct{}                     `json:"-"`
	XXX_unrecognized     []byte                       `json:"-"`
	XXX_sizecache        int32                        `json:"-"`
}

CopyToGuestRequest represents messages for copying files to guest

func (*CopyToGuestRequest) Descriptor

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

func (*CopyToGuestRequest) GetData

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

func (*CopyToGuestRequest) GetEnd

func (m *CopyToGuestRequest) GetEnd() *CopyToGuestEnd

func (*CopyToGuestRequest) GetRequest

func (m *CopyToGuestRequest) GetRequest() isCopyToGuestRequest_Request

func (*CopyToGuestRequest) GetStart

func (m *CopyToGuestRequest) GetStart() *CopyToGuestStart

func (*CopyToGuestRequest) ProtoMessage

func (*CopyToGuestRequest) ProtoMessage()

func (*CopyToGuestRequest) Reset

func (m *CopyToGuestRequest) Reset()

func (*CopyToGuestRequest) String

func (m *CopyToGuestRequest) String() string

func (*CopyToGuestRequest) XXX_DiscardUnknown

func (m *CopyToGuestRequest) XXX_DiscardUnknown()

func (*CopyToGuestRequest) XXX_Marshal

func (m *CopyToGuestRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyToGuestRequest) XXX_Merge

func (m *CopyToGuestRequest) XXX_Merge(src proto.Message)

func (*CopyToGuestRequest) XXX_OneofWrappers

func (*CopyToGuestRequest) XXX_OneofWrappers() []interface{}

XXX_OneofWrappers is for the internal use of the proto package.

func (*CopyToGuestRequest) XXX_Size

func (m *CopyToGuestRequest) XXX_Size() int

func (*CopyToGuestRequest) XXX_Unmarshal

func (m *CopyToGuestRequest) XXX_Unmarshal(b []byte) error

type CopyToGuestRequest_Data

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

type CopyToGuestRequest_End

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

type CopyToGuestRequest_Start

type CopyToGuestRequest_Start struct {
	Start *CopyToGuestStart `protobuf:"bytes,1,opt,name=start,proto3,oneof"`
}

type CopyToGuestResponse

type CopyToGuestResponse struct {
	Success              bool     `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	Error                string   `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`
	BytesWritten         int64    `protobuf:"varint,3,opt,name=bytes_written,json=bytesWritten,proto3" json:"bytes_written,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

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

func (*CopyToGuestResponse) Descriptor

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

func (*CopyToGuestResponse) GetBytesWritten

func (m *CopyToGuestResponse) GetBytesWritten() int64

func (*CopyToGuestResponse) GetError

func (m *CopyToGuestResponse) GetError() string

func (*CopyToGuestResponse) GetSuccess

func (m *CopyToGuestResponse) GetSuccess() bool

func (*CopyToGuestResponse) ProtoMessage

func (*CopyToGuestResponse) ProtoMessage()

func (*CopyToGuestResponse) Reset

func (m *CopyToGuestResponse) Reset()

func (*CopyToGuestResponse) String

func (m *CopyToGuestResponse) String() string

func (*CopyToGuestResponse) XXX_DiscardUnknown

func (m *CopyToGuestResponse) XXX_DiscardUnknown()

func (*CopyToGuestResponse) XXX_Marshal

func (m *CopyToGuestResponse) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyToGuestResponse) XXX_Merge

func (m *CopyToGuestResponse) XXX_Merge(src proto.Message)

func (*CopyToGuestResponse) XXX_Size

func (m *CopyToGuestResponse) XXX_Size() int

func (*CopyToGuestResponse) XXX_Unmarshal

func (m *CopyToGuestResponse) XXX_Unmarshal(b []byte) error

type CopyToGuestStart

type CopyToGuestStart struct {
	Path                 string   `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
	Mode                 uint32   `protobuf:"varint,2,opt,name=mode,proto3" json:"mode,omitempty"`
	IsDir                bool     `protobuf:"varint,3,opt,name=is_dir,json=isDir,proto3" json:"is_dir,omitempty"`
	Size                 int64    `protobuf:"varint,4,opt,name=size,proto3" json:"size,omitempty"`
	Mtime                int64    `protobuf:"varint,5,opt,name=mtime,proto3" json:"mtime,omitempty"`
	Uid                  uint32   `protobuf:"varint,6,opt,name=uid,proto3" json:"uid,omitempty"`
	Gid                  uint32   `protobuf:"varint,7,opt,name=gid,proto3" json:"gid,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

CopyToGuestStart initiates a copy-to-guest operation

func (*CopyToGuestStart) Descriptor

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

func (*CopyToGuestStart) GetGid

func (m *CopyToGuestStart) GetGid() uint32

func (*CopyToGuestStart) GetIsDir

func (m *CopyToGuestStart) GetIsDir() bool

func (*CopyToGuestStart) GetMode

func (m *CopyToGuestStart) GetMode() uint32

func (*CopyToGuestStart) GetMtime

func (m *CopyToGuestStart) GetMtime() int64

func (*CopyToGuestStart) GetPath

func (m *CopyToGuestStart) GetPath() string

func (*CopyToGuestStart) GetSize

func (m *CopyToGuestStart) GetSize() int64

func (*CopyToGuestStart) GetUid

func (m *CopyToGuestStart) GetUid() uint32

func (*CopyToGuestStart) ProtoMessage

func (*CopyToGuestStart) ProtoMessage()

func (*CopyToGuestStart) Reset

func (m *CopyToGuestStart) Reset()

func (*CopyToGuestStart) String

func (m *CopyToGuestStart) String() string

func (*CopyToGuestStart) XXX_DiscardUnknown

func (m *CopyToGuestStart) XXX_DiscardUnknown()

func (*CopyToGuestStart) XXX_Marshal

func (m *CopyToGuestStart) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*CopyToGuestStart) XXX_Merge

func (m *CopyToGuestStart) XXX_Merge(src proto.Message)

func (*CopyToGuestStart) XXX_Size

func (m *CopyToGuestStart) XXX_Size() int

func (*CopyToGuestStart) XXX_Unmarshal

func (m *CopyToGuestStart) XXX_Unmarshal(b []byte) error

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)
}

ExecOptions configures command execution

type ExecRequest

type ExecRequest struct {
	// Types that are valid to be assigned to Request:
	//
	//	*ExecRequest_Start
	//	*ExecRequest_Stdin
	Request              isExecRequest_Request `protobuf_oneof:"request"`
	XXX_NoUnkeyedLiteral struct{}              `json:"-"`
	XXX_unrecognized     []byte                `json:"-"`
	XXX_sizecache        int32                 `json:"-"`
}

ExecRequest represents messages from client to server

func (*ExecRequest) Descriptor

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

func (*ExecRequest) GetRequest

func (m *ExecRequest) GetRequest() isExecRequest_Request

func (*ExecRequest) GetStart

func (m *ExecRequest) GetStart() *ExecStart

func (*ExecRequest) GetStdin

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

func (*ExecRequest) ProtoMessage

func (*ExecRequest) ProtoMessage()

func (*ExecRequest) Reset

func (m *ExecRequest) Reset()

func (*ExecRequest) String

func (m *ExecRequest) String() string

func (*ExecRequest) XXX_DiscardUnknown

func (m *ExecRequest) XXX_DiscardUnknown()

func (*ExecRequest) XXX_Marshal

func (m *ExecRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ExecRequest) XXX_Merge

func (m *ExecRequest) XXX_Merge(src proto.Message)

func (*ExecRequest) XXX_OneofWrappers

func (*ExecRequest) XXX_OneofWrappers() []interface{}

XXX_OneofWrappers is for the internal use of the proto package.

func (*ExecRequest) XXX_Size

func (m *ExecRequest) XXX_Size() int

func (*ExecRequest) XXX_Unmarshal

func (m *ExecRequest) XXX_Unmarshal(b []byte) error

type ExecRequest_Start

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

type ExecRequest_Stdin

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

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"`
	XXX_NoUnkeyedLiteral struct{}                `json:"-"`
	XXX_unrecognized     []byte                  `json:"-"`
	XXX_sizecache        int32                   `json:"-"`
}

ExecResponse represents messages from server to client

func (*ExecResponse) Descriptor

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

func (*ExecResponse) GetExitCode

func (m *ExecResponse) GetExitCode() int32

func (*ExecResponse) GetResponse

func (m *ExecResponse) GetResponse() isExecResponse_Response

func (*ExecResponse) GetStderr

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

func (*ExecResponse) GetStdout

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

func (*ExecResponse) ProtoMessage

func (*ExecResponse) ProtoMessage()

func (*ExecResponse) Reset

func (m *ExecResponse) Reset()

func (*ExecResponse) String

func (m *ExecResponse) String() string

func (*ExecResponse) XXX_DiscardUnknown

func (m *ExecResponse) XXX_DiscardUnknown()

func (*ExecResponse) XXX_Marshal

func (m *ExecResponse) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ExecResponse) XXX_Merge

func (m *ExecResponse) XXX_Merge(src proto.Message)

func (*ExecResponse) XXX_OneofWrappers

func (*ExecResponse) XXX_OneofWrappers() []interface{}

XXX_OneofWrappers is for the internal use of the proto package.

func (*ExecResponse) XXX_Size

func (m *ExecResponse) XXX_Size() int

func (*ExecResponse) XXX_Unmarshal

func (m *ExecResponse) XXX_Unmarshal(b []byte) error

type ExecResponse_ExitCode

type ExecResponse_ExitCode struct {
	ExitCode int32 `protobuf:"varint,3,opt,name=exit_code,json=exitCode,proto3,oneof"`
}

type ExecResponse_Stderr

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

type ExecResponse_Stdout

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

type ExecStart

type ExecStart struct {
	Command              []string          `protobuf:"bytes,1,rep,name=command,proto3" json:"command,omitempty"`
	Tty                  bool              `protobuf:"varint,2,opt,name=tty,proto3" json:"tty,omitempty"`
	Env                  map[string]string `` /* 147-byte string literal not displayed */
	Cwd                  string            `protobuf:"bytes,4,opt,name=cwd,proto3" json:"cwd,omitempty"`
	TimeoutSeconds       int32             `protobuf:"varint,5,opt,name=timeout_seconds,json=timeoutSeconds,proto3" json:"timeout_seconds,omitempty"`
	XXX_NoUnkeyedLiteral struct{}          `json:"-"`
	XXX_unrecognized     []byte            `json:"-"`
	XXX_sizecache        int32             `json:"-"`
}

ExecStart initiates command execution

func (*ExecStart) Descriptor

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

func (*ExecStart) GetCommand

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

func (*ExecStart) GetCwd

func (m *ExecStart) GetCwd() string

func (*ExecStart) GetEnv

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

func (*ExecStart) GetTimeoutSeconds

func (m *ExecStart) GetTimeoutSeconds() int32

func (*ExecStart) GetTty

func (m *ExecStart) GetTty() bool

func (*ExecStart) ProtoMessage

func (*ExecStart) ProtoMessage()

func (*ExecStart) Reset

func (m *ExecStart) Reset()

func (*ExecStart) String

func (m *ExecStart) String() string

func (*ExecStart) XXX_DiscardUnknown

func (m *ExecStart) XXX_DiscardUnknown()

func (*ExecStart) XXX_Marshal

func (m *ExecStart) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ExecStart) XXX_Merge

func (m *ExecStart) XXX_Merge(src proto.Message)

func (*ExecStart) XXX_Size

func (m *ExecStart) XXX_Size() int

func (*ExecStart) XXX_Unmarshal

func (m *ExecStart) XXX_Unmarshal(b []byte) error

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)
}

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)
	// 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 StatPathRequest

type StatPathRequest struct {
	Path                 string   `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
	FollowLinks          bool     `protobuf:"varint,2,opt,name=follow_links,json=followLinks,proto3" json:"follow_links,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

StatPathRequest requests information about a path

func (*StatPathRequest) Descriptor

func (*StatPathRequest) Descriptor() ([]byte, []int)
func (m *StatPathRequest) GetFollowLinks() bool

func (*StatPathRequest) GetPath

func (m *StatPathRequest) GetPath() string

func (*StatPathRequest) ProtoMessage

func (*StatPathRequest) ProtoMessage()

func (*StatPathRequest) Reset

func (m *StatPathRequest) Reset()

func (*StatPathRequest) String

func (m *StatPathRequest) String() string

func (*StatPathRequest) XXX_DiscardUnknown

func (m *StatPathRequest) XXX_DiscardUnknown()

func (*StatPathRequest) XXX_Marshal

func (m *StatPathRequest) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*StatPathRequest) XXX_Merge

func (m *StatPathRequest) XXX_Merge(src proto.Message)

func (*StatPathRequest) XXX_Size

func (m *StatPathRequest) XXX_Size() int

func (*StatPathRequest) XXX_Unmarshal

func (m *StatPathRequest) XXX_Unmarshal(b []byte) error

type StatPathResponse

type StatPathResponse struct {
	Exists               bool     `protobuf:"varint,1,opt,name=exists,proto3" json:"exists,omitempty"`
	IsDir                bool     `protobuf:"varint,2,opt,name=is_dir,json=isDir,proto3" json:"is_dir,omitempty"`
	IsFile               bool     `protobuf:"varint,3,opt,name=is_file,json=isFile,proto3" json:"is_file,omitempty"`
	IsSymlink            bool     `protobuf:"varint,4,opt,name=is_symlink,json=isSymlink,proto3" json:"is_symlink,omitempty"`
	LinkTarget           string   `protobuf:"bytes,5,opt,name=link_target,json=linkTarget,proto3" json:"link_target,omitempty"`
	Mode                 uint32   `protobuf:"varint,6,opt,name=mode,proto3" json:"mode,omitempty"`
	Size                 int64    `protobuf:"varint,7,opt,name=size,proto3" json:"size,omitempty"`
	Error                string   `protobuf:"bytes,8,opt,name=error,proto3" json:"error,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

StatPathResponse contains information about a path

func (*StatPathResponse) Descriptor

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

func (*StatPathResponse) GetError

func (m *StatPathResponse) GetError() string

func (*StatPathResponse) GetExists

func (m *StatPathResponse) GetExists() bool

func (*StatPathResponse) GetIsDir

func (m *StatPathResponse) GetIsDir() bool

func (*StatPathResponse) GetIsFile

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

func (*StatPathResponse) GetLinkTarget

func (m *StatPathResponse) GetLinkTarget() string

func (*StatPathResponse) GetMode

func (m *StatPathResponse) GetMode() uint32

func (*StatPathResponse) GetSize

func (m *StatPathResponse) GetSize() int64

func (*StatPathResponse) ProtoMessage

func (*StatPathResponse) ProtoMessage()

func (*StatPathResponse) Reset

func (m *StatPathResponse) Reset()

func (*StatPathResponse) String

func (m *StatPathResponse) String() string

func (*StatPathResponse) XXX_DiscardUnknown

func (m *StatPathResponse) XXX_DiscardUnknown()

func (*StatPathResponse) XXX_Marshal

func (m *StatPathResponse) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*StatPathResponse) XXX_Merge

func (m *StatPathResponse) XXX_Merge(src proto.Message)

func (*StatPathResponse) XXX_Size

func (m *StatPathResponse) XXX_Size() int

func (*StatPathResponse) XXX_Unmarshal

func (m *StatPathResponse) XXX_Unmarshal(b []byte) error

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) 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.

Jump to

Keyboard shortcuts

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