Documentation
¶
Overview ¶
Package vzdctl is the control channel between the clawk CLI and a running vzd daemon: a tiny HTTP API served over a unix socket in the sandbox's VM dir. It exists so network-policy edits apply to the live VM (no down/up cycle) and so the CLI can read the daemon's denial ledger.
Index ¶
- Constants
- Variables
- func SocketPath(vmDir string) string
- type Client
- func (c *Client) AllowAll(ctx context.Context, d time.Duration) error
- func (c *Client) Decide(ctx context.Context, id, action, scope string) error
- func (c *Client) Denials(ctx context.Context) ([]netfilter.Denial, error)
- func (c *Client) Events(ctx context.Context) (<-chan netfilter.Event, error)
- func (c *Client) Lifecycle(ctx context.Context) (LifecycleState, error)
- func (c *Client) Pause(ctx context.Context) error
- func (c *Client) Pending(ctx context.Context) ([]netfilter.Pending, error)
- func (c *Client) Reload(ctx context.Context) error
- func (c *Client) ReloadForwards(ctx context.Context) error
- func (c *Client) ReloadSerials(ctx context.Context) error
- func (c *Client) Resume(ctx context.Context) error
- func (c *Client) Suspend(ctx context.Context) error
- type Handlers
- type LifecycleHandlers
- type LifecycleState
- type Server
Constants ¶
const ( LifecycleBooting = "booting" LifecycleRunning = "running" LifecyclePaused = "paused" )
Lifecycle state values for LifecycleState.State.
const SocketName = "control.sock"
SocketName is the control socket's filename inside a sandbox's VM dir, next to vz.pid and agent.sock.
Variables ¶
var ErrLifecycleUnsupported = errors.New("daemon does not support lifecycle control (restart the sandbox to upgrade its daemon)")
ErrLifecycleUnsupported reports that the daemon answered but has no lifecycle endpoints — it predates lifecycle control. Callers check with errors.Is and suggest a sandbox restart.
var ErrNotRunning = errors.New("control socket not available (sandbox not running?)")
ErrNotRunning reports that no daemon is listening — the sandbox is down (or predates the control socket). Callers check with errors.Is.
var ErrReverseForwardsUnsupported = errors.New("daemon does not support reverse port forwarding")
ErrReverseForwardsUnsupported reports that the daemon answered but has no reverse-forward endpoint — either it predates the feature or its backend has no host-side vsock listener (firecracker). Callers check with errors.Is.
var ErrSerialUnsupported = errors.New("daemon does not support serial forwarding")
ErrSerialUnsupported reports that the daemon answered but has no serial endpoint — either it predates the feature or its backend has no host-side vsock listener (firecracker). Callers check with errors.Is.
Functions ¶
func SocketPath ¶
SocketPath returns the control socket path for a sandbox's VM dir.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to a vzd control socket. The zero value is not usable; build one with NewClient.
func NewClient ¶
NewClient returns a client for the control socket at path. It does not dial; connection errors surface on the first call.
func (*Client) AllowAll ¶
AllowAll opens the time-boxed allow-all bypass for d (every destination passes until it elapses) and releases any currently held connections. A non-positive d clears the bypass.
func (*Client) Decide ¶
Decide resolves a held connection by id. action is "allow" or "deny"; scope is "once", "session", or "always". It returns ErrUnknownDecision (wrapped) when the hold is no longer outstanding.
func (*Client) Events ¶
Events streams gate events (pending/resolved) over the control socket. The returned channel is closed when ctx is cancelled or the stream ends; the reader goroutine's lifetime is bound to ctx. Connection errors surface from Events itself, not the channel.
func (*Client) Lifecycle ¶
func (c *Client) Lifecycle(ctx context.Context) (LifecycleState, error)
Lifecycle fetches the VM's live lifecycle snapshot.
func (*Client) Reload ¶
Reload asks the daemon to re-read the sandbox's network policy from the store and apply it to the live allow list.
func (*Client) ReloadForwards ¶ added in v0.3.0
ReloadForwards asks the daemon to re-read the sandbox's reverse port forwards from the store and push them to the in-guest agent.
func (*Client) ReloadSerials ¶ added in v0.4.0
ReloadSerials asks the daemon to re-read the sandbox's serial devices from the store and push them to the in-guest agent.
type Handlers ¶
type Handlers struct {
// Denials returns the current denial ledger snapshot.
Denials func() []netfilter.Denial
// Reload re-reads the sandbox's network policy from the store and
// applies it to the live allow list.
Reload func() error
// ReloadForwards, if non-nil, re-reads the sandbox's reverse port
// forwards from the store and pushes them to the in-guest agent. Nil
// on backends with no vsock listener (firecracker), where the endpoint
// reports 404 and the client maps it to
// ErrReverseForwardsUnsupported.
ReloadForwards func() error
// ReloadSerials, if non-nil, re-reads the sandbox's serial devices from
// the store and pushes them to the in-guest agent. Nil on backends with
// no vsock listener (firecracker), where the endpoint reports 404 and
// the client maps it to ErrSerialUnsupported.
ReloadSerials func() error
// Gate, if non-nil, powers the interactive allow/deny endpoints
// (/v1/events, /v1/decide, /v1/pending). When nil those endpoints
// report 404 and the daemon serves only the denial ledger + reload.
Gate *netfilter.Gate
// Lifecycle, if non-nil, powers the VM lifecycle endpoints
// (/v1/lifecycle, /v1/pause, /v1/resume, /v1/suspend). When nil those
// endpoints report 404, which the client maps to
// ErrLifecycleUnsupported — the daemon predates lifecycle control.
Lifecycle *LifecycleHandlers
}
Handlers are the daemon-side callbacks the server dispatches to. Denials and Reload are required; Gate is optional.
type LifecycleHandlers ¶
type LifecycleHandlers struct {
// State reports the VM's live lifecycle snapshot.
State func() LifecycleState
// Pause suspends the guest's vCPUs in place (memory stays resident).
Pause func() error
// Resume restarts the vCPUs after a Pause.
Resume func() error
// Suspend saves memory + device state to disk and stops the VM without
// resuming it; the daemon exits shortly after. Blocking — the response
// is written only once the state file is on disk.
Suspend func() error
}
LifecycleHandlers are the daemon-side callbacks behind the VM lifecycle endpoints. State is required when the struct is set; the verbs may be nil individually (each nil verb reports 404).
type LifecycleState ¶
type LifecycleState struct {
// State is "booting" (machine not constructed yet), "running", or
// "paused".
State string `json:"state"`
// Restored reports whether this boot restored the guest from a
// suspend-to-disk state file rather than cold-booting it. Callers use
// it to skip boot-time hooks whose effects survived inside the guest.
Restored bool `json:"restored"`
}
LifecycleState is the wire shape of GET /v1/lifecycle.
Source Files