local

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 14 Imported by: 1

README

Proxmox Local

Status: This project is under active development. Its API may change and breaking changes are possible. Do not use it in production yet.

go-proxmox-local is a Go library for driving a Proxmox VE hypervisor from the node itself — reading /etc/pve directly and shelling out to qm / pvesh / pvecm — as a sibling to go-proxmox-rest (the REST client) and go-proxmox-pool (cluster-wide scheduling helpers).

See docs/design.md for the full design.

Projects using this module

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Proxmox® is a registered trademark of Proxmox Server Solutions GmbH.

Documentation

Overview

Package local drives a Proxmox VE hypervisor from the node itself: it reads /etc/pve directly and shells out to qm/pvesh/pvecm, as the on-node counterpart to github.com/sergelogvinov/go-proxmox-rest (the REST client).

See docs/design.md for the full design.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound is returned when no guest config exists for the
	// requested id.
	ErrNotFound = errdefs.ErrNotFound
	// ErrNoQuorum is returned when the local cluster has no quorum.
	ErrNoQuorum = errdefs.ErrNoQuorum
	// ErrNotInstalled is returned when pvecm/pvesh/qm cannot be found on
	// this node.
	ErrNotInstalled = errdefs.ErrNotInstalled
	// ErrLocked is returned when qm reports the guest config is locked by
	// another operation; retryable.
	ErrLocked = errdefs.ErrLocked
)

These are re-exports (the same values, not copies) of the sentinels internal/errdefs defines, so that an error returned by the cluster or qemu subpackages — which wrap errdefs' values directly, to avoid importing this package and cycling back — still satisfies errors.Is(err, local.ErrNotFound) etc. here.

Functions

func IsLocked

func IsLocked(err error) bool

IsLocked reports whether err indicates a guest's config is locked by another operation; callers should retry with backoff.

func IsNoQuorum

func IsNoQuorum(err error) bool

IsNoQuorum reports whether err indicates the local cluster has no quorum.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err indicates that the requested guest was not found.

Types

type Client

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

Client is the entry point for driving a Proxmox VE hypervisor from the node itself. Obtain resource-scoped handles from its Qemu()/Cluster() methods; Client itself carries only the shared configuration and the command-execution seam (see Run, ConfigDir, RunDir, ProcDir), which the cluster and qemu subpackages consume through their own Env interfaces, so that neither needs to import this package (which would cycle back to them).

func New

func New(opts ...Option) (*Client, error)

New returns a new Client. The default root is "/", i.e. this node's own filesystem; WithRoot points every path below it at an alternate root (a temp directory in tests).

func (*Client) Cluster

func (c *Client) Cluster() *cluster.Client

Cluster returns a handle for pmxcfs and cluster-scope operations.

func (*Client) ConfigDir

func (c *Client) ConfigDir() string

ConfigDir returns the pmxcfs mount root (default "/etc/pve", or "<root>/etc/pve" under WithRoot).

func (*Client) LXC

func (c *Client) LXC() *lxc.Client

LXC returns a handle for LXC container configuration and lifecycle operations.

func (*Client) ProcDir added in v0.2.0

func (c *Client) ProcDir() string

ProcDir returns the procfs mount a running guest's QEMU process is looked up in (default "/proc", or "<root>/proc" under WithRoot).

func (*Client) Qemu

func (c *Client) Qemu() *qemu.Client

Qemu returns a handle for QEMU guest configuration and lifecycle operations.

func (*Client) Run

func (c *Client) Run(ctx context.Context, name string, args ...string) ([]byte, error)

Run executes a PVE CLI tool (pct, pvecm, pvesh, pvesm, or qm) through the configured Runner. It is exported so the cluster, qemu, lxc and storage subpackages can invoke it via their own Env interfaces without importing this package — see the package doc comment on Client.

func (*Client) RunDir

func (c *Client) RunDir() string

RunDir returns the directory holding running guests' pid/vnc/qmp sockets (default "/run/qemu-server", or "<root>/run/qemu-server" under WithRoot).

func (*Client) Storage

func (c *Client) Storage() *storage.Client

Storage returns a handle for local storage inspection.

type CommandError

type CommandError struct {
	Cmd      string
	Args     []string
	ExitCode int
	Stderr   string
}

CommandError carries what a PVE CLI invocation actually did, for a command that exited non-zero.

func (*CommandError) Error

func (e *CommandError) Error() string

Error implements the error interface.

type ConfigError

type ConfigError struct {
	Path string
	Line int
	Err  error
}

ConfigError carries the file and line a config parse failed on.

func (*ConfigError) Error

func (e *ConfigError) Error() string

Error implements the error interface.

func (*ConfigError) Unwrap

func (e *ConfigError) Unwrap() error

Unwrap allows errors.Is/errors.As to see through a ConfigError to its underlying cause.

type Logger

type Logger interface {
	Printf(format string, args ...any)
}

Logger is the minimal logging interface WithDryRun uses to report the argv it would have executed. *log.Logger satisfies it.

type Option

type Option func(*config)

Option mutates a Client's construction-time configuration.

func WithConfigDir

func WithConfigDir(dir string) Option

WithConfigDir overrides the pmxcfs mount root (default: "<root>/etc/pve").

func WithDryRun

func WithDryRun(dryRun bool) Option

WithDryRun makes the default Runner log the argv it would have executed (via WithLogger) and return success without running anything, when dryRun is true — a root daemon's safety valve.

func WithLogger

func WithLogger(l Logger) Option

WithLogger sets the logger WithDryRun uses to report the argv it would have executed.

func WithProcDir added in v0.2.0

func WithProcDir(dir string) Option

WithProcDir overrides the procfs mount a running guest's QEMU process is looked up in (default: "<root>/proc").

func WithRoot

func WithRoot(root string) Option

WithRoot points every default path (config dir, run dir, proc dir) at root instead of "/" — e.g. WithRoot(t.TempDir()) in a test. It can be combined, in either order, with WithConfigDir/WithRunDir/WithProcDir: an explicit directory always wins over the root-derived default.

func WithRunDir

func WithRunDir(dir string) Option

WithRunDir overrides the directory holding running guests' pid/vnc/qmp sockets (default: "<root>/run/qemu-server").

func WithRunner

func WithRunner(r Runner) Option

WithRunner overrides the default exec.CommandContext-based Runner — the seam a test's own double drives this library through, without a hypervisor.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the default deadline applied to a call whose context carries none. Unset (the default), calls have no enforced timeout beyond whatever the caller's own context already carries.

type Runner

type Runner interface {
	Run(ctx context.Context, name string, args ...string) (stdout []byte, err error)
}

Runner executes a PVE CLI tool. The default implementation uses exec.CommandContext with an absolute, pre-resolved binary path.

Directories

Path Synopsis
Package cluster provides pmxcfs and cluster-scope operations: quorum state and the next available VM/CT id.
Package cluster provides pmxcfs and cluster-scope operations: quorum state and the next available VM/CT id.
Package conf parses and formats the PVE section-config file format used by /etc/pve/qemu-server/<vmid>.conf (and its LXC/other counterparts): '#' description comment lines, "key: value" lines, a "[PENDING]" section, and "[<snapshot>]" sections.
Package conf parses and formats the PVE section-config file format used by /etc/pve/qemu-server/<vmid>.conf (and its LXC/other counterparts): '#' description comment lines, "key: value" lines, a "[PENDING]" section, and "[<snapshot>]" sections.
Package fakelocal is the local counterpart to go-proxmox-rest's fakeapi: a public test double so a consumer of go-proxmox-local (cmd/proxmox-scheduler above all) can drive a full create-then-update reconcile against a *local.Client without a hypervisor.
Package fakelocal is the local counterpart to go-proxmox-rest's fakeapi: a public test double so a consumer of go-proxmox-local (cmd/proxmox-scheduler above all) can drive a full create-then-update reconcile against a *local.Client without a hypervisor.
internal
errdefs
Package errdefs holds the sentinel errors shared by the local package and its cluster/qemu subpackages.
Package errdefs holds the sentinel errors shared by the local package and its cluster/qemu subpackages.
params
Package params provides a reflection-based encoder/decoder that converts between option structs and the flat form parameters / JSON responses used by the Proxmox API.
Package params provides a reflection-based encoder/decoder that converts between option structs and the flat form parameters / JSON responses used by the Proxmox API.
property
Package property converts Proxmox comma-separated property strings to and from tagged Go structs.
Package property converts Proxmox comma-separated property strings to and from tagged Go structs.
Package lxc provides LXC container configuration read access and lifecycle operations (create/update/delete via `pct`) on the local hypervisor.
Package lxc provides LXC container configuration read access and lifecycle operations (create/update/delete via `pct`) on the local hypervisor.
Package qemu provides QEMU guest configuration read access and lifecycle operations (create/update/delete via `qm`) on the local hypervisor.
Package qemu provides QEMU guest configuration read access and lifecycle operations (create/update/delete via `qm`) on the local hypervisor.
Package storage provides local storage inspection via `pvesm`.
Package storage provides local storage inspection via `pvesm`.

Jump to

Keyboard shortcuts

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