proxmox

package module
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: Apache-2.0 Imports: 27 Imported by: 83

README

Proxmox API Client Go Package

Continuous Integration GitHub license GitHub issues GitHub release codecov Go Report Card Go Reference

Join the community to discuss ongoing client development usage, the proxmox API or tooling in the #go-proxmox channel on the Gophers Slack and see the self generated docs for more usage details.

Slack

A go client for Proxmox VE. The client implements /api2/json and inspiration was drawn from the existing Telmate package but looking to improve in the following ways...

  • Treated as a proper standalone go package
  • Types and JSON marshal/unmarshalling for all end points
  • Full Testing, unit testing with mocks and integration tests against an API endpoint
  • Configuration options when creating a client for flexible usage
  • Client logging for debugging within your code
  • Context support
  • Added functionality for better go tooling built on this library, some things we'd like
    • Boot VM from qcow URL, inspiration: Proxmox Linux Templates
    • Dynamic host targeting for VM, Proxmox lacks a scheduler when given VM params it will try and locate a host with resources to put it
    • cloud-init support via no-cloud ISOs uploaded to node data stores and auto-mounted before boot, inspiration quiso
    • Unattended XML Support via ISOs similar to cloud-init ideas
    • node/vm/container shell command support via KVM proxy already built into proxmox

API coverage

go-proxmox wraps 100% of the upstream PVE /api2/json surface for PVE 8.x and 9.x — every endpoint in the API viewer has a typed Go wrapper, with three intentional exceptions documented in mage/endpoints/endpoints.go: the two mtunnelwebsocket URL builders (the library returns the signed URL via MigrationTunnelWebSocketPath; the caller plumbs into their own websocket dialer) and the file-restore/download streaming binary endpoint.

Coverage is tracked in CI via mage endpoints:coverage, which diffs the live PVE schema against the package's call sites. Run it locally to confirm a fresh schema bump didn't add anything new:

mage endpoints:sync       # refresh .cache/pve-api/endpoints.json from upstream
mage endpoints:coverage   # print per-area coverage; lists any missing endpoints

Core developers are home lab enthusiasts working in the virtualization and kubernetes space. The common use case we have for Proxmox is dev stress testing and validation of functionality in the products we work on, we plan to build the following tooling around this library to make that easier.

Usage

Create a client and use the public methods to access Proxmox resources.

Basic usage with login with a username and password credential
package main

import (
	"context"
	"fmt"
	
	"github.com/luthermonson/go-proxmox"
)

func main() {
    credentials := proxmox.Credentials{
		Username: "root@pam", 
		Password: "12345",
    }
    client := proxmox.NewClient("https://localhost:8006/api2/json",
		proxmox.WithCredentials(&credentials),
    )
	
    version, err := client.Version(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Println(version.Release) // 7.4
}
Usage with Client Options

Lab setup (self-signed PVE, short timeout, API token):

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/luthermonson/go-proxmox"
)

func main() {
	client := proxmox.NewClient("https://localhost:8006/api2/json",
		proxmox.WithAPIToken("root@pam!mytoken", "somegeneratedapitokenguidefromtheproxmoxui"),
		proxmox.WithInsecureSkipVerify(),     // lab only
		proxmox.WithTimeout(30*time.Second),  // http.DefaultClient has no timeout
	)

	version, err := client.Version(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Println(version.Release) // 6.3
}

Production setup (pinned CA, mTLS optional):

caBundle, _ := os.ReadFile("/etc/ssl/certs/pve-cluster.pem")
pool := x509.NewCertPool()
pool.AppendCertsFromPEM(caBundle)

client := proxmox.NewClient("https://pve.example.com:8006/api2/json",
	proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
	proxmox.WithRootCAs(pool),
	proxmox.WithTimeout(30*time.Second),
	// optional mTLS:
	// proxmox.WithClientCertificate(clientCert),
)
Credential authentication and 2FA

API tokens are the right choice for daemons and CI. For interactive tools — anything with a human typing a password and a TOTP code — use credentials with WithOTP and WithEagerAuth:

client := proxmox.NewClient(url,
	proxmox.WithCredentials(&proxmox.Credentials{
		Username: "admin",
		Password: password,
	}),
	proxmox.WithDefaultRealm("pam"),  // "admin" gets Realm "pam" merged in
	proxmox.WithOTP("123456"),        // one-shot; consumed on first /access/ticket
	proxmox.WithEagerAuth(),          // see note below
)

WithEagerAuth is worth calling out. PVE's pveproxy enforces a hardcoded 3-second delay on every 401 response as a brute-force mitigation (see PVE::APIServer::AnyEvent's # always delay unauthorized calls by 3 seconds block). With credential auth the library's first request goes out unauthenticated by design — the ticket isn't issued until /access/ticket succeeds — so the first user-facing call eats the full 3 seconds. WithEagerAuth runs CreateSession inside NewClient so that cost is paid once at startup and every subsequent request is a normal ticket-authenticated call. Token auth doesn't trigger the 401 path at all and doesn't need this.

The OTP is consumed exactly once; subsequent RefreshTicket calls renew the session via the ticket itself and don't need a new code. If the session is fully lost later (PVE restart invalidates tickets), construct a fresh client with a fresh OTP — TOTP codes can't be cached.

Resource traversal: instance handles

Most resources identified by an id/name follow a getter-returns-handle pattern. The handle carries the parent's client and identifying fields, so callers don't re-thread (node, id) on every call.

cluster, _ := client.Cluster(ctx)

// SDN controllers — getter on the parent, operations on the instance.
ctrl := cluster.SDNController("evpn-1")
if err := ctrl.Update(ctx, &proxmox.SDNControllerOptions{ASN: proxmox.IntOrBool(65000)}); err != nil {
    panic(err)
}
_, _ = ctrl.Delete(ctx)

// Same pattern for VM/container snapshots, firewall rules, ceph OSDs/pools/mons,
// HA resources, ACME accounts, custom CPU models, fabrics, IPAMs, prefix-lists, etc.

See AGENTS.md (Required: pick the right shape for new endpoints) for the full inventory of instance types.

Permission / capability discovery via Subdirs

PVE's directory-index GETs are ACL-filtered: the response only lists the sub-resources the calling token is permitted to read. Use them to probe what an API token can do without try-and-403 against every endpoint:

node, _ := client.Node(ctx, "pve1")
subdirs, _ := node.Subdirs(ctx)         // ["qemu", "lxc", "storage", ...] filtered by ACL
fw, _ := node.FirewallSubdirs(ctx)      // ["rules", "options", "log"] if reachable

cluster, _ := client.Cluster(ctx)
sdnAreas, _ := cluster.SDNSubdirs(ctx)  // ["vnets", "zones", "controllers", ...]
CSV type for comma-joined PVE fields

A few PVE fields serialize as comma-joined strings on the wire (most notably SDNZone.Nodes and .Peers, plus various group/realm fields). proxmox.CSV is a typed []string whose UnmarshalJSON accepts both "a,b,c" and ["a","b","c"], and whose MarshalJSON always emits the comma-joined form PVE expects:

// Read side: PVE returns `"nodes": "pve1,pve2,pve3"`. CSV presents it as a slice.
zone, _ := cluster.SDNZone(ctx, "vxlan-1")
for _, n := range zone.Nodes {                  // proxmox.CSV — iterable like []string
    fmt.Println(n)
}
allNodes := []string(zone.Nodes)                // explicit cast when you need []string

// Write side: the matching *Options types take a plain comma-joined string,
// because PVE only accepts that form on POST/PUT.
_ = cluster.NewSDNZone(ctx, &proxmox.SDNZoneOptions{
    Name:  "vxlan-1",
    Type:  "vxlan",
    Nodes: "pve1,pve2,pve3",
})
Proxies

Route every request through a forward proxy. Works for http://, https://, and socks5:// URLs:

proxyURL, _ := url.Parse("http://proxy.corp.example.com:3128")
client := proxmox.NewClient("https://pve.example.com:8006/api2/json",
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithProxy(proxyURL),
)

Or use the standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY env-var convention:

client := proxmox.NewClient("https://pve.example.com:8006/api2/json",
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithProxyFromEnvironment(),
)

WithProxyFromEnvironment reads env vars per-request (via Go's standard http.ProxyFromEnvironment), so changes after NewClient take effect on the next call. Composes with WithHTTPClient, the TLS options, retry, and request interceptors — option order doesn't matter.

Retries on transient failures

PVE returns 502 / 503 during cluster transitions and 429 when rate-limited. WithRetry installs a RoundTripper wrapper that retries with full-jitter exponential backoff, honors Retry-After on 429 / 503, and respects request-context cancellation:

client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRetry(),  // defaults: 3 attempts, 200ms–5s backoff
)

Tune the defaults for flakier upstreams:

client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRetry(
        proxmox.WithRetryMax(5),
        proxmox.WithRetryBackoff(500*time.Millisecond, 30*time.Second),
    ),
)

Or replace the predicate that decides what to retry — for example to also retry 423 Locked while a cluster transition is in flight:

retryOn423 := func(res *http.Response, err error) bool {
    if err != nil {
        return true
    }
    switch res.StatusCode {
    case http.StatusLocked, http.StatusBadGateway,
        http.StatusServiceUnavailable, http.StatusGatewayTimeout,
        http.StatusTooManyRequests:
        return true
    }
    return false
}
client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRetry(proxmox.WithRetryCondition(retryOn423)),
)

The default predicate retries network errors plus 502 / 503 / 504 / 429. Only idempotent verbs (GET, PUT, DELETE) and POST with a fully-buffered body are eligible — this client always buffers request bodies as []byte, so POST is rewindable in practice.

Request interceptors

Run a function on every outgoing request after the auth headers are populated and before the request is sent. Useful for tracing, correlation IDs, custom audit headers, request logging:

addCorrelationID := func(req *http.Request) error {
    req.Header.Set("X-Correlation-Id", "build-1234")
    return nil
}
client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRequestInterceptor(addCorrelationID),
)

Multiple interceptors compose — each WithRequestInterceptor call appends to the chain, and they run in registration order. The first non-nil error short-circuits the request (with a request interceptor: prefix so callers can errors.Is against their own sentinels):

tracing := func(req *http.Request) error {
    // pull the active span from req.Context() and inject W3C traceparent.
    req.Header.Set("Traceparent", traceparent.From(req.Context()))
    return nil
}
audit := func(req *http.Request) error {
    log.Info().Str("method", req.Method).Str("path", req.URL.Path).Msg("pve")
    return nil
}
client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRequestInterceptor(tracing),
    proxmox.WithRequestInterceptor(audit),
)

The chain fires from Req, Upload, and UploadReader. Websocket upgrades (TermWebSocket, VNCWebSocket) are exempt — the dialer doesn't surface a *http.Request the chain could mutate.

More examples
  • examples/sdn — full SDN walkthrough: create a zone, vnet, subnet, controller, dry-run / apply / rollback.
  • examples/term-and-vnc — websocket terminal and VNC proxy via a small Gin server.
Upgrading between releases

Per-release migration guides live in migration/. Each file describes the source-level changes when upgrading FROM the named release.

Developing

This project relies on Mage for cross os/arch compatibility, please see their installation guide.

Unit Testing

Run mage test to run the unit tests in the root directory.

Integration Testing

To run the integration testing suite against an existing Proxmox API set some env vars in your shell before running mage testIntegration. The integration tests will test logging in and using an API token credentials so make sure you set all five env vars before running tests for them to pass.

Please leave no trace when developing integration tests. All tests should create and remove all testing data they generate then they can be repeatably run against the same proxmox environment. Most people working on this package will likely use their personal Proxmox VE home lab and consuming extra resources via tests will lead to frustration.

Bash
export PROXMOX_URL="https://192.168.1.6:8006/api2/json"
export PROXMOX_USERNAME="root@pam"
export PROXMOX_PASSWORD="password"
export PROXMOX_TOKENID="root@pam!mytoken"
export PROXMOX_SECRET="somegeneratedapitokenguidefromtheproxmoxui"

mage test:integration
Powershell
$Env:PROXMOX_URL = "https://192.168.1.6:8006/api2/json"
$Env:PROXMOX_USERNAME = "root@pam"
$Env:PROXMOX_PASSWORD = "password"
$Env:PROXMOX_TOKENID = "root@pam!mytoken"
$Env:PROXMOX_SECRET = "somegeneratedapitokenguidefromtheproxmoxui"

mage test:integration

Documentation

Index

Constants

View Source 
const (
	LevelError = iota + 1
	LevelWarn
	LevelInfo
	LevelDebug
)
View Source 
const (
	DefaultUserAgent = "go-proxmox/dev"
	TagFormat        = "go-proxmox+%s"
)
View Source 
const (
	TimeframeHour  = Timeframe("hour")
	TimeframeDay   = Timeframe("day")
	TimeframeWeek  = Timeframe("week")
	TimeframeMonth = Timeframe("month")
	TimeframeYear  = Timeframe("year")
)
View Source 
const (
	AVERAGE = ConsolidationFunction("AVERAGE")
	MAX     = ConsolidationFunction("MAX")
)
View Source 
const (
	DomainTypeAD     = DomainType("ad")
	DomainTypeLDAP   = DomainType("ldap")
	DomainTypeOpenID = DomainType("openid")
	DomainTypePam    = DomainType("pam")
	DomainTypePVE    = DomainType("pve")
)
View Source 
const (
	VirtualMachineBackupModeSnapshot = VirtualMachineBackupMode("snapshot")
	VirtualMachineBackupModeSuspend  = VirtualMachineBackupMode("suspend")
	VirtualMachineBackupModeStop     = VirtualMachineBackupMode("stop")

	VirtualMachineBackupCompressZero = VirtualMachineBackupCompress("0")
	VirtualMachineBackupCompressOne  = VirtualMachineBackupCompress("1")
	VirtualMachineBackupCompressGzip = VirtualMachineBackupCompress("gzip")
	VirtualMachineBackupCompressLzo  = VirtualMachineBackupCompress("lzo")
	VirtualMachineBackupCompressZstd = VirtualMachineBackupCompress("zstd")

	VirtualMachineBackupNotificationPolicyAlways  = VirtualMachineBackupNotificationPolicy("always")
	VirtualMachineBackupNotificationPolicyFailure = VirtualMachineBackupNotificationPolicy("failure")
	VirtualMachineBackupNotificationPolicyNever   = VirtualMachineBackupNotificationPolicy("never")
)
View Source 
const (
	StringSeparator = Separator("\n")
	FieldSeparator  = Separator(":")
	SpaceSeparator  = Separator(" ")
)
View Source 
const (
	StatusVirtualMachineRunning = "running"
	StatusVirtualMachineStopped = "stopped"
	StatusVirtualMachinePaused  = "paused"

	UserDataISOFormat = "user-data-%d.iso"
	TagCloudInit      = "cloud-init"
	TagSeperator      = ";"
)
View Source 
const (
	TaskRunning = "running"
)

Variables

View Source 
var (
	ErrNotAuthorized = errors.New("not authorized to access endpoint")

	ErrSessionExists = errors.New("session already exists")

	ErrNoSession = errors.New("no current session to refresh")
)
View Source 
var DefaultAgentWaitInterval = 100 * time.Millisecond

DefaultAgentWaitInterval is the polling interval when waiting for agent exec commands

View Source 
var DefaultWaitInterval = 1 * time.Second
View Source 
var ErrAPITokenWebSocketUnsupported = errors.New("proxmox does not accept API tokens for vncwebsocket; use WithCredentials or WithSession")

ErrAPITokenWebSocketUnsupported is returned by TermWebSocket and VNCWebSocket when the client is authenticated with an API token. Proxmox's vncwebsocket endpoint rejects the token-suffixed user (e.g. "root@pam!tokenname") during the post-upgrade auth handshake, which surfaces here as "unexpected EOF" and on the server as `failed waiting for client: timed out`. Use WithCredentials or WithSession for terminal/VNC access.

View Source 
var ErrNoop = errors.New("nothing to do")
View Source 
var ErrNotFound = errors.New("unable to find the item you are looking for")
View Source 
var ErrTimeout = errors.New("the operation has timed out")

Functions

func EncodeSSHKeys added in v0.6.0 

func EncodeSSHKeys(keys ...string) string

EncodeSSHKeys returns the given SSH public keys encoded the way Proxmox's sshkeys parameter requires. Multiple keys are joined with newlines (PVE's documented separator) before encoding.

PVE applies its own urlencoded-string validator that rejects '+' as a space encoding and requires every reserved character to be percent-encoded — the Python urllib.parse.quote(s, safe="") style. Go's net/url.QueryEscape emits '+' for spaces (HTML form encoding), so its output alone fails validation with "invalid format - invalid urlencoded string". See issue #144.

Use the result as the Value on a VirtualMachineOption{Name: "sshkeys", ...} or assign it to VirtualMachineConfig.SSHKeys.

func IsAPITokenWebSocketUnsupported added in v0.6.0 

func IsAPITokenWebSocketUnsupported(err error) bool

func IsErrNoop 

func IsErrNoop(err error) bool

func IsNotAuthorized 

func IsNotAuthorized(err error) bool

func IsNotFound 

func IsNotFound(err error) bool

func IsTimeout 

func IsTimeout(err error) bool

func MakeTag 

func MakeTag(v string) string

func Ptr added in v0.7.0 

func Ptr[T any](v T) *T

Ptr returns a pointer to v. It exists so callers can construct optional fields on config/options structs inline without a temporary local variable: 

cfg := &proxmox.ContainerConfig{
	Arch:    proxmox.Ptr("amd64"),
	Console: proxmox.Ptr(proxmox.IntOrBool(true)),
}

Pointer-typed fields on these structs distinguish "unset, use the PVE server-side default" (nil) from "explicitly send this value" (non-nil) — without that distinction, a Go zero value silently overrides the server default at marshal time. See issue #199.

Types

type ACL 

type ACL struct {
	Path      string    `json:"path,omitempty"`
	RoleID    string    `json:"roleid,omitempty"`
	Type      string    `json:"type,omitempty"`
	UGID      string    `json:"ugid,omitempty"`
	Propagate IntOrBool `json:"propagate,omitempty"`
}

type ACLOptions 

type ACLOptions struct {
	Path      string    `json:"path,omitempty"`
	Roles     string    `json:"roles,omitempty"` // comma separated list of roles
	Groups    string    `json:"groups,omitempty"`
	Users     string    `json:"users,omitempty"`
	Tokens    string    `json:"tokens,omitempty"`
	Propagate IntOrBool `json:"propagate"`        // Default is true, omitempty would never send false
	Delete    IntOrBool `json:"delete,omitempty"` // true to delete the ACL
}

type ACLs 

type ACLs []*ACL

type ACMEAccount added in v0.6.0 

type ACMEAccount struct {
	Account   map[string]interface{} `json:"account,omitempty"`
	Directory string                 `json:"directory,omitempty"`
	Location  string                 `json:"location,omitempty"`
	TOS       string                 `json:"tos,omitempty"`
}

ACMEAccount is the full account record from GET /cluster/acme/account/{name}. `Account` is the raw CA-returned JSON (status, contacts, etc.) — left untyped because RFC 8555 leaves the shape extensible.

type ACMEAccountIndex added in v0.6.0 

type ACMEAccountIndex struct {
	Name string `json:"name,omitempty"`
}

ACMEAccountIndex is one row in GET /cluster/acme/account — just the name.

type ACMEAccountOptions added in v0.6.0 

type ACMEAccountOptions struct {
	Contact    string `json:"contact"`
	Directory  string `json:"directory,omitempty"`
	EABKid     string `json:"eab-kid,omitempty"`
	EABHMACKey string `json:"eab-hmac-key,omitempty"`
	Name       string `json:"name,omitempty"`
	TOSURL     string `json:"tos_url,omitempty"`
}

ACMEAccountOptions is the POST body for creating an account. Contact is the only required field; PVE defaults Name to "default" and Directory to LE prod. EABKid + EABHMACKey are for External Account Binding (e.g. ZeroSSL).

type ACMEChallengeSchema added in v0.6.0 

type ACMEChallengeSchema struct {
	ID     string                 `json:"id,omitempty"`
	Name   string                 `json:"name,omitempty"`
	Type   string                 `json:"type,omitempty"`
	Schema map[string]interface{} `json:"schema,omitempty"`
}

ACMEChallengeSchema is one entry in GET /cluster/acme/challenge-schema — the catalog of DNS plugin types PVE understands. Schema is the per-plugin parameter spec (left as raw map since each plugin defines its own).

type ACMEDirectory added in v0.6.0 

type ACMEDirectory struct {
	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`
}

ACMEDirectory is one row in GET /cluster/acme/directories — a friendly name + URL for a known ACME CA endpoint.

type ACMEMeta added in v0.6.0 

type ACMEMeta struct {
	CAAIdentities           []string  `json:"caaIdentities,omitempty"`
	ExternalAccountRequired IntOrBool `json:"externalAccountRequired,omitempty"`
	TermsOfService          string    `json:"termsOfService,omitempty"`
	Website                 string    `json:"website,omitempty"`
}

ACMEMeta is the metadata document returned by GET /cluster/acme/meta — what the CA itself advertises about its capabilities and policies.

type ACMEPlugin added in v0.6.0 

type ACMEPlugin struct {
	ID              string    `json:"plugin,omitempty"`
	Type            string    `json:"type,omitempty"`
	API             string    `json:"api,omitempty"`
	Data            string    `json:"data,omitempty"`
	Disable         IntOrBool `json:"disable,omitempty"`
	Nodes           string    `json:"nodes,omitempty"`
	ValidationDelay int       `json:"validation-delay,omitempty"`
	Digest          string    `json:"digest,omitempty"`
}

ACMEPlugin is the read shape from GET /cluster/acme/plugins[/{id}]. The per-provider parameters live in Data (a base64-encoded blob per PVE).

type ACMEPluginOptions added in v0.6.0 

type ACMEPluginOptions struct {
	ID              string `json:"id,omitempty"`
	Type            string `json:"type,omitempty"` // "dns" | "standalone" — POST only
	API             string `json:"api,omitempty"`
	Data            string `json:"data,omitempty"`
	Disable         *bool  `json:"disable,omitempty"`
	Nodes           string `json:"nodes,omitempty"`
	ValidationDelay *int   `json:"validation-delay,omitempty"` // PVE default 30; pointer so unset doesn't reset to 0
	Digest          string `json:"digest,omitempty"`           // PUT only
	Delete          string `json:"delete,omitempty"`           // PUT only
}

ACMEPluginOptions is the create/update payload. POST requires ID + Type; PUT identifies the plugin by URL and accepts Delete to clear keys.

type APTIndexEntry added in v0.6.0 

type APTIndexEntry struct {
	ID string `json:"id"`
}

APTIndexEntry is one row of the /nodes/{node}/apt directory index. PVE returns objects with a single "id" field naming each child resource (changelog, repositories, update, versions).

type APTPackageVersion added in v0.6.0 

type APTPackageVersion struct {
	Package        string `json:"Package"`
	Title          string `json:"Title"`
	Description    string `json:"Description"`
	Version        string `json:"Version"`
	OldVersion     string `json:"OldVersion,omitempty"`
	Origin         string `json:"Origin"`
	Arch           string `json:"Arch"`
	Section        string `json:"Section"`
	Priority       string `json:"Priority"`
	CurrentState   string `json:"CurrentState"`             // Installed / NotInstalled / ...
	ManagerVersion string `json:"ManagerVersion,omitempty"` // only on pve-manager
	RunningKernel  string `json:"RunningKernel,omitempty"`  // only on proxmox-ve
	NotifyStatus   string `json:"NotifyStatus,omitempty"`
}

APTPackageVersion is one row of /apt/versions — package info for the Proxmox-relevant subset of installed packages, including current install state. Used by the GUI's "Updates → Package Versions" panel.

type APTRepositories added in v0.6.0 

type APTRepositories struct {
	Digest        string                `json:"digest"`
	Files         []*APTRepositoryFile  `json:"files,omitempty"`
	Errors        []*APTRepositoryError `json:"errors,omitempty"`
	Infos         []*APTRepositoryInfo  `json:"infos,omitempty"`
	StandardRepos []*APTStandardRepo    `json:"standard-repos,omitempty"`
}

APTRepositories is the parsed view of /etc/apt/sources.list(.d) plus a global Digest used as an etag for concurrent edits. StandardRepos is PVE's catalog of repositories the GUI knows how to add; the per-handle Status is nil when the repo isn't configured on the node.

type APTRepository added in v0.6.0 

type APTRepository struct {
	Enabled    bool                   `json:"Enabled"`
	FileType   string                 `json:"FileType"`
	Types      []string               `json:"Types"`
	URIs       []string               `json:"URIs"`
	Suites     []string               `json:"Suites"`
	Components []string               `json:"Components,omitempty"`
	Options    []*APTRepositoryOption `json:"Options,omitempty"`
	Comment    string                 `json:"Comment,omitempty"`
}

APTRepository is a single repository entry within a file. Components, Options and Comment are only populated where the underlying file format supports them.

type APTRepositoryError added in v0.6.0 

type APTRepositoryError struct {
	Path  string `json:"path"`
	Error string `json:"error"`
}

type APTRepositoryFile added in v0.6.0 

type APTRepositoryFile struct {
	Path         string           `json:"path"`
	FileType     string           `json:"file-type"`
	Digest       []int            `json:"digest,omitempty"`
	Repositories []*APTRepository `json:"repositories,omitempty"`
}

APTRepositoryFile is one apt sources file on disk. FileType is "list" (one-line) or "sources" (deb822). Digest is the per-file digest as a byte array (PVE returns it as a JSON array of integers).

type APTRepositoryInfo added in v0.6.0 

type APTRepositoryInfo struct {
	Path     string `json:"path"`
	Index    string `json:"index"`
	Kind     string `json:"kind"`
	Message  string `json:"message"`
	Property string `json:"property,omitempty"`
}

APTRepositoryInfo is a warning/info note PVE attaches to a specific entry within a specific file (e.g. "use of subscription repo on free system"). Index is a string in the schema even though it names a numeric position.

type APTRepositoryOption added in v0.6.0 

type APTRepositoryOption struct {
	Key    string   `json:"Key"`
	Values []string `json:"Values"`
}

type APTStandardRepo added in v0.6.0 

type APTStandardRepo struct {
	Handle string `json:"handle"`
	Name   string `json:"name"`
	Status *bool  `json:"status,omitempty"`
}

APTStandardRepo is one entry from PVE's catalog of well-known repos. Status is *bool because tri-state: true = configured+enabled, false = configured+disabled, nil = not present on the node.

type APTUpdate added in v0.6.0 

type APTUpdate struct {
	Package      string `json:"Package"`
	Title        string `json:"Title"`
	Description  string `json:"Description"`
	Version      string `json:"Version"`              // new version
	OldVersion   string `json:"OldVersion,omitempty"` // installed version
	Origin       string `json:"Origin"`               // "Proxmox", "Debian", ...
	Arch         string `json:"Arch"`
	Section      string `json:"Section"`
	Priority     string `json:"Priority"`
	NotifyStatus string `json:"NotifyStatus,omitempty"` // version PVE has already notified about
}

APTUpdate is one pending package upgrade as reported by /apt/update. Fields use PVE's upper-case names verbatim — these come straight from the apt metadata.

type AgentCommandIndexEntry added in v0.6.0 

type AgentCommandIndexEntry struct {
	Name string `json:"name,omitempty"`
}

AgentCommandIndexEntry is one entry in the GET /agent command index. PVE only documents `{}` items, but exposes the subroute as the link's "name", so we accept it as an open struct and surface the name when present.

type AgentCommandInfo added in v0.6.0 

type AgentCommandInfo struct {
	Name            string `json:"name"`
	Enabled         bool   `json:"enabled"`
	SuccessResponse bool   `json:"success-response"`
}

type AgentExecStatus 

type AgentExecStatus struct {
	Exited       int       `json:"exited"`
	ErrData      string    `json:"err-data"`
	ErrTruncated bool      `json:"err-truncated"`
	ExitCode     int       `json:"exitcode"`
	OutData      string    `json:"out-data"`
	OutTruncated IntOrBool `json:"out-truncated"`
	Signal       bool      `json:"signal"`
}

type AgentFileRead added in v0.6.0 

type AgentFileRead struct {
	Content   string    `json:"content"`
	Truncated IntOrBool `json:"truncated,omitempty"`
}

AgentFileRead is the response from /agent/file-read. PVE returns the file body inline alongside a truncation flag — no `result` envelope here, unlike most other agent endpoints.

type AgentFsInfo added in v0.6.0 

type AgentFsInfo struct {
	Name       string             `json:"name"`
	Mountpoint string             `json:"mountpoint"`
	Type       string             `json:"type"`
	UsedBytes  uint64             `json:"used-bytes,omitempty"`
	TotalBytes uint64             `json:"total-bytes,omitempty"`
	Disk       []*AgentFsInfoDisk `json:"disk,omitempty"`
}

AgentFsInfo mirrors qga's "guest-get-fsinfo" filesystem entry. Each element of AgentGetFsInfo.Result describes one mounted filesystem inside the guest.

type AgentFsInfoDisk added in v0.6.0 

type AgentFsInfoDisk struct {
	Serial        string        `json:"serial,omitempty"`
	BusType       string        `json:"bus-type,omitempty"`
	Bus           int           `json:"bus,omitempty"`
	Unit          int           `json:"unit,omitempty"`
	Target        int           `json:"target,omitempty"`
	PciController *AgentPciCtrl `json:"pci-controller,omitempty"`
	Dev           string        `json:"dev,omitempty"`
}

type AgentFsfreezeStatus added in v0.6.0 

type AgentFsfreezeStatus string

AgentFsfreezeStatus is the freeze state string ("thawed" or "frozen") returned by qga's guest-fsfreeze-status.

type AgentHostName added in v0.5.0 

type AgentHostName struct {
	HostName string `json:"host-name"`
}

type AgentInfo added in v0.6.0 

type AgentInfo struct {
	Version           string              `json:"version"`
	SupportedCommands []*AgentCommandInfo `json:"supported_commands,omitempty"`
}

AgentInfo describes the guest-agent itself: version + supported commands.

type AgentMemoryBlock added in v0.6.0 

type AgentMemoryBlock struct {
	PhysIndex  int  `json:"phys-index"`
	Online     bool `json:"online"`
	CanOffline bool `json:"can-offline,omitempty"`
}

AgentMemoryBlock describes one hot-pluggable memory block as reported by qga's guest-get-memory-blocks.

type AgentMemoryBlockInfo added in v0.6.0 

type AgentMemoryBlockInfo struct {
	Size uint64 `json:"size"`
}

AgentMemoryBlockInfo is the response payload from qga's guest-get-memory-block-info — currently just the per-block size in bytes.

type AgentNetworkIPAddress 

type AgentNetworkIPAddress struct {
	IPAddressType string `json:"ip-address-type"` // ipv4 ipv6
	IPAddress     string `json:"ip-address"`
	Prefix        int    `json:"prefix"`
	// Deprecated: QEMU Guest Agent's GuestIpAddress has never carried a
	// mac-address field (see qga/qapi-schema.json upstream); this was always
	// unmarshalled as empty. Read the MAC from the parent
	// AgentNetworkIface.HardwareAddress instead. Will be removed in v0.8.0.
	// Closes issue #336.
	MacAddress string `json:"mac-address,omitempty"`
}

type AgentNetworkIface 

type AgentNetworkIface struct {
	Name            string                   `json:"name"`
	HardwareAddress string                   `json:"hardware-address"`
	IPAddresses     []*AgentNetworkIPAddress `json:"ip-addresses"`
}

type AgentOsInfo 

type AgentOsInfo struct {
	Version       string `json:"version"`
	VersionID     string `json:"version-id"`
	ID            string `json:"id"`
	Machine       string `json:"machine"`
	PrettyName    string `json:"pretty-name"`
	Name          string `json:"name"`
	KernelRelease string `json:"kernel-release"`
	KernelVersion string `json:"kernel-version"`
}

type AgentPciCtrl added in v0.6.0 

type AgentPciCtrl struct {
	Domain   int `json:"domain"`
	Bus      int `json:"bus"`
	Slot     int `json:"slot"`
	Function int `json:"function"`
}

type AgentTime added in v0.6.0 

type AgentTime int64

AgentTime represents the guest's wall-clock time in nanoseconds since epoch, as returned by qga's guest-get-time.

type AgentUser added in v0.6.0 

type AgentUser struct {
	User      string  `json:"user"`
	Domain    string  `json:"domain,omitempty"`
	LoginTime float64 `json:"login-time"`
}

AgentUser describes one logged-in user from qga's guest-get-users. The LoginTime field is unix-epoch seconds with sub-second precision.

type AgentVCPU added in v0.6.0 

type AgentVCPU struct {
	LogicalID  int  `json:"logical-id"`
	Online     bool `json:"online"`
	CanOffline bool `json:"can-offline,omitempty"`
}

AgentVCPU represents one logical CPU from qga's guest-get-vcpus. PVE passes the QGA payload through verbatim.

type Appliance 

type Appliance struct {
	Node         string `json:",omitempty"`
	Os           string
	Source       string
	Type         string
	SHA512Sum    string
	Package      string
	Template     string
	Architecture string
	InfoPage     string
	Description  string
	ManageURL    string
	Version      string
	Section      string
	Headline     string
	// contains filtered or unexported fields
}

type Appliances 

type Appliances []*Appliance

type Backup 

type Backup struct{ Content }

func (*Backup) Delete 

func (b *Backup) Delete(ctx context.Context) (*Task, error)

type BackupGuestEntry added in v0.7.0 

type BackupGuestEntry struct {
	VMID int    `json:"vmid"`
	Type string `json:"type,omitempty"` // "qemu" | "lxc"
	Name string `json:"name,omitempty"`
}

BackupGuestEntry is one row in GET /cluster/backup-info/not-backed-up.

type BackupIncludedVolumesGuest added in v0.7.0 

type BackupIncludedVolumesGuest struct {
	ID       int                            `json:"id"`
	Name     string                         `json:"name,omitempty"`
	Type     string                         `json:"type,omitempty"` // "qemu" | "lxc" | "unknown"
	Children []*BackupIncludedVolumesVolume `json:"children,omitempty"`
}

BackupIncludedVolumesGuest is one guest entry under IncludedVolumes.

type BackupIncludedVolumesRoot added in v0.7.0 

type BackupIncludedVolumesRoot struct {
	Children []*BackupIncludedVolumesGuest `json:"children,omitempty"`
}

BackupIncludedVolumesRoot is the response of GET /cluster/backup/{id}/included_volumes — a 2-level tree (guests -> volumes) shaped for ExtJS tree views.

type BackupIncludedVolumesVolume added in v0.7.0 

type BackupIncludedVolumesVolume struct {
	ID       string `json:"id"`
	Name     string `json:"name,omitempty"`
	Included bool   `json:"included"`
	Reason   string `json:"reason,omitempty"`
}

BackupIncludedVolumesVolume is one volume entry under a guest.

type Backups 

type Backups []*Backup

type BulkMigrateOptions added in v0.7.0 

type BulkMigrateOptions struct {
	Target         string `json:"target,omitempty"` // required by PVE
	VMIDs          []int  `json:"vms,omitempty"`
	MaxWorkers     int    `json:"max-workers,omitempty"` // PVE default 1
	Online         *bool  `json:"online,omitempty"`      // live migration for VMs / restart for CTs
	WithLocalDisks *bool  `json:"with-local-disks,omitempty"`
}

BulkMigrateOptions is the body of POST /cluster/bulk-action/guest/migrate.

type BulkShutdownOptions added in v0.7.0 

type BulkShutdownOptions struct {
	VMIDs      []int `json:"vms,omitempty"`
	MaxWorkers int   `json:"max-workers,omitempty"` // PVE default 4
	Timeout    int   `json:"timeout,omitempty"`     // PVE default 180
	// ForceStop: stop the guest hard after timeout. PVE default 1 (true);
	// pointer so leaving the field unset does NOT flip the server default to
	// false. See AGENTS.md "don't clobber PVE-side defaults".
	ForceStop *bool `json:"force-stop,omitempty"`
}

BulkShutdownOptions is the body of POST /cluster/bulk-action/guest/shutdown.

type BulkStartOptions added in v0.7.0 

type BulkStartOptions struct {
	VMIDs      []int `json:"vms,omitempty"`
	MaxWorkers int   `json:"max-workers,omitempty"` // PVE default 4
	Timeout    int   `json:"timeout,omitempty"`     // seconds, VM-only
}

BulkStartOptions is the body of POST /cluster/bulk-action/guest/start.

type BulkSuspendOptions added in v0.7.0 

type BulkSuspendOptions struct {
	VMIDs      []int `json:"vms,omitempty"`
	MaxWorkers int   `json:"max-workers,omitempty"` // PVE default 4
	// ToDisk suspends to disk (resumed on next start). PVE default 0 (false);
	// matches Go zero — plain bool with omitempty drops the field on unset.
	ToDisk       bool   `json:"to-disk,omitempty"`
	StateStorage string `json:"statestorage,omitempty"` // requires ToDisk
}

BulkSuspendOptions is the body of POST /cluster/bulk-action/guest/suspend.

type CPUInfo 

type CPUInfo struct {
	UserHz  int `json:"user_hz"`
	MHZ     StringOrInt
	Model   string
	Cores   int
	Sockets int
	Flags   string
	CPUs    int
	HVM     string
}

type CSV added in v0.6.0 

type CSV []string

func (CSV) MarshalJSON added in v0.6.0 

func (c CSV) MarshalJSON() ([]byte, error)

func (*CSV) UnmarshalJSON added in v0.6.0 

func (c *CSV) UnmarshalJSON(b []byte) error

type Ceph added in v0.2.2 

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

func (*Ceph) Status added in v0.2.2 

func (ce *Ceph) Status(ctx context.Context) (*ClusterCephStatus, error)

type CephCfgDBEntry added in v0.6.0 

type CephCfgDBEntry struct {
	Section            string    `json:"section"`
	Name               string    `json:"name"`
	Value              string    `json:"value"`
	Level              string    `json:"level,omitempty"`
	Mask               string    `json:"mask,omitempty"`
	CanUpdateAtRuntime IntOrBool `json:"can_update_at_runtime,omitempty"`
}

CephCfgDBEntry is a single row from the Ceph mon config DB (GET /nodes/{node}/ceph/cfg/db). Value is always a string — Ceph stores every option as a string regardless of its underlying type.

type CephCfgValue added in v0.6.0 

type CephCfgValue map[string]map[string]string

CephCfgValue is the response to GET /nodes/{node}/ceph/cfg/value: a two-level map of section → key → value. Underscores in both section and key names are normalised to hyphens by PVE.

type CephCmdSafety added in v0.6.0 

type CephCmdSafety struct {
	Safe   bool   `json:"safe"`
	Status string `json:"status,omitempty"`
}

CephCmdSafety is the response from the cmd-safety probe — true means Ceph considers the requested action (stop/destroy of a service) safe to perform right now without losing data redundancy. Status carries the human-readable reason when Safe is false.

type CephFS added in v0.6.0 

type CephFS struct {
	Node           string   `json:"-"`
	Name           string   `json:"name"`
	MetadataPool   string   `json:"metadata_pool"`
	MetadataPoolID int      `json:"metadata_pool_id,omitempty"`
	DataPool       string   `json:"data_pool"`
	DataPools      []string `json:"data_pools,omitempty"`
	DataPoolIDs    []int    `json:"data_pool_ids,omitempty"`
	// contains filtered or unexported fields
}

CephFS is a single entry from the list at GET /nodes/{node}/ceph/fs AND the operations handle returned by Node.CephFS(name). A CephFS may have multiple data pools — DataPool/MetadataPool are the legacy scalar fields (kept for backwards compatibility) and DataPools/DataPoolIDs expose the full set.

func (*CephFS) Delete added in v0.6.0 

func (f *CephFS) Delete(ctx context.Context, removePools, removeStorages bool) (*Task, error)

Delete destroys the CephFS filesystem. removePools also drops the backing metadata + data pools; removeStorages also removes the pveceph-managed storage.cfg entries. PVE refuses the call if any non-disabled cephfs storage entry still references the filesystem.

type CephFSOptions added in v0.6.0 

type CephFSOptions struct {
	PgNum      int       `json:"pg_num,omitempty"`
	AddStorage IntOrBool `json:"add-storage,omitempty"`
}

CephFSOptions is the body for POST /nodes/{node}/ceph/fs/{name}. All fields are optional: PVE defaults Name to "cephfs", PgNum to 128, and AddStorage to false.

type CephFlag added in v0.7.0 

type CephFlag struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Value       bool   `json:"value"`
}

CephFlag is one row of /cluster/ceph/flags.

type CephFlagsUpdateOptions added in v0.7.0 

type CephFlagsUpdateOptions struct {
	NoBackfill  *bool `json:"nobackfill,omitempty"`
	NoDeepScrub *bool `json:"nodeep-scrub,omitempty"`
	NoDown      *bool `json:"nodown,omitempty"`
	NoIn        *bool `json:"noin,omitempty"`
	NoOut       *bool `json:"noout,omitempty"`
	NoRebalance *bool `json:"norebalance,omitempty"`
	NoRecover   *bool `json:"norecover,omitempty"`
	NoScrub     *bool `json:"noscrub,omitempty"`
	NoTierAgent *bool `json:"notieragent,omitempty"`
	NoUp        *bool `json:"noup,omitempty"`
	Pause       *bool `json:"pause,omitempty"`
}

CephFlagsUpdateOptions is the body of PUT /cluster/ceph/flags. Each pointer field maps to a Ceph OSDMap flag: true sets, false unsets, nil leaves the current state untouched (PVE schema has no defaults — they're per-cluster runtime state — so pointer is mandatory to distinguish "not specified").

type CephFsMap added in v0.2.2 

type CephFsMap struct {
	ByRank []struct {
		FilesystemID int    `json:"filesystem_id"`
		Gid          int    `json:"gid"`
		Name         string `json:"name"`
		Rank         int    `json:"rank"`
		Status       string `json:"status"`
	} `json:"by_rank"`
	Epoch     int `json:"epoch"`
	ID        int `json:"id"`
	In        int `json:"in"`
	Max       int `json:"max"`
	Up        int `json:"up"`
	UpStandby int `json:"up:standby"`
}

type CephHealth added in v0.2.2 

type CephHealth struct {
	Checks map[CephHealthCheckName]CephHealthCheck `json:"checks"`
	Mutes  []interface{}                           `json:"mutes"`
	Status string                                  `json:"status"`
}

type CephHealthCheck added in v0.2.2 

type CephHealthCheck struct {
	Detail   []CephHealthCheckDetail `json:"detail"`
	Muted    bool                    `json:"muted"`
	Severity string                  `json:"severity"`
	Summary  CephHealthCheckSummary  `json:"summary"`
}

type CephHealthCheckDetail added in v0.2.2 

type CephHealthCheckDetail struct {
	Message string `json:"message"`
}

type CephHealthCheckName added in v0.2.2 

type CephHealthCheckName string

type CephHealthCheckSummary added in v0.2.2 

type CephHealthCheckSummary struct {
	Count   int    `json:"count"`
	Message string `json:"message"`
}

type CephIndexEntry added in v0.6.0 

type CephIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

CephIndexEntry is one row of the /nodes/{node}/ceph directory index — each entry names a child resource (osd, mon, mgr, pool, fs, status, log, …).

type CephInitOptions added in v0.6.0 

type CephInitOptions struct {
	// Network restricts all Ceph traffic to the given CIDR. Required when
	// you want to pin Ceph to a non-default subnet.
	Network string `json:"network,omitempty"`
	// ClusterNetwork is the optional separate CIDR for OSD heartbeat /
	// replication / recovery traffic. PVE rejects this without Network.
	ClusterNetwork string `json:"cluster-network,omitempty"`
	// Size is the target number of replicas per object (1-7). PVE default 3.
	Size int `json:"size,omitempty"`
	// MinSize is the minimum replicas required to accept I/O (1-7). PVE
	// default 2. Must be <= Size.
	MinSize int `json:"min_size,omitempty"`
	// PGBits is the legacy default placement-group bit count (6-14, default
	// 6). Deprecated upstream in recent Ceph releases; usually leave unset.
	PGBits int `json:"pg_bits,omitempty"`
	// DisableCephx turns off cephx authentication. Dangerous on untrusted
	// networks — only set true when the cluster network is fully private.
	DisableCephx bool `json:"disable_cephx,omitempty"`
}

CephInitOptions are the parameters for POST /nodes/{node}/ceph/init — the one-time bootstrap that seeds /etc/ceph/ceph.conf with cluster fsid, default pool sizing, and network settings. All fields are optional; PVE applies sensible defaults (size=3, min_size=2, etc.). Re-calling init on a node that already has a [global] section is a no-op for most fields.

type CephLogEntry added in v0.6.0 

type CephLogEntry struct {
	N int    `json:"n"` // 1-based log-file line number
	T string `json:"t"` // log line text
}

CephLogEntry is one line of the cluster log as returned by /nodes/{node}/ceph/log. PVE uses single-letter field names ("n", "t") for the line-number and text — matching the dump_logfile wire format.

type CephMDS added in v0.6.0 

type CephMDS struct {
	Node             string    `json:"-"`
	Addr             string    `json:"addr,omitempty"`
	CephVersion      string    `json:"ceph_version,omitempty"`
	CephVersionShort string    `json:"ceph_version_short,omitempty"`
	DirExists        IntOrBool `json:"direxists,omitempty"`
	FSName           string    `json:"fs_name,omitempty"`
	Host             string    `json:"host,omitempty"`
	Name             string    `json:"name,omitempty"`
	Rank             int       `json:"rank,omitempty"`
	Service          IntOrBool `json:"service,omitempty"`
	StandbyReplay    IntOrBool `json:"standby_replay,omitempty"`
	State            string    `json:"state,omitempty"`
	// contains filtered or unexported fields
}

CephMDS is one row from GET /nodes/{node}/ceph/mds AND the operations handle returned by Node.CephMDS(name).

func (*CephMDS) Delete added in v0.6.0 

func (m *CephMDS) Delete(ctx context.Context) (*Task, error)

Delete destroys the metadata server.

type CephMDSOptions added in v0.6.0 

type CephMDSOptions struct {
	HotStandby IntOrBool `json:"hotstandby,omitempty"`
}

CephMDSOptions is the POST body for /nodes/{node}/ceph/mds/{name}. Hot standby has the daemon poll and replay an active MDS' log for faster failover at the cost of always-on idle resources.

type CephMetadata added in v0.7.0 

type CephMetadata struct {
	Version *CephMetadataVersion      `json:"version,omitempty"`
	OSD     []map[string]any          `json:"osd,omitempty"`
	MON     []map[string]any          `json:"mon,omitempty"`
	MGR     []map[string]any          `json:"mgr,omitempty"`
	MDS     []map[string]any          `json:"mds,omitempty"`
	Node    map[string]map[string]any `json:"node,omitempty"`
}

CephMetadata is the response of /cluster/ceph/metadata. PVE returns per-OSD (and per-MON/MGR/MDS) version+device info; we expose the common service buckets and a Version block when present.

type CephMetadataVersion added in v0.7.0 

type CephMetadataVersion struct {
	Version     string `json:"version,omitempty"`
	Buildcommit string `json:"buildcommit,omitempty"`
}

CephMetadataVersion captures the cluster-wide ceph version string PVE derives across all running daemons.

type CephMgr added in v0.6.0 

type CephMgr struct {
	Node             string    `json:"-"`
	Addr             string    `json:"addr,omitempty"`
	CephVersion      string    `json:"ceph_version,omitempty"`
	CephVersionShort string    `json:"ceph_version_short,omitempty"`
	DirExists        IntOrBool `json:"direxists,omitempty"`
	Host             string    `json:"host,omitempty"`
	Name             string    `json:"name,omitempty"`
	Service          IntOrBool `json:"service,omitempty"`
	State            string    `json:"state,omitempty"`
	// contains filtered or unexported fields
}

CephMgr is one row from GET /nodes/{node}/ceph/mgr AND the operations handle returned by Node.CephMgr(id). Distinct from CephMgrMap (the active manager map in cluster-status snapshots).

func (*CephMgr) Delete added in v0.6.0 

func (m *CephMgr) Delete(ctx context.Context) (*Task, error)

Delete destroys the manager.

type CephMgrActiveAddresses added in v0.2.2 

type CephMgrActiveAddresses struct {
	Addrvec []CephMgrAddrVector `json:"addrvec"`
}

type CephMgrActiveClient added in v0.2.2 

type CephMgrActiveClient struct {
	Addrvec []CephMgrAddrVector `json:"addrvec"`
	Name    string              `json:"name"`
}

type CephMgrAddrVector added in v0.2.2 

type CephMgrAddrVector struct {
	Addr  string `json:"addr"`
	Nonce int    `json:"nonce"`
	Type  string `json:"type"`
}

type CephMgrAlwaysOnModules added in v0.2.2 

type CephMgrAlwaysOnModules struct {
	Octopus []string `json:"octopus"`
	Pacific []string `json:"pacific"`
	Quincy  []string `json:"quincy"`
	Reef    []string `json:"reef"`
	Squid   []string `json:"squid"`
}

type CephMgrAvailableModule added in v0.2.2 

type CephMgrAvailableModule struct {
	CanRun        bool                          `json:"can_run"`
	ErrorString   string                        `json:"error_string"`
	ModuleOptions CephMgrAvailableModuleOptions `json:"module_options"`
	Name          string                        `json:"name"`
}

type CephMgrAvailableModuleOption added in v0.2.2 

type CephMgrAvailableModuleOption struct {
	DefaultValue string        `json:"default_value"`
	Desc         string        `json:"desc"`
	EnumAllowed  []string      `json:"enum_allowed"`
	Flags        int           `json:"flags"`
	Level        string        `json:"level"`
	LongDesc     string        `json:"long_desc"`
	Max          string        `json:"max"`
	Min          string        `json:"min"`
	Name         string        `json:"name"`
	SeeAlso      []interface{} `json:"see_also"`
	Tags         []interface{} `json:"tags"`
	Type         string        `json:"type"`
}

type CephMgrAvailableModuleOptions added in v0.2.2 

type CephMgrAvailableModuleOptions struct {
	Interval          CephMgrAvailableModuleOption `json:"interval"`
	LogLevel          CephMgrAvailableModuleOption `json:"log_level"`
	LogToCluster      CephMgrAvailableModuleOption `json:"log_to_cluster"`
	LogToClusterLevel CephMgrAvailableModuleOption `json:"log_to_cluster_level"`
	LogToFile         CephMgrAvailableModuleOption `json:"log_to_file"`
	SMTPDestination   CephMgrAvailableModuleOption `json:"smtp_destination"`
	SMTPFromName      CephMgrAvailableModuleOption `json:"smtp_from_name"`
	SMTPHost          CephMgrAvailableModuleOption `json:"smtp_host"`
	SMTPPassword      CephMgrAvailableModuleOption `json:"smtp_password"`
	SMTPPort          CephMgrAvailableModuleOption `json:"smtp_port"`
	SMTPSender        CephMgrAvailableModuleOption `json:"smtp_sender"`
	SMTPSsl           CephMgrAvailableModuleOption `json:"smtp_ssl"`
	SMTPUser          CephMgrAvailableModuleOption `json:"smtp_user"`
}

type CephMgrMap added in v0.2.2 

type CephMgrMap struct {
	ActiveAddr          string                   `json:"active_addr"`
	ActiveAddrs         CephMgrActiveAddresses   `json:"active_addrs"`
	ActiveChange        string                   `json:"active_change"`
	ActiveClients       []CephMgrActiveClient    `json:"active_clients"`
	ActiveGid           int                      `json:"active_gid"`
	ActiveMgrFeatures   int64                    `json:"active_mgr_features"`
	ActiveName          string                   `json:"active_name"`
	AlwaysOnModules     CephMgrAlwaysOnModules   `json:"always_on_modules"`
	Available           bool                     `json:"available"`
	AvailableModules    []CephMgrAvailableModule `json:"available_modules"`
	Epoch               int                      `json:"epoch"`
	LastFailureOsdEpoch int                      `json:"last_failure_osd_epoch"`
	Modules             []string                 `json:"modules"`
	Services            CephMgrServices          `json:"services"`
	Standbys            []CephMgrStandby         `json:"standbys"`
}

type CephMgrServices added in v0.2.2 

type CephMgrServices struct {
	Dashboard  string `json:"dashboard"`
	Prometheus string `json:"prometheus"`
}

type CephMgrStandby added in v0.2.2 

type CephMgrStandby struct {
	AvailableModules []CephMgrAvailableModule `json:"available_modules"`
	Gid              int                      `json:"gid"`
	MgrFeatures      int64                    `json:"mgr_features"`
	Name             string                   `json:"name"`
}

type CephMon added in v0.2.2 

type CephMon struct {
	Node             string    `json:"-"`
	Addr             string    `json:"addr,omitempty"`
	CephVersion      string    `json:"ceph_version,omitempty"`
	CephVersionShort string    `json:"ceph_version_short,omitempty"`
	DirExists        IntOrBool `json:"direxists,omitempty"`
	Host             string    `json:"host,omitempty"`
	Name             string    `json:"name,omitempty"`
	Quorum           IntOrBool `json:"quorum,omitempty"`
	Rank             int       `json:"rank,omitempty"`
	Service          IntOrBool `json:"service,omitempty"`
	State            string    `json:"state,omitempty"`
	// contains filtered or unexported fields
}

CephMon is one row from GET /nodes/{node}/ceph/mon AND the operations handle returned by Node.CephMon(name). "Name" is the monid; "State" mixes cluster reality (running) with PVE config state (stopped/unknown).

func (*CephMon) Delete added in v0.6.0 

func (m *CephMon) Delete(ctx context.Context) (*Task, error)

Delete destroys the monitor. PVE refuses to remove the last monitor of the cluster. Does not touch any manager running on the same node — use *CephMgr.Delete for that.

type CephMonFeatures added in v0.2.2 

type CephMonFeatures struct {
	Optional   []interface{} `json:"optional"`
	Persistent []string      `json:"persistent"`
}

type CephMonMap added in v0.2.2 

type CephMonMap struct {
	Created           time.Time        `json:"created"`
	DisallowedLeaders string           `json:"disallowed_leaders"`
	ElectionStrategy  int              `json:"election_strategy"`
	Epoch             int              `json:"epoch"`
	Features          CephMonFeatures  `json:"features"`
	Fsid              string           `json:"fsid"`
	MinMonRelease     int              `json:"min_mon_release"`
	MinMonReleaseName string           `json:"min_mon_release_name"`
	Modified          time.Time        `json:"modified"`
	Mons              []ClusterCephMon `json:"mons"`
	Quorum            []int            `json:"quorum"`
	RemovedRanks      string           `json:"removed_ranks"`
	StretchMode       bool             `json:"stretch_mode"`
	TiebreakerMon     string           `json:"tiebreaker_mon"`
}

type CephMonOptions added in v0.6.0 

type CephMonOptions struct {
	MonAddress string `json:"mon-address,omitempty"`
}

CephMonOptions is the POST body for /nodes/{node}/ceph/mon/{monid}. monid is set via the URL path; MonAddress overrides the autodetected monitor IP address(es), must be on Ceph's public network.

type CephOSD added in v0.6.0 

type CephOSD struct {
	Node string `json:"-"`
	ID   int    `json:"-"`
	// contains filtered or unexported fields
}

CephOSD is the operations handle for a single OSD on a node, returned by Node.CephOSD(id). It carries no data fields — instance methods (In/Out/ Scrub/Delete/LVInfo/Metadata) call back into the API when invoked.

func (*CephOSD) Delete added in v0.6.0 

func (o *CephOSD) Delete(ctx context.Context, cleanup bool) (*Task, error)

Delete destroys the OSD. With cleanup=true PVE also zaps the underlying logical volumes (via `ceph-volume lvm zap --destroy`), removes the VG's PV, and wipes any leftover journal/block.db/block.wal partitions. Returns a Task.

func (*CephOSD) In added in v0.6.0 

func (o *CephOSD) In(ctx context.Context) error

In marks the OSD as `in` (eligible to hold data). Returns no value per the PVE schema — success = nil err.

func (*CephOSD) LVInfo added in v0.6.0 

func (o *CephOSD) LVInfo(ctx context.Context, devType string) (info *CephOSDLVInfo, err error)

LVInfo returns LVM details for one of the OSD's logical volumes. devType is "block" (default), "db", or "wal" — pass "" for block.

func (*CephOSD) Metadata added in v0.6.0 

func (o *CephOSD) Metadata(ctx context.Context) (details *CephOSDDetails, err error)

Metadata returns daemon-level info plus the list of backing devices.

func (*CephOSD) Out added in v0.6.0 

func (o *CephOSD) Out(ctx context.Context) error

Out marks the OSD as `out` (data will migrate off it).

func (*CephOSD) Scrub added in v0.6.0 

func (o *CephOSD) Scrub(ctx context.Context, deep bool) error

Scrub instructs the OSD to scrub. Pass deep=true for a deep scrub (checksum-verifies every object) instead of the default metadata-only scrub.

func (*CephOSD) SubResources added in v0.6.0 

func (o *CephOSD) SubResources(ctx context.Context) (items []map[string]interface{}, err error)

SubResources returns the per-OSD index page (GET /nodes/{node}/ceph/osd/{id}). PVE returns a free-form list of child resource descriptors; surfaced as raw maps because the schema declares no concrete fields.

type CephOSDCreateOptions added in v0.6.0 

type CephOSDCreateOptions struct {
	Dev              string    `json:"dev"`
	CrushDeviceClass string    `json:"crush-device-class,omitempty"`
	DBDev            string    `json:"db_dev,omitempty"`
	DBDevSize        float64   `json:"db_dev_size,omitempty"`
	Encrypted        IntOrBool `json:"encrypted,omitempty"`
	OSDsPerDevice    int       `json:"osds-per-device,omitempty"`
	WALDev           string    `json:"wal_dev,omitempty"`
	WALDevSize       float64   `json:"wal_dev_size,omitempty"`
}

CephOSDCreateOptions is the POST body for /nodes/{node}/ceph/osd. Dev is required. DBDevSize requires DBDev; WALDevSize requires WALDev. OSDsPerDevice is mutually exclusive with DBDev/WALDev.

type CephOSDDetails added in v0.6.0 

type CephOSDDetails struct {
	OSD     CephOSDMetadata `json:"osd"`
	Devices []CephOSDDevice `json:"devices,omitempty"`
}

CephOSDDetails is the response from GET /nodes/{node}/ceph/osd/{osdid}/metadata — daemon-level info plus the list of backing devices.

type CephOSDDevice added in v0.6.0 

type CephOSDDevice struct {
	DevNode        string `json:"dev_node,omitempty"`
	Device         string `json:"device,omitempty"` // block|db|wal
	PhysicalDevice string `json:"physical_device,omitempty"`
	Size           uint64 `json:"size,omitempty"`
	SupportDiscard bool   `json:"support_discard,omitempty"`
	Type           string `json:"type,omitempty"` // hdd|ssd
}

CephOSDDevice is one row in CephOSDDetails.Devices.

type CephOSDLVInfo added in v0.6.0 

type CephOSDLVInfo struct {
	CreationTime string `json:"creation_time,omitempty"`
	LVName       string `json:"lv_name,omitempty"`
	LVPath       string `json:"lv_path,omitempty"`
	LVSize       uint64 `json:"lv_size,omitempty"`
	LVUUID       string `json:"lv_uuid,omitempty"`
	VGName       string `json:"vg_name,omitempty"`
}

CephOSDLVInfo is the response from GET /nodes/{node}/ceph/osd/{osdid}/lv-info — LVM details for the OSD's block / db / wal logical volume.

type CephOSDMetadata added in v0.6.0 

type CephOSDMetadata struct {
	BackAddr       string `json:"back_addr,omitempty"`
	Encrypted      bool   `json:"encrypted,omitempty"`
	FrontAddr      string `json:"front_addr,omitempty"`
	HBBackAddr     string `json:"hb_back_addr,omitempty"`
	HBFrontAddr    string `json:"hb_front_addr,omitempty"`
	Hostname       string `json:"hostname,omitempty"`
	ID             int    `json:"id"`
	MemUsage       int64  `json:"mem_usage,omitempty"`
	OSDData        string `json:"osd_data,omitempty"`
	OSDObjectStore string `json:"osd_objectstore,omitempty"`
	PID            int    `json:"pid,omitempty"`
	Version        string `json:"version,omitempty"`
}

CephOSDMetadata is the "osd" sub-object inside CephOSDDetails.

type CephOSDTree added in v0.6.0 

type CephOSDTree struct {
	Flags string                 `json:"flags,omitempty"`
	Root  map[string]interface{} `json:"root,omitempty"`
}

CephOSDTree is the response from GET /nodes/{node}/ceph/osd — the CRUSH tree top-level plus any cluster-wide OSD flags. The CRUSH bucket structure is recursive and per-node properties (status, weight, in, usage, latencies, etc.) vary by bucket type, so Root is kept as a raw map.

type CephOsdMap added in v0.2.2 

type CephOsdMap struct {
	Epoch          int `json:"epoch"`
	NumInOsds      int `json:"num_in_osds"`
	NumOsds        int `json:"num_osds"`
	NumRemappedPgs int `json:"num_remapped_pgs"`
	NumUpOsds      int `json:"num_up_osds"`
	OsdInSince     int `json:"osd_in_since"`
	OsdUpSince     int `json:"osd_up_since"`
}

type CephPgMap added in v0.2.2 

type CephPgMap struct {
	BytesAvail int64 `json:"bytes_avail"`
	BytesTotal int64 `json:"bytes_total"`
	BytesUsed  int64 `json:"bytes_used"`
	DataBytes  int64 `json:"data_bytes"`
	NumObjects int   `json:"num_objects"`
	NumPgs     int   `json:"num_pgs"`
	NumPools   int   `json:"num_pools"`
	PgsByState []struct {
		Count     int    `json:"count"`
		StateName string `json:"state_name"`
	} `json:"pgs_by_state"`
	ReadBytesSec  int `json:"read_bytes_sec"`
	ReadOpPerSec  int `json:"read_op_per_sec"`
	WriteBytesSec int `json:"write_bytes_sec"`
	WriteOpPerSec int `json:"write_op_per_sec"`
}

type CephPool added in v0.6.0 

type CephPool struct {
	Node                string         `json:"-"`
	ApplicationMetadata map[string]any `json:"application_metadata,omitempty"`
	AutoscaleStatus     map[string]any `json:"autoscale_status,omitempty"`
	BytesUsed           uint64         `json:"bytes_used,omitempty"`
	CrushRule           int            `json:"crush_rule"`
	CrushRuleName       string         `json:"crush_rule_name,omitempty"`
	MinSize             int            `json:"min_size"`
	PercentUsed         float64        `json:"percent_used,omitempty"`
	PgAutoscaleMode     string         `json:"pg_autoscale_mode,omitempty"`
	PgNum               int            `json:"pg_num"`
	PgNumFinal          int            `json:"pg_num_final,omitempty"`
	PgNumMin            int            `json:"pg_num_min,omitempty"`
	Pool                int            `json:"pool"`
	PoolName            string         `json:"pool_name"`
	Size                int            `json:"size"`
	TargetSize          uint64         `json:"target_size,omitempty"`
	TargetSizeRatio     float64        `json:"target_size_ratio,omitempty"`
	Type                string         `json:"type"`
	// contains filtered or unexported fields
}

CephPool is one row returned by GET /nodes/{node}/ceph/pool AND the operations handle returned by Node.CephPool(name). Optional fields (statistics-bearing, autoscaler-derived) may be absent depending on Ceph release and whether the pool reports usage.

func (*CephPool) Delete added in v0.6.0 

func (p *CephPool) Delete(ctx context.Context, force, removeStorages, removeECProfile bool) (*Task, error)

Delete destroys the pool. Pass force to destroy a pool even if it is in use. removeStorages also strips any pveceph-managed storage.cfg entries pointing at the pool. removeECProfile drops the EC profile when applicable (PVE defaults this to true server-side; pass false to keep it).

func (*CephPool) Status added in v0.6.0 

func (p *CephPool) Status(ctx context.Context, verbose bool) (status *CephPoolStatus, err error)

Status returns the current configuration and (optionally) statistics for the pool. Set verbose=true to include usage and IO statistics in the Statistics field.

func (*CephPool) SubResources added in v0.6.0 

func (p *CephPool) SubResources(ctx context.Context) (subdirs []*CephPoolSubdir, err error)

SubResources returns the per-pool directory index (currently just "status"). To fetch the actual pool configuration / utilization use Status.

func (*CephPool) Update added in v0.6.0 

func (p *CephPool) Update(ctx context.Context, opts *CephPoolOptions) (*Task, error)

Update changes pool settings. Name is taken from the handle (URL path); any Name set on opts is ignored. Returns a Task.

type CephPoolErasureCoding added in v0.6.0 

type CephPoolErasureCoding struct {
	K             int    // required: number of data chunks
	M             int    // required: number of coding chunks
	DeviceClass   string // optional: CRUSH device class
	FailureDomain string // optional: CRUSH failure domain (default "host")
	Profile       string // optional: override EC profile name
}

CephPoolErasureCoding is the inline "erasure-coding" parameter accepted by POST /nodes/{node}/ceph/pool. PVE serializes it as a single comma-separated string of key=value pairs (e.g. "k=4,m=2,failure-domain=host"). K and M are required; the rest are optional. Build the string with String().

func (*CephPoolErasureCoding) String added in v0.6.0 

func (ec *CephPoolErasureCoding) String() string

String serializes the EC config to the PVE wire format "k=<int>,m=<int>[,device-class=<class>][,failure-domain=<domain>][,profile=<name>]".

type CephPoolOptions added in v0.6.0 

type CephPoolOptions struct {
	Name            string                 `json:"name,omitempty"`
	AddStorages     *bool                  `json:"add_storages,omitempty"`
	Application     string                 `json:"application,omitempty"`
	CrushRule       string                 `json:"crush_rule,omitempty"`
	ErasureCoding   *CephPoolErasureCoding `json:"-"` // serialized by helper, see CreateCephPool
	MinSize         *int                   `json:"min_size,omitempty"`
	PgAutoscaleMode string                 `json:"pg_autoscale_mode,omitempty"`
	PgNum           *int                   `json:"pg_num,omitempty"`
	PgNumMin        *int                   `json:"pg_num_min,omitempty"`
	Size            *int                   `json:"size,omitempty"`
	TargetSize      string                 `json:"target_size,omitempty"`
	TargetSizeRatio *float64               `json:"target_size_ratio,omitempty"`
}

CephPoolOptions is the POST body for /nodes/{node}/ceph/pool (create) and the PUT body for /nodes/{node}/ceph/pool/{name} (update). Name is required on create and immutable on update — the URL path supplies it for PUT.

Pointer fields (*int, *bool) are used wherever PVE has a server-side default that should be preserved when the caller leaves the field unset; this avoids silently clobbering Ceph defaults (size=3, min_size=2, pg_num=128, etc.).

type CephPoolStatus added in v0.6.0 

type CephPoolStatus struct {
	Application          string         `json:"application,omitempty"`
	ApplicationList      []string       `json:"application_list,omitempty"`
	AutoscaleStatus      map[string]any `json:"autoscale_status,omitempty"`
	CrushRule            string         `json:"crush_rule,omitempty"`
	FastRead             bool           `json:"fast_read"`
	HashPSPool           bool           `json:"hashpspool"`
	ID                   int            `json:"id"`
	MinSize              int            `json:"min_size,omitempty"`
	Name                 string         `json:"name"`
	NoDeepScrub          bool           `json:"nodeep-scrub"`
	NoDelete             bool           `json:"nodelete"`
	NoPGChange           bool           `json:"nopgchange"`
	NoScrub              bool           `json:"noscrub"`
	NoSizeChange         bool           `json:"nosizechange"`
	PgAutoscaleMode      string         `json:"pg_autoscale_mode,omitempty"`
	PgNum                int            `json:"pg_num,omitempty"`
	PgNumMin             int            `json:"pg_num_min,omitempty"`
	PgpNum               int            `json:"pgp_num"`
	Size                 int            `json:"size,omitempty"`
	Statistics           map[string]any `json:"statistics,omitempty"`
	TargetSize           string         `json:"target_size,omitempty"`
	TargetSizeRatio      float64        `json:"target_size_ratio,omitempty"`
	UseGMTHitset         bool           `json:"use_gmt_hitset"`
	WriteFadviseDontneed bool           `json:"write_fadvise_dontneed"`
}

CephPoolStatus is the response body of GET /nodes/{node}/ceph/pool/{name}/status. Statistics is only populated when the request was made with verbose=1.

type CephPoolSubdir added in v0.6.0 

type CephPoolSubdir struct {
	Subdir string `json:"subdir,omitempty"`
}

CephPoolSubdir is one row from GET /nodes/{node}/ceph/pool/{name} — the sub-resource directory index. Currently the only entry is "status".

type CephRule added in v0.6.0 

type CephRule struct {
	Name string `json:"name"`
}

CephRule is one entry of the CRUSH rules list. PVE returns only the rule name here; the rule body lives in the CRUSH map dumped by CephCrush.

type CephServiceMap added in v0.2.2 

type CephServiceMap struct {
	Epoch    int      `json:"epoch"`
	Modified string   `json:"modified"`
	Services struct{} `json:"services"`
}

type Client 

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

func NewClient 

func NewClient(baseURL string, opts ...Option) *Client

func (*Client) ACL 

func (c *Client) ACL(ctx context.Context) (acl ACLs, err error)

func (*Client) APIToken deprecated 

func (c *Client) APIToken(tokenID, secret string)

Deprecated: Use the WithAPIToken Option

func (*Client) AccessIndex added in v0.6.0 

func (c *Client) AccessIndex(ctx context.Context) ([]string, error)

AccessIndex enumerates the children of /access ("ticket", "openid", "tfa", "permissions", "password", "domains", ...).

func (*Client) Cluster 

func (c *Client) Cluster(ctx context.Context) (*Cluster, error)

func (*Client) ClusterStorage added in v0.1.1 

func (c *Client) ClusterStorage(ctx context.Context, name string) (storage *ClusterStorage, err error)

func (*Client) ClusterStorages added in v0.1.1 

func (c *Client) ClusterStorages(ctx context.Context) (storages ClusterStorages, err error)

func (*Client) CreateSession added in v0.2.4 

func (c *Client) CreateSession(ctx context.Context) error

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, p string, v interface{}) error

func (*Client) DeleteClusterStorage added in v0.1.1 

func (c *Client) DeleteClusterStorage(ctx context.Context, name string) (*Task, error)

func (*Client) DeleteTFAEntry added in v0.6.0 

func (c *Client) DeleteTFAEntry(ctx context.Context, userid, id, password string) error

DeleteTFAEntry removes a single TFA entry. password is the caller's current password when changing another user's TFA (PVE may require it server-side). Pass "" to omit.

func (*Client) DeleteWithParams added in v0.6.0 

func (c *Client) DeleteWithParams(ctx context.Context, p string, d interface{}, v interface{}) error

DeleteWithParams mirrors GetWithParams for DELETE: it serialises d into a query string (Proxmox DELETE endpoints take options via query params, not a request body) and unmarshals the response into v.

func (*Client) Domain 

func (c *Client) Domain(ctx context.Context, realm string) (domain *Domain, err error)

func (*Client) Domains 

func (c *Client) Domains(ctx context.Context) (domains Domains, err error)

func (*Client) Get 

func (c *Client) Get(ctx context.Context, p string, v interface{}) error

func (*Client) GetTicket added in v0.6.0 

func (c *Client) GetTicket(ctx context.Context) error

GetTicket is a no-op placeholder that PVE exposes for HTML formatters that want a "login page" URL (GET /access/ticket). The endpoint returns null; the wrapper exists for surface coverage and can double as a world-permission liveness probe (no auth required).

func (*Client) GetWithParams added in v0.2.2 

func (c *Client) GetWithParams(ctx context.Context, p string, d interface{}, v interface{}) error

GetWithParams is a helper function to append query parameters to the URL

func (*Client) Group 

func (c *Client) Group(ctx context.Context, groupid string) (group *Group, err error)

func (*Client) Groups 

func (c *Client) Groups(ctx context.Context) (groups Groups, err error)

func (*Client) Login deprecated 

func (c *Client) Login(ctx context.Context, username, password string) error

Deprecated: Use WithCredentials Option

func (*Client) NewClusterStorage added in v0.1.1 

func (c *Client) NewClusterStorage(ctx context.Context, options ...ClusterStorageOptions) (*Task, error)

func (*Client) NewDomain 

func (c *Client) NewDomain(ctx context.Context, realm string, domainType DomainType) error

NewDomain create a new domain with the required two parameters pull it and use domain.Update to configure

func (*Client) NewGroup 

func (c *Client) NewGroup(ctx context.Context, groupid, comment string) error

NewGroup makes a new group, comment is option and can be left empty

func (*Client) NewPool 

func (c *Client) NewPool(ctx context.Context, poolid, comment string) error

func (*Client) NewRole 

func (c *Client) NewRole(ctx context.Context, roleID string, privs string) (err error)

func (*Client) NewTFAEntry added in v0.6.0 

func (c *Client) NewTFAEntry(ctx context.Context, userid string, opts *TFAEntryOptions) (id string, err error)

NewTFAEntry adds a TFA entry for a user. Returns the new entry id on success — PVE wraps it in a {"id": "..."} envelope inside data.

func (*Client) NewUser 

func (c *Client) NewUser(ctx context.Context, user *NewUser) (err error)

func (*Client) Node 

func (c *Client) Node(ctx context.Context, name string) (*Node, error)

func (*Client) Nodes 

func (c *Client) Nodes(ctx context.Context) (ns NodeStatuses, err error)

func (*Client) OpenIDAuthURL added in v0.6.0 

func (c *Client) OpenIDAuthURL(ctx context.Context, realm, redirectURL string) (string, error)

OpenIDAuthURL kicks off the OIDC flow. realm names the configured PVE OIDC realm; redirectURL is where the IdP will redirect after authentication (must match what's registered with the IdP). Returns the URL the caller should send the browser to.

func (*Client) OpenIDIndex added in v0.6.0 

func (c *Client) OpenIDIndex(ctx context.Context) ([]string, error)

OpenIDIndex enumerates the children of /access/openid ("auth-url", "login").

func (*Client) OpenIDLogin added in v0.6.0 

func (c *Client) OpenIDLogin(ctx context.Context, code, state, redirectURL string) (*OpenIDLoginResponse, error)

OpenIDLogin completes the OIDC dance after the IdP has redirected back to our redirectURL with code + state query params. PVE returns a normal session ticket on success.

func (*Client) Password 

func (c *Client) Password(ctx context.Context, userid, password string) error

func (*Client) Permissions 

func (c *Client) Permissions(ctx context.Context, o *PermissionsOptions) (permissions Permissions, err error)

Permissions get permissions for the current user for the client which passes no params, use Permission

func (*Client) Pool 

func (c *Client) Pool(ctx context.Context, poolid string, filters ...string) (pool *Pool, err error)

Pool optional filter of cluster resources by type, enum can be "qemu", "lxc", "storage".

func (*Client) Pools 

func (c *Client) Pools(ctx context.Context) (pools Pools, err error)

func (*Client) Post 

func (c *Client) Post(ctx context.Context, p string, d interface{}, v interface{}) error

func (*Client) Put 

func (c *Client) Put(ctx context.Context, p string, d interface{}, v interface{}) error

func (*Client) RefreshTicket added in v0.6.0 

func (c *Client) RefreshTicket(ctx context.Context) error

RefreshTicket renews the existing PVE auth ticket by re-POSTing to /access/ticket with the current ticket as the password. This is the documented renewal mechanism that does not require the original password and works for sessions originally authenticated with OTP/2FA. On success the client's session is updated in place, so any callers holding pointers to this Client (cached *VirtualMachine, *Container, etc.) automatically use the new ticket.

Returns ErrNoSession if there is no session to renew.

func (*Client) Req 

func (c *Client) Req(ctx context.Context, method, path string, data []byte, v interface{}) error

func (*Client) Role 

func (c *Client) Role(ctx context.Context, roleid string) (role Permission, err error)

func (*Client) Roles 

func (c *Client) Roles(ctx context.Context) (roles Roles, err error)

func (*Client) Session added in v0.6.0 

func (c *Client) Session() *Session

Session returns the current authenticated session, or nil if the client has not yet authenticated (or is using an API token). The returned pointer references the client's live session — do not mutate its fields. The pointer itself can be retained, but its contents may be updated in place by a concurrent RefreshTicket or CreateSession call.

func (*Client) TFAEntries added in v0.6.0 

func (c *Client) TFAEntries(ctx context.Context, userid string) (entries []*TFAEntryInfo, err error)

TFAEntries lists all TFA entries for a given user.

func (*Client) TFAEntry added in v0.6.0 

func (c *Client) TFAEntry(ctx context.Context, userid, id string) (entry *TFAEntryInfo, err error)

TFAEntry reads a single TFA entry by id.

func (*Client) TFAUsers added in v0.6.0 

func (c *Client) TFAUsers(ctx context.Context) (users []*TFAUserEntry, err error)

TFAUsers lists every user with at least one TFA entry configured.

func (*Client) TermWebSocket added in v0.1.2 

func (c *Client) TermWebSocket(path string, term *Term) (chan []byte, chan []byte, chan error, func() error, error)

TermWebSocket opens a terminal WebSocket connection to a previously created termproxy session. It is invoked by Node.TermWebSocket, VirtualMachine.TermWebSocket, and Container.TermWebSocket.

Returns ErrAPITokenWebSocketUnsupported if the client is authenticated with an API token; Proxmox does not accept tokens for /vncwebsocket — see issue luthermonson/go-proxmox#221 and the linked Proxmox forum threads.

func (*Client) Ticket 

func (c *Client) Ticket(ctx context.Context, credentials *Credentials) (*Session, error)

func (*Client) UnlockUserTFA added in v0.6.0 

func (c *Client) UnlockUserTFA(ctx context.Context, userid string) error

UnlockUserTFA clears the TFA lockout flag set after too many failed attempts for the given user. Unlike User.UnlockTFA (which actually removes the user's TFA configuration via the legacy endpoint), this leaves the entries intact — it just resets the failure counter. PUT /access/users/{userid}/unlock-tfa.

func (*Client) UpdateACL 

func (c *Client) UpdateACL(ctx context.Context, aclOptions ACLOptions) error

func (*Client) UpdateClusterStorage added in v0.1.1 

func (c *Client) UpdateClusterStorage(ctx context.Context, name string, options ...ClusterStorageOptions) (*Task, error)

func (*Client) UpdateTFAEntry added in v0.6.0 

func (c *Client) UpdateTFAEntry(ctx context.Context, userid, id string, opts *TFAEntryUpdateOptions) error

UpdateTFAEntry mutates an existing entry (enable/disable, description).

func (*Client) Upload 

func (c *Client) Upload(path string, fields map[string]string, file *os.File, v interface{}) error

Upload - There is some weird 16kb limit hardcoded in proxmox for the max POST size, hopefully in the future we make a func to scp the file to the node directly as this API endpoint is kind of janky. For now big ISOs/vztmpl should be put somewhere and a use DownloadUrl. code link for posterity, I think they meant to do 16mb and got the bit math wrong https://git.proxmox.com/?p=pve-manager.git;a=blob;f=PVE/HTTPServer.pm;h=8a0c308ea6d6601b886b0dec2bada3d4c3da65d0;hb=HEAD#l36 the task returned is the imgcopy from the tmp file to where the node actually wants the iso and you should wait for that to complete before using the iso

func (*Client) UploadReader added in v0.6.0 

func (c *Client) UploadReader(path string, fields map[string]string, filename string, body io.Reader, size int64, v interface{}) error

UploadReader is the io.Reader-based variant of Upload. Use it when the payload is already in memory (e.g., a snippet) or otherwise not backed by an *os.File. size must be the exact byte length of body.

func (*Client) User 

func (c *Client) User(ctx context.Context, userid string) (user *User, err error)

func (*Client) Users 

func (c *Client) Users(ctx context.Context) (users Users, err error)

func (*Client) VNCWebSocket 

func (c *Client) VNCWebSocket(path string, vnc *VNC) (chan []byte, chan []byte, chan error, func() error, error)

VNCWebSocket opens a VNC WebSocket connection to a previously created VNC session. It is invoked by Node.VNCWebSocket, VirtualMachine.VNCWebSocket, and Container.VNCWebSocket.

Returns ErrAPITokenWebSocketUnsupported if the client is authenticated with an API token; see TermWebSocket for the underlying Proxmox limitation.

func (*Client) VerifyVNCTicket added in v0.6.0 

func (c *Client) VerifyVNCTicket(ctx context.Context, opts *VerifyVNCTicketOptions) error

VerifyVNCTicket verifies a VNC ticket previously issued by a vncshell / vncproxy call. PVE returns null on success and 401 on failure. Useful for spice/vnc gateway services that re-authenticate clients.

func (*Client) Version 

func (c *Client) Version(ctx context.Context) (*Version, error)

type CloudInitOption added in v0.6.0 

type CloudInitOption func(*cloudInitConfig)

CloudInitOption configures optional behavior on VirtualMachine.CloudInit. Construct via the With*-prefixed CloudInit option helpers.

func WithCloudInitStorage added in v0.6.0 

func WithCloudInitStorage(name string) CloudInitOption

WithCloudInitStorage selects a specific Proxmox storage (by name) to upload the cloud-init ISO into. The storage must be enabled and accept "iso" content. Without this option, CloudInit auto-selects the first enabled iso-capable storage on the node, which is non-deterministic across nodes with multiple iso-capable storages — see issue #119.

type Cluster 

type Cluster struct {
	Version int
	Quorate int
	Nodes   NodeStatuses
	Name    string
	ID      string
	// contains filtered or unexported fields
}

func (*Cluster) ACMEAccount added in v0.6.0 

func (cl *Cluster) ACMEAccount(ctx context.Context, name string) (account *ACMEAccount, err error)

ACMEAccount returns the full account record (contact, directory URL, EAB settings, account JSON from the CA). Pass "" to read the "default" account.

func (*Cluster) ACMEAccounts added in v0.6.0 

func (cl *Cluster) ACMEAccounts(ctx context.Context) (accounts []*ACMEAccountIndex, err error)

ACMEAccounts lists configured ACME accounts on the cluster.

func (*Cluster) ACMEChallengeSchema added in v0.6.0 

func (cl *Cluster) ACMEChallengeSchema(ctx context.Context) (schemas []*ACMEChallengeSchema, err error)

ACMEChallengeSchema returns the catalog of supported challenge plugin schemas (DNS providers etc.) PVE can configure.

func (*Cluster) ACMEDirectories added in v0.6.0 

func (cl *Cluster) ACMEDirectories(ctx context.Context) (dirs []*ACMEDirectory, err error)

ACMEDirectories returns the list of ACME CA directories PVE knows about (Let's Encrypt prod, staging, etc.).

func (*Cluster) ACMEMeta added in v0.6.0 

func (cl *Cluster) ACMEMeta(ctx context.Context, directory string) (meta *ACMEMeta, err error)

ACMEMeta returns the metadata document of an ACME CA directory (caa identities, EAB requirement, ToS URL, website). directory is optional.

func (*Cluster) ACMEPlugin added in v0.6.0 

func (cl *Cluster) ACMEPlugin(ctx context.Context, id string) (plugin *ACMEPlugin, err error)

ACMEPlugin reads a single plugin's configuration.

func (*Cluster) ACMEPlugins added in v0.6.0 

func (cl *Cluster) ACMEPlugins(ctx context.Context, pluginType string) (plugins []*ACMEPlugin, err error)

ACMEPlugins lists configured ACME challenge plugins (DNS providers, standalone, etc.). Pass a non-empty pluginType to filter by challenge type (e.g. "dns", "standalone").

func (*Cluster) ACMESubdirs added in v0.7.0 

func (cl *Cluster) ACMESubdirs(ctx context.Context) ([]string, error)

ACMESubdirs enumerates the children of /cluster/acme ("plugins", "account", "tos", "meta", "directories", "challenge-schema").

func (*Cluster) ACMETermsOfService added in v0.6.0 

func (cl *Cluster) ACMETermsOfService(ctx context.Context, directory string) (tosURL string, err error)

ACMETermsOfService returns the URL of the CA's ToS document for a given directory URL. directory is optional — PVE defaults to Let's Encrypt prod.

func (*Cluster) AddConfigNode added in v0.7.0 

func (cl *Cluster) AddConfigNode(ctx context.Context, node string, opts *ClusterAddNodeOptions) (result *ClusterAddNodeResult, err error)

AddConfigNode adds a node to the cluster configuration. PVE documents this call as "for internal use" — it returns corosync.conf bytes + the authkey the new node needs, which `pvecm add` normally consumes locally. Exposed here for tooling.

POST /cluster/config/nodes/{node}

func (*Cluster) Backup added in v0.6.0 

func (cl *Cluster) Backup(ctx context.Context, id string) (*ClusterBackup, error)

Backup returns the cluster backup schedule with the given job ID.

func (*Cluster) BackupInfoSubdirs added in v0.7.0 

func (cl *Cluster) BackupInfoSubdirs(ctx context.Context) ([]string, error)

BackupInfoSubdirs enumerates the children of /cluster/backup-info ("not-backed-up" today). ACL-filtered.

GET /cluster/backup-info

func (*Cluster) Backups added in v0.6.0 

func (cl *Cluster) Backups(ctx context.Context) (ClusterBackups, error)

Backups returns all configured cluster backup schedules (vzdump jobs). See https://pve.proxmox.com/pve-docs/api-viewer/#/cluster/backup

func (*Cluster) BulkActionGuestSubdirs added in v0.7.0 

func (cl *Cluster) BulkActionGuestSubdirs(ctx context.Context) ([]string, error)

BulkActionGuestSubdirs enumerates the children of /cluster/bulk-action/guest ("start", "shutdown", "suspend", "migrate"). ACL-filtered.

GET /cluster/bulk-action/guest

func (*Cluster) BulkActionSubdirs added in v0.7.0 

func (cl *Cluster) BulkActionSubdirs(ctx context.Context) ([]string, error)

BulkActionSubdirs enumerates the children of /cluster/bulk-action ("guest" today). ACL-filtered.

GET /cluster/bulk-action

func (*Cluster) BulkMigrateGuests added in v0.7.0 

func (cl *Cluster) BulkMigrateGuests(ctx context.Context, opts *BulkMigrateOptions) (*Task, error)

BulkMigrateGuests migrates guests to the target node. opts.Target is required by the schema; opts.VMIDs filters which guests are moved. Returns the UPID for the worker task.

POST /cluster/bulk-action/guest/migrate

func (*Cluster) BulkShutdownGuests added in v0.7.0 

func (cl *Cluster) BulkShutdownGuests(ctx context.Context, opts *BulkShutdownOptions) (*Task, error)

BulkShutdownGuests shuts down all guests matching opts.VMIDs, or every guest cluster-wide when opts.VMIDs is empty. Returns the UPID for the worker task.

POST /cluster/bulk-action/guest/shutdown

func (*Cluster) BulkStartGuests added in v0.7.0 

func (cl *Cluster) BulkStartGuests(ctx context.Context, opts *BulkStartOptions) (*Task, error)

BulkStartGuests starts (or resumes) all guests matching opts.VMIDs, or every guest cluster-wide when opts.VMIDs is empty. Returns the UPID for the worker task.

POST /cluster/bulk-action/guest/start

func (*Cluster) BulkSuspendGuests added in v0.7.0 

func (cl *Cluster) BulkSuspendGuests(ctx context.Context, opts *BulkSuspendOptions) (*Task, error)

BulkSuspendGuests suspends all guests matching opts.VMIDs, or every guest cluster-wide when opts.VMIDs is empty. Returns the UPID for the worker task.

POST /cluster/bulk-action/guest/suspend

func (*Cluster) Ceph added in v0.2.2 

func (cl *Cluster) Ceph(ctx context.Context) (*Ceph, error)

func (*Cluster) CephFlag added in v0.7.0 

func (cl *Cluster) CephFlag(ctx context.Context, flag string) (value string, err error)

CephFlag returns the current state of a single flag. Useful as a quick poll helper without parsing the full catalog.

GET /cluster/ceph/flags/{flag}

func (*Cluster) CephFlags added in v0.7.0 

func (cl *Cluster) CephFlags(ctx context.Context) (flags []*CephFlag, err error)

CephFlags returns the catalog of Ceph OSD-map flags with their current enabled state.

GET /cluster/ceph/flags

func (*Cluster) CephMetadata added in v0.7.0 

func (cl *Cluster) CephMetadata(ctx context.Context) (meta *CephMetadata, err error)

CephMetadata returns the Ceph services version snapshot — versions and device-id mapping per OSD, MON, MGR, MDS. PVE's response is a wide version-dependent shape; we surface it as a typed root with the common service buckets and let callers reach into the per-service maps directly.

GET /cluster/ceph/metadata

func (*Cluster) CephSubdirs added in v0.7.0 

func (cl *Cluster) CephSubdirs(ctx context.Context) ([]string, error)

CephSubdirs enumerates the children of /cluster/ceph ("metadata", "status", "flags").

func (*Cluster) CheckID added in v0.1.1 

func (cl *Cluster) CheckID(ctx context.Context, vmid int) (bool, error)

CheckID checks if the given vmid is free. CheckID calls the /cluster/nextid endpoint with the "vmid" parameter. The API documentation describes the check as: "Pass a VMID to assert that its free (at time of check)." Returns true if the vmid is free, false otherwise.

func (*Cluster) ClusterOptions added in v0.7.0 

func (cl *Cluster) ClusterOptions(ctx context.Context) (opts *ClusterOptionsResponse, err error)

ClusterOptions reads the cluster-wide datacenter.cfg.

GET /cluster/options

func (*Cluster) ConfigNodes added in v0.7.0 

func (cl *Cluster) ConfigNodes(ctx context.Context) (nodes []*ClusterConfigNodeEntry, err error)

ConfigNodes lists the corosync node list (just names — use ClusterStatus/NodeStatuses for richer per-node state).

GET /cluster/config/nodes

func (*Cluster) ConfigSubdirs added in v0.7.0 

func (cl *Cluster) ConfigSubdirs(ctx context.Context) ([]string, error)

ConfigSubdirs enumerates the children of /cluster/config ("nodes", "join", "totem", "qdevice", "apiversion").

func (*Cluster) CreateCluster added in v0.7.0 

func (cl *Cluster) CreateCluster(ctx context.Context, opts *ClusterCreateOptions) (status string, err error)

CreateCluster generates a new cluster configuration on this node. PVE returns a status string on success.

POST /cluster/config

func (*Cluster) CustomCPUModel added in v0.7.0 

func (cl *Cluster) CustomCPUModel(cputype string) *CustomCPUModel

CustomCPUModel returns a handle for a single custom CPU model. No API call. The "custom-" prefix on cputype is optional per PVE.

GET /cluster/qemu/custom-cpu-models/{cputype}

func (*Cluster) CustomCPUModels added in v0.7.0 

func (cl *Cluster) CustomCPUModels(ctx context.Context) (models []*CustomCPUModel, err error)

CustomCPUModels lists configured custom CPU model definitions. Only entries the caller has Mapping.{Audit,Use,Modify} on are returned.

GET /cluster/qemu/custom-cpu-models

func (*Cluster) DeleteACMEAccount added in v0.6.0 

func (cl *Cluster) DeleteACMEAccount(ctx context.Context, name string) (*Task, error)

DeleteACMEAccount deactivates an ACME account with the CA and removes it from PVE. Async because PVE calls the CA's deactivate endpoint.

func (*Cluster) DeleteACMEPlugin added in v0.6.0 

func (cl *Cluster) DeleteACMEPlugin(ctx context.Context, id string) error

DeleteACMEPlugin removes an ACME challenge plugin.

func (*Cluster) DeleteConfigNode added in v0.7.0 

func (cl *Cluster) DeleteConfigNode(ctx context.Context, node string) error

DeleteConfigNode removes a node from the cluster configuration.

DELETE /cluster/config/nodes/{node}

func (*Cluster) DeleteDirMapping added in v0.6.0 

func (cl *Cluster) DeleteDirMapping(ctx context.Context, id string) error

DeleteDirMapping removes a directory mapping.

func (*Cluster) DeleteMetricServer added in v0.6.0 

func (cl *Cluster) DeleteMetricServer(ctx context.Context, id string) error

DeleteMetricServer removes a configured metric server.

func (*Cluster) DeleteNotificationGotifyEndpoint added in v0.6.0 

func (cl *Cluster) DeleteNotificationGotifyEndpoint(ctx context.Context, name string) error

DeleteNotificationGotifyEndpoint removes a Gotify endpoint.

func (*Cluster) DeleteNotificationMatcher added in v0.6.0 

func (cl *Cluster) DeleteNotificationMatcher(ctx context.Context, name string) error

DeleteNotificationMatcher removes a matcher.

func (*Cluster) DeleteNotificationSMTPEndpoint added in v0.6.0 

func (cl *Cluster) DeleteNotificationSMTPEndpoint(ctx context.Context, name string) error

DeleteNotificationSMTPEndpoint removes an SMTP endpoint.

func (*Cluster) DeleteNotificationSendmailEndpoint added in v0.6.0 

func (cl *Cluster) DeleteNotificationSendmailEndpoint(ctx context.Context, name string) error

DeleteNotificationSendmailEndpoint removes a sendmail endpoint.

func (*Cluster) DeleteNotificationWebhookEndpoint added in v0.6.0 

func (cl *Cluster) DeleteNotificationWebhookEndpoint(ctx context.Context, name string) error

DeleteNotificationWebhookEndpoint removes a webhook endpoint.

func (*Cluster) DeletePCIMapping added in v0.6.0 

func (cl *Cluster) DeletePCIMapping(ctx context.Context, id string) error

DeletePCIMapping removes a PCI mapping.

func (*Cluster) DeleteRealmSyncJob added in v0.6.0 

func (cl *Cluster) DeleteRealmSyncJob(ctx context.Context, id string) error

DeleteRealmSyncJob removes a realm-sync job.

func (*Cluster) DeleteSDNVNet added in v0.2.3 

func (cl *Cluster) DeleteSDNVNet(ctx context.Context, name string) error

func (*Cluster) DeleteSDNZone added in v0.2.3 

func (cl *Cluster) DeleteSDNZone(ctx context.Context, name string) error

func (*Cluster) DeleteUSBMapping added in v0.6.0 

func (cl *Cluster) DeleteUSBMapping(ctx context.Context, id string) error

DeleteUSBMapping removes a USB mapping.

func (*Cluster) DirMapping added in v0.6.0 

func (cl *Cluster) DirMapping(ctx context.Context, id string) (m *ClusterDirMapping, err error)

DirMapping reads a single directory mapping by id.

func (*Cluster) DirMappings added in v0.6.0 

func (cl *Cluster) DirMappings(ctx context.Context, checkNode string) (mappings ClusterDirMappings, err error)

DirMappings lists directory mappings. Pass a non-empty checkNode to ask PVE to validate each entry against that node (populates each entry's Checks).

func (*Cluster) FWGroup 

func (cl *Cluster) FWGroup(ctx context.Context, name string) (group *FirewallSecurityGroup, err error)

func (*Cluster) FWGroups 

func (cl *Cluster) FWGroups(ctx context.Context) (groups []*FirewallSecurityGroup, err error)

func (*Cluster) FirewallAlias added in v0.7.0 

func (cl *Cluster) FirewallAlias(ctx context.Context, name string) (alias *FirewallAlias, err error)

func (*Cluster) FirewallAliasDelete added in v0.7.0 

func (cl *Cluster) FirewallAliasDelete(ctx context.Context, name string) error

func (*Cluster) FirewallAliasUpdate added in v0.7.0 

func (cl *Cluster) FirewallAliasUpdate(ctx context.Context, name string, update *FirewallAliasUpdateOption) error

func (*Cluster) FirewallAliases added in v0.7.0 

func (cl *Cluster) FirewallAliases(ctx context.Context) (aliases []*FirewallAlias, err error)

func (*Cluster) FirewallIPSet added in v0.7.0 

func (cl *Cluster) FirewallIPSet(ctx context.Context, name string) (entries []*FirewallIPSetEntry, err error)

FirewallIPSet returns the entries (CIDRs) of a single ipset. The GET on the collection-style URL returns the members, not metadata about the ipset itself — that matches the PVE wire format.

func (*Cluster) FirewallIPSetDelete added in v0.7.0 

func (cl *Cluster) FirewallIPSetDelete(ctx context.Context, name string, force bool) error

FirewallIPSetDelete removes the ipset. PVE rejects deletion of a non-empty ipset unless force=1 is set; we pass it as a query param so the JSON body stays empty (Delete in this client doesn't take a body).

func (*Cluster) FirewallIPSetEntry added in v0.7.0 

func (cl *Cluster) FirewallIPSetEntry(ctx context.Context, name, cidr string) (entry *FirewallIPSetEntry, err error)

func (*Cluster) FirewallIPSetEntryDelete added in v0.7.0 

func (cl *Cluster) FirewallIPSetEntryDelete(ctx context.Context, name, cidr string) error

func (*Cluster) FirewallIPSetEntryUpdate added in v0.7.0 

func (cl *Cluster) FirewallIPSetEntryUpdate(ctx context.Context, name, cidr string, entry *FirewallIPSetEntryUpdateOption) error

func (*Cluster) FirewallIPSets added in v0.7.0 

func (cl *Cluster) FirewallIPSets(ctx context.Context) (ipsets []*FirewallIPSet, err error)

func (*Cluster) FirewallMacros added in v0.7.0 

func (cl *Cluster) FirewallMacros(ctx context.Context) (macros []*FirewallMacro, err error)

func (*Cluster) FirewallOptions added in v0.7.0 

func (cl *Cluster) FirewallOptions(ctx context.Context) (opts *FirewallClusterOption, err error)

func (*Cluster) FirewallOptionsUpdate added in v0.7.0 

func (cl *Cluster) FirewallOptionsUpdate(ctx context.Context, opts *FirewallClusterOptionUpdateOption) error

func (*Cluster) FirewallRefs added in v0.7.0 

func (cl *Cluster) FirewallRefs(ctx context.Context, typ string) (refs []*FirewallRef, err error)

FirewallRefs lists alias/ipset references usable in rule source/dest. typ is optional — pass "alias" or "ipset" to filter, or "" for all.

func (*Cluster) FirewallRule added in v0.7.0 

func (cl *Cluster) FirewallRule(ctx context.Context, pos int) (rule *FirewallRule, err error)

func (*Cluster) FirewallRuleDelete added in v0.7.0 

func (cl *Cluster) FirewallRuleDelete(ctx context.Context, pos int) error

func (*Cluster) FirewallRuleUpdate added in v0.7.0 

func (cl *Cluster) FirewallRuleUpdate(ctx context.Context, rule *FirewallRule) error

func (*Cluster) FirewallRules added in v0.7.0 

func (cl *Cluster) FirewallRules(ctx context.Context) (rules []*FirewallRule, err error)

func (*Cluster) FirewallSubdirs added in v0.7.0 

func (cl *Cluster) FirewallSubdirs(ctx context.Context) ([]string, error)

FirewallSubdirs enumerates the children of /cluster/firewall ("groups", "rules", "ipset", "aliases", "options", "macros", "refs").

func (*Cluster) GuestsNotInBackup added in v0.7.0 

func (cl *Cluster) GuestsNotInBackup(ctx context.Context) (guests []*BackupGuestEntry, err error)

GuestsNotInBackup returns guests that aren't covered by any backup job.

GET /cluster/backup-info/not-backed-up

func (*Cluster) HAArm added in v0.7.0 

func (cl *Cluster) HAArm(ctx context.Context) error

HAArm re-arms the HA stack after it was previously disarmed. Manual quorum-override action — requires Sys.Console on /.

POST /cluster/ha/status/arm-ha

func (*Cluster) HADisarm added in v0.7.0 

func (cl *Cluster) HADisarm(ctx context.Context, resourceMode string) error

HADisarm requests disarming the HA stack and releases watchdogs cluster-wide. resourceMode is required by PVE: "freeze" preserves HA-tracking state but holds commands, "ignore" removes resources from HA tracking entirely.

POST /cluster/ha/status/disarm-ha

func (*Cluster) HAGroup added in v0.7.0 

func (cl *Cluster) HAGroup(ctx context.Context, name string) (group *HAGroup, err error)

func (*Cluster) HAGroupDelete added in v0.7.0 

func (cl *Cluster) HAGroupDelete(ctx context.Context, name string) error

func (*Cluster) HAGroupUpdate added in v0.7.0 

func (cl *Cluster) HAGroupUpdate(ctx context.Context, name string, opts *HAGroupUpdateOption) error

func (*Cluster) HAGroups added in v0.7.0 

func (cl *Cluster) HAGroups(ctx context.Context) (groups []*HAGroup, err error)

func (*Cluster) HAManagerStatus added in v0.7.0 

func (cl *Cluster) HAManagerStatus(ctx context.Context) (status *HAManagerStatus, err error)

func (*Cluster) HAResource added in v0.7.0 

func (cl *Cluster) HAResource(ctx context.Context, sid string) (resource *HAResource, err error)

func (*Cluster) HAResourceDelete added in v0.7.0 

func (cl *Cluster) HAResourceDelete(ctx context.Context, sid string, purge bool) error

HAResourceDelete removes the resource from HA management. purge also removes it from any HA rules that reference it (and deletes the rule if it's the only resource — that's PVE's documented behavior, not a client-side decision).

func (*Cluster) HAResourceMigrate added in v0.7.0 

func (cl *Cluster) HAResourceMigrate(ctx context.Context, sid, node string) error

func (*Cluster) HAResourceRelocate added in v0.7.0 

func (cl *Cluster) HAResourceRelocate(ctx context.Context, sid, node string) error

HAResourceRelocate is the harder cousin of Migrate — it stops the service on the old node and restarts it on the target, rather than doing an online migration. Use when online migration isn't supported by the guest type.

func (*Cluster) HAResourceUpdate added in v0.7.0 

func (cl *Cluster) HAResourceUpdate(ctx context.Context, sid string, opts *HAResourceUpdateOption) error

func (*Cluster) HAResources added in v0.7.0 

func (cl *Cluster) HAResources(ctx context.Context, typ string) (resources []*HAResource, err error)

HAResources lists managed HA resources. typ filters by resource type (e.g. "vm", "ct"); pass "" for all.

func (*Cluster) HARule added in v0.7.0 

func (cl *Cluster) HARule(ctx context.Context, name string) (rule *HARule, err error)

func (*Cluster) HARuleDelete added in v0.7.0 

func (cl *Cluster) HARuleDelete(ctx context.Context, name string) error

func (*Cluster) HARuleUpdate added in v0.7.0 

func (cl *Cluster) HARuleUpdate(ctx context.Context, name string, opts *HARuleUpdateOption) error

func (*Cluster) HARules added in v0.7.0 

func (cl *Cluster) HARules(ctx context.Context, resource, typ string) (rules []*HARule, err error)

HARules lists HA rules. resource filters to rules affecting that resource ID; typ filters by rule type (e.g. "node-affinity", "resource-affinity"). Pass "" for either to skip that filter.

func (*Cluster) HAStatus added in v0.7.0 

func (cl *Cluster) HAStatus(ctx context.Context) (status []*HAStatusEntry, err error)

func (*Cluster) HAStatusSubdirs added in v0.7.0 

func (cl *Cluster) HAStatusSubdirs(ctx context.Context) ([]string, error)

HAStatusSubdirs enumerates the children of /cluster/ha/status ("current", "manager_status").

func (*Cluster) HASubdirs added in v0.7.0 

func (cl *Cluster) HASubdirs(ctx context.Context) ([]string, error)

HASubdirs enumerates the children of /cluster/ha ("groups", "resources", "status", "rules").

func (*Cluster) Jobs added in v0.6.0 

func (cl *Cluster) Jobs(ctx context.Context) (entries []*ClusterJobIndexEntry, err error)

Jobs lists the resource-type directory under /cluster/jobs (just "realm-sync" today, but PVE may grow other recurring job kinds).

func (*Cluster) JoinAPIVersion added in v0.7.0 

func (cl *Cluster) JoinAPIVersion(ctx context.Context) (version int, err error)

JoinAPIVersion returns the version of the cluster join API on this node.

GET /cluster/config/apiversion

func (*Cluster) JoinCluster added in v0.7.0 

func (cl *Cluster) JoinCluster(ctx context.Context, opts *ClusterJoinOptions) (status string, err error)

JoinCluster joins this node to an existing cluster. PVE returns a status string on success (not a UPID). opts.Hostname, opts.Password, and opts.Fingerprint are required.

POST /cluster/config/join

func (*Cluster) JoinInfo added in v0.7.0 

func (cl *Cluster) JoinInfo(ctx context.Context, node string) (info *ClusterJoinInfo, err error)

JoinInfo returns the parameters a prospective member needs to join this cluster: nodelist, totem config, preferred-node, config digest, and per-node SSH/cert fingerprints. node is optional — empty defaults to the connected node.

GET /cluster/config/join

func (*Cluster) Log added in v0.7.0 

func (cl *Cluster) Log(ctx context.Context, max int) (entries []*ClusterLogEntry, err error)

Log returns the cluster-wide task log. max caps the number of entries; 0 uses the PVE default.

GET /cluster/log

func (*Cluster) Mappings added in v0.6.0 

func (cl *Cluster) Mappings(ctx context.Context) (entries ClusterMappings, err error)

Mappings lists the resource-type directory under /cluster/mapping (e.g. dir, pci, usb). See https://pve.proxmox.com/pve-docs/api-viewer/#/cluster/mapping

func (*Cluster) MetricServer added in v0.6.0 

func (cl *Cluster) MetricServer(ctx context.Context, id string) (server *ClusterMetricServer, err error)

MetricServer reads the full configuration of a single metric server.

func (*Cluster) MetricServers added in v0.6.0 

func (cl *Cluster) MetricServers(ctx context.Context) (servers ClusterMetricServers, err error)

MetricServers lists configured external metric servers (graphite / influxdb / opentelemetry). See https://pve.proxmox.com/pve-docs/api-viewer/#/cluster/metrics/server

func (*Cluster) MetricsExport added in v0.7.0 

func (cl *Cluster) MetricsExport(ctx context.Context, opts *MetricsExportOptions) (export *MetricsExportResponse, err error)

MetricsExport retrieves cluster metrics. opts is optional.

GET /cluster/metrics/export

func (*Cluster) MetricsSubdirs added in v0.7.0 

func (cl *Cluster) MetricsSubdirs(ctx context.Context) ([]string, error)

MetricsSubdirs enumerates the children of /cluster/metrics ("server", "export"). ACL-filtered.

GET /cluster/metrics

func (*Cluster) New added in v0.3.0 

func (cl *Cluster) New(c *Client) *Cluster

func (*Cluster) NewACMEAccount added in v0.6.0 

func (cl *Cluster) NewACMEAccount(ctx context.Context, opts *ACMEAccountOptions) (*Task, error)

NewACMEAccount registers a new ACME account with the CA. PVE runs this as a task because it does a real HTTP round-trip to the CA. opts.Contact is required; everything else (including Name) defaults sensibly.

func (*Cluster) NewACMEPlugin added in v0.6.0 

func (cl *Cluster) NewACMEPlugin(ctx context.Context, opts *ACMEPluginOptions) error

NewACMEPlugin creates a new ACME challenge plugin. opts.ID and opts.Type ("dns" | "standalone") are required by PVE.

func (*Cluster) NewBackup added in v0.6.0 

func (cl *Cluster) NewBackup(ctx context.Context, opts *ClusterBackupOptions) error

NewBackup creates a new cluster backup schedule. The created schedule is not returned by the API; call Backups or Backup(id) to retrieve it.

func (*Cluster) NewCustomCPUModel added in v0.7.0 

func (cl *Cluster) NewCustomCPUModel(ctx context.Context, opts *CustomCPUModelOptions) error

NewCustomCPUModel creates a new custom CPU model. opts.CPUType is required; opts.ReportedModel is required by PVE per the schema (optional=0).

POST /cluster/qemu/custom-cpu-models

func (*Cluster) NewDirMapping added in v0.6.0 

func (cl *Cluster) NewDirMapping(ctx context.Context, opts *ClusterDirMappingOptions) error

NewDirMapping creates a directory mapping. opts.ID and opts.Map are required.

func (*Cluster) NewFWGroup 

func (cl *Cluster) NewFWGroup(ctx context.Context, group *FirewallSecurityGroup) error

func (*Cluster) NewFirewallAlias added in v0.7.0 

func (cl *Cluster) NewFirewallAlias(ctx context.Context, alias *FirewallAliasCreateOption) error

func (*Cluster) NewFirewallIPSet added in v0.7.0 

func (cl *Cluster) NewFirewallIPSet(ctx context.Context, ipset *FirewallIPSetCreationOption) error

func (*Cluster) NewFirewallIPSetEntry added in v0.7.0 

func (cl *Cluster) NewFirewallIPSetEntry(ctx context.Context, name string, entry *FirewallIPSetEntryCreationOption) error

func (*Cluster) NewFirewallRule added in v0.7.0 

func (cl *Cluster) NewFirewallRule(ctx context.Context, rule *FirewallRule) error

func (*Cluster) NewHAGroup added in v0.7.0 

func (cl *Cluster) NewHAGroup(ctx context.Context, opts *HAGroupCreateOption) error

func (*Cluster) NewHAResource added in v0.7.0 

func (cl *Cluster) NewHAResource(ctx context.Context, opts *HAResourceCreateOption) error

func (*Cluster) NewHARule added in v0.7.0 

func (cl *Cluster) NewHARule(ctx context.Context, opts *HARuleCreateOption) error

func (*Cluster) NewMetricServer added in v0.6.0 

func (cl *Cluster) NewMetricServer(ctx context.Context, opts *ClusterMetricServerOptions) error

NewMetricServer creates a new external metric server entry. Requires opts.ID and opts.Type ("graphite" | "influxdb" | "opentelemetry").

func (*Cluster) NewNotificationGotifyEndpoint added in v0.6.0 

func (cl *Cluster) NewNotificationGotifyEndpoint(ctx context.Context, opts *ClusterNotificationGotifyOptions) error

NewNotificationGotifyEndpoint creates a Gotify endpoint. opts.Name, .Server, and .Token are required by PVE on create.

func (*Cluster) NewNotificationMatcher added in v0.6.0 

func (cl *Cluster) NewNotificationMatcher(ctx context.Context, opts *ClusterNotificationMatcherOptions) error

NewNotificationMatcher creates a matcher. opts.Name is required.

func (*Cluster) NewNotificationSMTPEndpoint added in v0.6.0 

func (cl *Cluster) NewNotificationSMTPEndpoint(ctx context.Context, opts *ClusterNotificationSMTPOptions) error

NewNotificationSMTPEndpoint creates an SMTP endpoint.

func (*Cluster) NewNotificationSendmailEndpoint added in v0.6.0 

func (cl *Cluster) NewNotificationSendmailEndpoint(ctx context.Context, opts *ClusterNotificationSendmailOptions) error

NewNotificationSendmailEndpoint creates a sendmail endpoint.

func (*Cluster) NewNotificationWebhookEndpoint added in v0.6.0 

func (cl *Cluster) NewNotificationWebhookEndpoint(ctx context.Context, opts *ClusterNotificationWebhookOptions) error

NewNotificationWebhookEndpoint creates a webhook endpoint.

func (*Cluster) NewPCIMapping added in v0.6.0 

func (cl *Cluster) NewPCIMapping(ctx context.Context, opts *ClusterPCIMappingOptions) error

NewPCIMapping creates a PCI hardware mapping.

func (*Cluster) NewRealmSyncJob added in v0.6.0 

func (cl *Cluster) NewRealmSyncJob(ctx context.Context, id string, opts *ClusterRealmSyncJobOptions) error

NewRealmSyncJob creates a realm-sync job. PVE puts the id in the URL (not the body) and requires opts.Schedule.

func (*Cluster) NewReplicationJob added in v0.7.0 

func (cl *Cluster) NewReplicationJob(ctx context.Context, opts *ReplicationJobOptions) error

func (*Cluster) NewSDNController added in v0.7.0 

func (cl *Cluster) NewSDNController(ctx context.Context, opts *SDNControllerOptions) error

NewSDNController creates a new SDN controller object. opts.Controller and opts.Type are required.

POST /cluster/sdn/controllers

func (*Cluster) NewSDNDNS added in v0.7.0 

func (cl *Cluster) NewSDNDNS(ctx context.Context, opts *SDNDNSOptions) error

NewSDNDNS creates a new SDN DNS plugin. opts.DNS, opts.Type, opts.URL and opts.Key are required.

POST /cluster/sdn/dns

func (*Cluster) NewSDNFabric added in v0.7.0 

func (cl *Cluster) NewSDNFabric(ctx context.Context, opts *SDNFabricOptions) error

NewSDNFabric creates a new fabric. opts.ID and opts.Protocol are required.

POST /cluster/sdn/fabrics/fabric

func (*Cluster) NewSDNIPAM added in v0.7.0 

func (cl *Cluster) NewSDNIPAM(ctx context.Context, opts *SDNIPAMOptions) error

NewSDNIPAM creates a new IPAM backend. opts.IPAM and opts.Type are required.

POST /cluster/sdn/ipams

func (*Cluster) NewSDNPrefixList added in v0.7.0 

func (cl *Cluster) NewSDNPrefixList(ctx context.Context, opts *SDNPrefixListOptions) error

NewSDNPrefixList creates a new prefix-list. opts.ID is required.

POST /cluster/sdn/prefix-lists

func (*Cluster) NewSDNRouteMapEntry added in v0.7.0 

func (cl *Cluster) NewSDNRouteMapEntry(ctx context.Context, opts *SDNRouteMapEntryOptions) error

NewSDNRouteMapEntry creates a new entry in a route-map. opts.RouteMapID, opts.Order, and opts.Action are required.

POST /cluster/sdn/route-maps/entries

func (*Cluster) NewSDNVNet added in v0.2.3 

func (cl *Cluster) NewSDNVNet(ctx context.Context, vnet *VNetOptions) error

func (*Cluster) NewSDNZone added in v0.2.3 

func (cl *Cluster) NewSDNZone(ctx context.Context, zone *SDNZoneOptions) error

func (*Cluster) NewUSBMapping added in v0.6.0 

func (cl *Cluster) NewUSBMapping(ctx context.Context, opts *ClusterUSBMappingOptions) error

NewUSBMapping creates a USB hardware mapping.

func (*Cluster) NextID 

func (cl *Cluster) NextID(ctx context.Context) (int, error)

func (*Cluster) NotificationEndpointsSubdirs added in v0.7.0 

func (cl *Cluster) NotificationEndpointsSubdirs(ctx context.Context) ([]string, error)

NotificationEndpointsSubdirs enumerates the children of /cluster/notifications/endpoints ("sendmail", "gotify", "smtp", "webhook"). ACL-filtered. Each typed sub-resource is already covered by the per-type methods on *Cluster (NotificationSendmail, NotificationGotify, …).

GET /cluster/notifications/endpoints

func (*Cluster) NotificationGotifyEndpoint added in v0.6.0 

func (cl *Cluster) NotificationGotifyEndpoint(ctx context.Context, name string) (e *ClusterNotificationGotifyEndpoint, err error)

NotificationGotifyEndpoint reads a single Gotify endpoint.

func (*Cluster) NotificationGotifyEndpoints added in v0.6.0 

func (cl *Cluster) NotificationGotifyEndpoints(ctx context.Context) (endpoints []*ClusterNotificationGotifyEndpoint, err error)

NotificationGotifyEndpoints lists configured Gotify endpoints.

func (*Cluster) NotificationMatcher added in v0.6.0 

func (cl *Cluster) NotificationMatcher(ctx context.Context, name string) (m *ClusterNotificationMatcher, err error)

NotificationMatcher reads a single matcher by name.

func (*Cluster) NotificationMatcherFieldValues added in v0.6.0 

func (cl *Cluster) NotificationMatcherFieldValues(ctx context.Context) (values []*ClusterNotificationMatcherFieldValue, err error)

NotificationMatcherFieldValues returns the known (field, value) pairs for matcher exact-match rules.

func (*Cluster) NotificationMatcherFields added in v0.6.0 

func (cl *Cluster) NotificationMatcherFields(ctx context.Context) (fields []*ClusterNotificationMatcherField, err error)

NotificationMatcherFields returns the known metadata field names usable in matcher "match-field" rules.

func (*Cluster) NotificationMatchers added in v0.6.0 

func (cl *Cluster) NotificationMatchers(ctx context.Context) (matchers []*ClusterNotificationMatcher, err error)

NotificationMatchers lists configured matchers.

func (*Cluster) NotificationSMTPEndpoint added in v0.6.0 

func (cl *Cluster) NotificationSMTPEndpoint(ctx context.Context, name string) (e *ClusterNotificationSMTPEndpoint, err error)

NotificationSMTPEndpoint reads a single SMTP endpoint.

func (*Cluster) NotificationSMTPEndpoints added in v0.6.0 

func (cl *Cluster) NotificationSMTPEndpoints(ctx context.Context) (endpoints []*ClusterNotificationSMTPEndpoint, err error)

NotificationSMTPEndpoints lists configured SMTP endpoints.

func (*Cluster) NotificationSendmailEndpoint added in v0.6.0 

func (cl *Cluster) NotificationSendmailEndpoint(ctx context.Context, name string) (e *ClusterNotificationSendmailEndpoint, err error)

NotificationSendmailEndpoint reads a single sendmail endpoint.

func (*Cluster) NotificationSendmailEndpoints added in v0.6.0 

func (cl *Cluster) NotificationSendmailEndpoints(ctx context.Context) (endpoints []*ClusterNotificationSendmailEndpoint, err error)

NotificationSendmailEndpoints lists configured sendmail endpoints.

func (*Cluster) NotificationTargets added in v0.6.0 

func (cl *Cluster) NotificationTargets(ctx context.Context) (targets []*ClusterNotificationTarget, err error)

NotificationTargets lists all notification targets (flattened view across every endpoint plugin type).

func (*Cluster) NotificationWebhookEndpoint added in v0.6.0 

func (cl *Cluster) NotificationWebhookEndpoint(ctx context.Context, name string) (e *ClusterNotificationWebhookEndpoint, err error)

NotificationWebhookEndpoint reads a single webhook endpoint.

func (*Cluster) NotificationWebhookEndpoints added in v0.6.0 

func (cl *Cluster) NotificationWebhookEndpoints(ctx context.Context) (endpoints []*ClusterNotificationWebhookEndpoint, err error)

NotificationWebhookEndpoints lists configured webhook endpoints.

func (*Cluster) Notifications added in v0.6.0 

func (cl *Cluster) Notifications(ctx context.Context) (entries ClusterNotificationIndex, err error)

Notifications lists the resource-type directory under /cluster/notifications.

func (*Cluster) PCIMapping added in v0.6.0 

func (cl *Cluster) PCIMapping(ctx context.Context, id string) (m *ClusterPCIMapping, err error)

PCIMapping reads a single PCI mapping by id.

func (*Cluster) PCIMappings added in v0.6.0 

func (cl *Cluster) PCIMappings(ctx context.Context, checkNode string) (mappings ClusterPCIMappings, err error)

PCIMappings lists PCI hardware mappings. See DirMappings for checkNode.

func (*Cluster) QDevice added in v0.7.0 

func (cl *Cluster) QDevice(ctx context.Context) (status map[string]any, err error)

QDevice returns the QDevice (corosync external arbitrator) status. Returns an open-shape map because PVE's response shape depends on whether qdevice is configured and which net algorithm is in use.

GET /cluster/config/qdevice

func (*Cluster) QEMUCPUFlags added in v0.7.0 

func (cl *Cluster) QEMUCPUFlags(ctx context.Context, arch, accel string) (flags []*QEMUCPUFlag, err error)

QEMUCPUFlags returns the catalog of CPU flags available across the cluster (currently x86_64 only — aarch64 returns an empty list). arch and accel are optional; pass "" to use PVE defaults (host arch + kvm acceleration).

GET /cluster/qemu/cpu-flags

func (*Cluster) QEMUSubdirs added in v0.7.0 

func (cl *Cluster) QEMUSubdirs(ctx context.Context) ([]string, error)

QEMUSubdirs enumerates the children of /cluster/qemu. Each entry's "subdir" is a numeric VMID — these are the QEMU guests visible to the caller cluster-wide. Distinct from (*Node).VirtualMachines, which scopes to one node and returns rich VM records.

func (*Cluster) RealmSyncJob added in v0.6.0 

func (cl *Cluster) RealmSyncJob(ctx context.Context, id string) (job *ClusterRealmSyncJob, err error)

RealmSyncJob reads a single realm-sync job by id.

func (*Cluster) RealmSyncJobs added in v0.6.0 

func (cl *Cluster) RealmSyncJobs(ctx context.Context) (jobs []*ClusterRealmSyncJob, err error)

RealmSyncJobs lists configured realm-sync (LDAP/AD/OIDC) jobs.

func (*Cluster) ReplicationJob added in v0.7.0 

func (cl *Cluster) ReplicationJob(ctx context.Context, id string) (job *ReplicationJob, err error)

func (*Cluster) ReplicationJobDelete added in v0.7.0 

func (cl *Cluster) ReplicationJobDelete(ctx context.Context, id string, force, keep bool) error

ReplicationJobDelete marks the job for removal. force=true removes the jobconfig entry without cleaning up replicated state; keep=true leaves the replicated data at the target. The default (force=false, keep=false) is the safe path — PVE schedules a cleanup pass and removes target data.

func (*Cluster) ReplicationJobUpdate added in v0.7.0 

func (cl *Cluster) ReplicationJobUpdate(ctx context.Context, id string, opts *ReplicationJobUpdateOption) error

func (*Cluster) ReplicationJobs added in v0.7.0 

func (cl *Cluster) ReplicationJobs(ctx context.Context) (jobs []*ReplicationJob, err error)

ReplicationJobs lists configured storage replication jobs (the per-guest snapshot-based replication, distinct from cluster backup jobs).

func (*Cluster) Resources 

func (cl *Cluster) Resources(ctx context.Context, filters ...string) (rs ClusterResources, err error)

Resources retrieves a summary list of all resources in the cluster. It calls /cluster/resources api v2 endpoint with an optional "type" parameter to filter searched values. It returns a list of ClusterResources.

func (*Cluster) SDNApply added in v0.2.3 

func (cl *Cluster) SDNApply(ctx context.Context) (*Task, error)

func (*Cluster) SDNController added in v0.7.0 

func (cl *Cluster) SDNController(name string) *SDNController

SDNController returns a handle for a single SDN controller. No API call is made; use the returned handle's Read to populate it.

GET /cluster/sdn/controllers/{controller}

func (*Cluster) SDNControllers added in v0.7.0 

func (cl *Cluster) SDNControllers(ctx context.Context, typ string) (controllers []*SDNController, err error)

SDNControllers lists configured SDN controllers. typ filters by plugin type (e.g. "bgp", "evpn"); pass "" for all.

GET /cluster/sdn/controllers

func (*Cluster) SDNDNS added in v0.7.0 

func (cl *Cluster) SDNDNS(name string) *SDNDNS

SDNDNS returns a handle for a single SDN DNS plugin. No API call is made.

GET /cluster/sdn/dns/{dns}

func (*Cluster) SDNDNSList added in v0.7.0 

func (cl *Cluster) SDNDNSList(ctx context.Context, typ string) (dns []*SDNDNS, err error)

SDNDNSList lists configured SDN DNS plugins. typ filters by plugin type (currently only "powerdns" is supported by PVE); pass "" for all.

GET /cluster/sdn/dns

func (*Cluster) SDNDryRun added in v0.7.0 

func (cl *Cluster) SDNDryRun(ctx context.Context, node string) (*SDNDryRun, error)

SDNDryRun returns the diff (FRR + /etc/network/interfaces.d/sdn) between the current and pending SDN configuration on a specific node.

GET /cluster/sdn/dry-run

func (*Cluster) SDNFabric added in v0.7.0 

func (cl *Cluster) SDNFabric(id string) *SDNFabric

SDNFabric returns a handle for a single fabric. No API call is made.

GET /cluster/sdn/fabrics/fabric/{id}

func (*Cluster) SDNFabricNodes added in v0.7.0 

func (cl *Cluster) SDNFabricNodes(ctx context.Context) (nodes []*SDNFabricNode, err error)

SDNFabricNodes lists all SDN fabric/node pairs across every fabric — the flat alternative to per-fabric iteration via SDNFabric.Nodes.

GET /cluster/sdn/fabrics/node

func (*Cluster) SDNFabrics added in v0.7.0 

func (cl *Cluster) SDNFabrics(ctx context.Context, pending, running bool) (fabrics []*SDNFabric, err error)

SDNFabrics lists configured fabrics. pending/running toggle the returned configuration (PVE distinguishes pending changes from running config).

GET /cluster/sdn/fabrics/fabric

func (*Cluster) SDNFabricsAll added in v0.7.0 

func (cl *Cluster) SDNFabricsAll(ctx context.Context) (all *SDNFabricsAll, err error)

SDNFabricsAll returns the combined view of all fabrics and their member nodes — useful for rendering the whole SDN underlay in one call.

GET /cluster/sdn/fabrics/all

func (*Cluster) SDNFabricsIndex added in v0.7.0 

func (cl *Cluster) SDNFabricsIndex(ctx context.Context) (entries []map[string]any, err error)

SDNFabricsIndex returns the directory entries under /cluster/sdn/fabrics (currently {"fabric", "node", "all"} subdirs).

GET /cluster/sdn/fabrics

func (*Cluster) SDNIPAM added in v0.7.0 

func (cl *Cluster) SDNIPAM(name string) *SDNIPAM

SDNIPAM returns a handle for a single IPAM backend. No API call is made.

GET /cluster/sdn/ipams/{ipam}

func (*Cluster) SDNIPAMs added in v0.7.0 

func (cl *Cluster) SDNIPAMs(ctx context.Context, typ string) (ipams []*SDNIPAM, err error)

SDNIPAMs lists configured IPAM backends. typ filters by plugin type ("netbox", "phpipam", "pve"); pass "" for all.

GET /cluster/sdn/ipams

func (*Cluster) SDNIndex added in v0.7.0 

func (cl *Cluster) SDNIndex(ctx context.Context) (entries []map[string]any, err error)

SDNIndex returns the directory entries under /cluster/sdn.

GET /cluster/sdn

func (*Cluster) SDNLock added in v0.7.0 

func (cl *Cluster) SDNLock(ctx context.Context, allowPending bool) (SDNLockToken, error)

SDNLock acquires the global SDN configuration lock. The returned token must be passed as LockToken on subsequent mutating SDN endpoints (controllers, fabrics, IPAMs, etc.) and on SDNRollback/SDNReleaseLock.

allowPending lets the lock be acquired even if there are pending changes.

POST /cluster/sdn/lock

func (*Cluster) SDNPrefixList added in v0.7.0 

func (cl *Cluster) SDNPrefixList(id string) *SDNPrefixList

SDNPrefixList returns a handle for a single prefix-list. No API call is made.

GET /cluster/sdn/prefix-lists/{id}

func (*Cluster) SDNPrefixLists added in v0.7.0 

func (cl *Cluster) SDNPrefixLists(ctx context.Context, pending, running, verbose bool) (lists []*SDNPrefixList, err error)

SDNPrefixLists lists configured prefix-lists. pending/running toggle which configuration is returned; verbose=false returns just IDs.

GET /cluster/sdn/prefix-lists

func (*Cluster) SDNReleaseLock added in v0.7.0 

func (cl *Cluster) SDNReleaseLock(ctx context.Context, token SDNLockToken, force bool) error

SDNReleaseLock releases the global SDN configuration lock. Pass force=true to release without providing the matching token (admin override).

DELETE /cluster/sdn/lock

func (*Cluster) SDNRollback added in v0.7.0 

func (cl *Cluster) SDNRollback(ctx context.Context, token SDNLockToken, releaseLock bool) error

SDNRollback discards pending SDN configuration changes. token may be empty when no lock is held. releaseLock controls whether the lock is released on success (PVE default: true).

POST /cluster/sdn/rollback

func (*Cluster) SDNRouteMapEntries added in v0.7.0 

func (cl *Cluster) SDNRouteMapEntries(ctx context.Context, pending, running bool) (entries []*SDNRouteMapEntry, err error)

SDNRouteMapEntries lists every route-map entry across all route-maps. pending/running toggle the returned configuration view.

GET /cluster/sdn/route-maps/entries

func (*Cluster) SDNRouteMapEntriesFor added in v0.7.0 

func (cl *Cluster) SDNRouteMapEntriesFor(ctx context.Context, routeMapID string, pending, running bool) (entries []*SDNRouteMapEntry, err error)

SDNRouteMapEntriesFor lists the entries belonging to a single named route-map.

GET /cluster/sdn/route-maps/entries/{route-map-id}

func (*Cluster) SDNRouteMapEntry added in v0.7.0 

func (cl *Cluster) SDNRouteMapEntry(routeMapID string, order uint16) *SDNRouteMapEntry

SDNRouteMapEntry returns a handle for one entry in a route-map keyed by (route-map-id, order). No API call is made.

GET /cluster/sdn/route-maps/entries/{route-map-id}/entry/{order}

func (*Cluster) SDNRouteMaps added in v0.7.0 

func (cl *Cluster) SDNRouteMaps(ctx context.Context, running bool) (maps []*SDNRouteMapID, err error)

SDNRouteMaps lists configured SDN route-maps. running=true returns the running config rather than pending.

GET /cluster/sdn/route-maps

func (*Cluster) SDNSubdirs added in v0.7.0 

func (cl *Cluster) SDNSubdirs(ctx context.Context) ([]string, error)

SDNSubdirs enumerates the children of /cluster/sdn ("vnets", "zones", "controllers", "ipams", "dns", "fabrics", "subnets").

func (*Cluster) SDNSubnets added in v0.2.3 

func (cl *Cluster) SDNSubnets(ctx context.Context, vnetName string) (subnets []*VNetSubnet, err error)

func (*Cluster) SDNVNet added in v0.2.3 

func (cl *Cluster) SDNVNet(ctx context.Context, name string) (vnet *VNet, err error)

func (*Cluster) SDNVNets added in v0.2.3 

func (cl *Cluster) SDNVNets(ctx context.Context) (vnets []*VNet, err error)

func (*Cluster) SDNZone added in v0.2.3 

func (cl *Cluster) SDNZone(ctx context.Context, name string) (zone *SDNZone, err error)

func (*Cluster) SDNZones added in v0.2.3 

func (cl *Cluster) SDNZones(ctx context.Context, filters ...string) (zones []*SDNZone, err error)

func (*Cluster) ScheduleAnalyze added in v0.6.0 

func (cl *Cluster) ScheduleAnalyze(ctx context.Context, schedule string, iterations, startTime int) (preview []*ClusterScheduleEvent, err error)

ScheduleAnalyze simulates a systemd-style calendar event and returns the next iterations firings. iterations defaults to 10 server-side when 0; startTime in UNIX seconds (0 = "now").

func (*Cluster) SetCephFlag added in v0.7.0 

func (cl *Cluster) SetCephFlag(ctx context.Context, flag string, value bool) error

SetCephFlag sets or clears a single ceph flag synchronously. The PVE schema describes this as a sync wrapper around the bulk endpoint; no UPID is returned.

PUT /cluster/ceph/flags/{flag}

func (*Cluster) SetCephFlags added in v0.7.0 

func (cl *Cluster) SetCephFlags(ctx context.Context, opts *CephFlagsUpdateOptions) (*Task, error)

SetCephFlags toggles multiple ceph flags atomically and returns a *Task for the worker that applies them. Each pointer field in opts: true sets, false unsets, nil leaves the flag alone.

PUT /cluster/ceph/flags

func (*Cluster) Status 

func (cl *Cluster) Status(ctx context.Context) error

func (*Cluster) Subdirs added in v0.7.0 

func (cl *Cluster) Subdirs(ctx context.Context) ([]string, error)

Subdirs enumerates the children of /cluster (typically "replication", "metrics", "config", "firewall", "backup", "backupinfo", "ha", "acme", "ceph", "jobs", "sdn", "log", "resources", "tasks", "options", "status", "nextid", "qemu"). ACL-filtered.

func (*Cluster) Tasks 

func (cl *Cluster) Tasks(ctx context.Context) (Tasks, error)

func (*Cluster) TestNotificationTarget added in v0.6.0 

func (cl *Cluster) TestNotificationTarget(ctx context.Context, name string) error

TestNotificationTarget triggers PVE to send a test notification through the named target. Returns immediately; PVE does not surface a UPID for this op.

func (*Cluster) Totem added in v0.7.0 

func (cl *Cluster) Totem(ctx context.Context) (totem map[string]any, err error)

Totem returns the corosync totem protocol settings (token timeouts, link modes, secauth, etc.). Returns an open-shape map because the totem config has many version-dependent knobs.

GET /cluster/config/totem

func (*Cluster) USBMapping added in v0.6.0 

func (cl *Cluster) USBMapping(ctx context.Context, id string) (m *ClusterUSBMapping, err error)

USBMapping reads a single USB mapping by id.

func (*Cluster) USBMappings added in v0.6.0 

func (cl *Cluster) USBMappings(ctx context.Context, checkNode string) (mappings ClusterUSBMappings, err error)

USBMappings lists USB hardware mappings. See DirMappings for checkNode.

func (*Cluster) UnmarshalJSON 

func (cl *Cluster) UnmarshalJSON(b []byte) error

func (*Cluster) UpdateACMEAccount added in v0.6.0 

func (cl *Cluster) UpdateACMEAccount(ctx context.Context, name, contact string) (*Task, error)

UpdateACMEAccount mutates an existing account. Only `contact` is mutable per the PVE schema; the rest is set at creation. Pass "" for name to target the "default" account.

func (*Cluster) UpdateACMEPlugin added in v0.6.0 

func (cl *Cluster) UpdateACMEPlugin(ctx context.Context, id string, opts *ACMEPluginOptions) error

UpdateACMEPlugin mutates an existing plugin. Pass opts.Delete to reset a comma-separated list of keys back to their PVE defaults.

func (*Cluster) UpdateClusterOptions added in v0.7.0 

func (cl *Cluster) UpdateClusterOptions(ctx context.Context, opts *ClusterOptionsUpdate) error

UpdateClusterOptions mutates the datacenter.cfg. opts.Delete is a comma-separated list of keys to reset to their PVE defaults.

PUT /cluster/options

func (*Cluster) UpdateDirMapping added in v0.6.0 

func (cl *Cluster) UpdateDirMapping(ctx context.Context, id string, opts *ClusterDirMappingOptions) error

UpdateDirMapping mutates an existing directory mapping.

func (*Cluster) UpdateMetricServer added in v0.6.0 

func (cl *Cluster) UpdateMetricServer(ctx context.Context, id string, opts *ClusterMetricServerOptions) error

UpdateMetricServer mutates an existing metric server entry. The opts.Delete field is a comma-separated list of keys to reset (PVE quirk).

func (*Cluster) UpdateNotificationGotifyEndpoint added in v0.6.0 

func (cl *Cluster) UpdateNotificationGotifyEndpoint(ctx context.Context, name string, opts *ClusterNotificationGotifyOptions) error

UpdateNotificationGotifyEndpoint mutates an existing Gotify endpoint.

func (*Cluster) UpdateNotificationMatcher added in v0.6.0 

func (cl *Cluster) UpdateNotificationMatcher(ctx context.Context, name string, opts *ClusterNotificationMatcherOptions) error

UpdateNotificationMatcher mutates an existing matcher.

func (*Cluster) UpdateNotificationSMTPEndpoint added in v0.6.0 

func (cl *Cluster) UpdateNotificationSMTPEndpoint(ctx context.Context, name string, opts *ClusterNotificationSMTPOptions) error

UpdateNotificationSMTPEndpoint mutates an existing SMTP endpoint.

func (*Cluster) UpdateNotificationSendmailEndpoint added in v0.6.0 

func (cl *Cluster) UpdateNotificationSendmailEndpoint(ctx context.Context, name string, opts *ClusterNotificationSendmailOptions) error

UpdateNotificationSendmailEndpoint mutates an existing sendmail endpoint.

func (*Cluster) UpdateNotificationWebhookEndpoint added in v0.6.0 

func (cl *Cluster) UpdateNotificationWebhookEndpoint(ctx context.Context, name string, opts *ClusterNotificationWebhookOptions) error

UpdateNotificationWebhookEndpoint mutates an existing webhook endpoint.

func (*Cluster) UpdatePCIMapping added in v0.6.0 

func (cl *Cluster) UpdatePCIMapping(ctx context.Context, id string, opts *ClusterPCIMappingOptions) error

UpdatePCIMapping mutates an existing PCI mapping.

func (*Cluster) UpdateRealmSyncJob added in v0.6.0 

func (cl *Cluster) UpdateRealmSyncJob(ctx context.Context, id string, opts *ClusterRealmSyncJobOptions) error

UpdateRealmSyncJob mutates an existing job. Pass opts.Delete (comma list) to reset specific keys back to PVE defaults.

func (*Cluster) UpdateSDNVNet added in v0.2.3 

func (cl *Cluster) UpdateSDNVNet(ctx context.Context, vnet *VNet) error

func (*Cluster) UpdateSDNZone added in v0.2.3 

func (cl *Cluster) UpdateSDNZone(ctx context.Context, zone *SDNZoneOptions) error

func (*Cluster) UpdateUSBMapping added in v0.6.0 

func (cl *Cluster) UpdateUSBMapping(ctx context.Context, id string, opts *ClusterUSBMappingOptions) error

UpdateUSBMapping mutates an existing USB mapping.

type ClusterAddNodeOptions added in v0.7.0 

type ClusterAddNodeOptions struct {
	APIVersion int    `json:"apiversion,omitempty"`
	NewNodeIP  string `json:"new_node_ip,omitempty"`
	NodeID     int    `json:"nodeid,omitempty"`
	Votes      int    `json:"votes,omitempty"`
	// Force, when true, suppresses the "node already exists" error.
	// PVE schema is boolean; pointer keeps an unset field out of the body.
	Force *bool  `json:"force,omitempty"`
	Link0 string `json:"link0,omitempty"`
	Link1 string `json:"link1,omitempty"`
	Link2 string `json:"link2,omitempty"`
	Link3 string `json:"link3,omitempty"`
	Link4 string `json:"link4,omitempty"`
	Link5 string `json:"link5,omitempty"`
	Link6 string `json:"link6,omitempty"`
	Link7 string `json:"link7,omitempty"`
}

ClusterAddNodeOptions is the body of POST /cluster/config/nodes/{node}.

type ClusterAddNodeResult added in v0.7.0 

type ClusterAddNodeResult struct {
	CorosyncAuthkey string   `json:"corosync_authkey,omitempty"`
	CorosyncConf    string   `json:"corosync_conf,omitempty"`
	Warnings        []string `json:"warnings,omitempty"`
}

ClusterAddNodeResult is the response of POST /cluster/config/nodes/{node} — the corosync authkey + conf bytes that pvecm normally writes locally on the joining node.

type ClusterBackup added in v0.6.0 

type ClusterBackup struct {
	ID               string    `json:"id,omitempty"`
	Schedule         string    `json:"schedule,omitempty"`
	Enabled          IntOrBool `json:"enabled,omitempty"`
	RepeatMissed     IntOrBool `json:"repeat-missed,omitempty"`
	All              IntOrBool `json:"all,omitempty"`
	NotesTemplate    string    `json:"notes-template,omitempty"`
	MailNotification string    `json:"mailnotification,omitempty"`
	MailTo           string    `json:"mailto,omitempty"`
	Mode             string    `json:"mode,omitempty"`
	Type             string    `json:"type,omitempty"`
	NextRun          uint64    `json:"next-run,omitempty"`
	Storage          string    `json:"storage,omitempty"`
	VMID             string    `json:"vmid,omitempty"`
	Exclude          string    `json:"exclude,omitempty"`
	Node             string    `json:"node,omitempty"`
	Pool             string    `json:"pool,omitempty"`
	BwLimit          uint64    `json:"bwlimit,omitempty"`
	Comment          string    `json:"comment,omitempty"`
	PruneBackups     string    `json:"prune-backups,omitempty"`
	// contains filtered or unexported fields
}

ClusterBackup is a single configured cluster-wide backup schedule (a vzdump job). See https://pve.proxmox.com/pve-docs/api-viewer/#/cluster/backup

func (*ClusterBackup) Delete added in v0.6.0 

func (b *ClusterBackup) Delete(ctx context.Context) error

Delete removes this backup schedule.

func (*ClusterBackup) IncludedVolumes added in v0.7.0 

func (b *ClusterBackup) IncludedVolumes(ctx context.Context) (root *BackupIncludedVolumesRoot, err error)

IncludedVolumes returns a tree of guests and their volumes' inclusion status for the given backup job ID.

GET /cluster/backup/{id}/included_volumes

func (*ClusterBackup) Update added in v0.6.0 

func (b *ClusterBackup) Update(ctx context.Context, opts *ClusterBackupOptions) error

Update updates this backup schedule's configuration.

type ClusterBackupOptions added in v0.6.0 

type ClusterBackupOptions struct {
	All                bool   `json:"all,omitempty"`
	BwLimit            uint64 `json:"bwlimit,omitempty"`
	Comment            string `json:"comment,omitempty"`
	Compress           string `json:"compress,omitempty"`
	Dow                string `json:"dow,omitempty"`
	DumpDir            string `json:"dumpdir,omitempty"`
	Enabled            bool   `json:"enabled,omitempty"`
	Exclude            string `json:"exclude,omitempty"`
	ExcludePath        string `json:"exclude-path,omitempty"`
	ID                 string `json:"id,omitempty"`
	IoNice             uint   `json:"ionice,omitempty"`
	LockWait           uint   `json:"lockwait,omitempty"`
	MailNotification   string `json:"mailnotification,omitempty"`
	MailTo             string `json:"mailto,omitempty"`
	MaxFiles           uint   `json:"maxfiles,omitempty"`
	Mode               string `json:"mode,omitempty"`
	Node               string `json:"node,omitempty"`
	NotesTemplate      string `json:"notes-template,omitempty"`
	NotificationMode   string `json:"notification-mode,omitempty"`
	NotificationPolicy string `json:"notification-policy,omitempty"`
	NotificationTarget string `json:"notification-target,omitempty"`
	Performance        string `json:"performance,omitempty"`
	Pigz               int    `json:"pigz,omitempty"`
	Pool               string `json:"pool,omitempty"`
	Protected          bool   `json:"protected,omitempty"`
	PruneBackups       string `json:"prune-backups,omitempty"`
	Quiet              bool   `json:"quiet,omitempty"`
	Remove             bool   `json:"remove,omitempty"`
	RepeatMissed       bool   `json:"repeat-missed,omitempty"`
	Schedule           string `json:"schedule,omitempty"`
	Script             string `json:"script,omitempty"`
	StdExcludes        bool   `json:"stdexcludes,omitempty"`
	Stop               bool   `json:"stop,omitempty"`
	StopWait           uint   `json:"stopwait,omitempty"`
	Storage            string `json:"storage,omitempty"`
	TmpDir             string `json:"tmpdir,omitempty"`
	VMID               string `json:"vmid,omitempty"`
	Zstd               uint   `json:"zstd,omitempty"`
}

ClusterBackupOptions is the request body for POST /cluster/backup (create) and PUT /cluster/backup/{id} (update). All fields are optional; see the PVE API docs for semantics.

type ClusterBackups added in v0.6.0 

type ClusterBackups []*ClusterBackup

type ClusterCephMon added in v0.6.0 

type ClusterCephMon struct {
	Addr          string `json:"addr"`
	CrushLocation string `json:"crush_location"`
	Name          string `json:"name"`
	Priority      int    `json:"priority"`
	Rank          int    `json:"rank"`
	Weight        int    `json:"weight"`
	PublicAddr    string `json:"public_addr"`
	PublicAddrs   struct {
		Addrvec []CephMgrAddrVector `json:"addrvec"`
	} `json:"public_addrs"`
}

ClusterCephMon is the cluster-status snapshot of a monitor (used inside ClusterCephStatus.Monmap.Mons). It's distinct from *CephMon, the per-node monitor handle returned by Node.CephMon(name) that carries operations.

type ClusterCephStatus added in v0.2.2 

type ClusterCephStatus struct {
	ElectionEpoch  int            `json:"election_epoch"`
	Fsid           string         `json:"fsid"`
	Fsmap          CephFsMap      `json:"fsmap"`
	Health         CephHealth     `json:"health"`
	Mgrmap         CephMgrMap     `json:"mgrmap"`
	Monmap         CephMonMap     `json:"monmap"`
	Osdmap         CephOsdMap     `json:"osdmap"`
	Pgmap          CephPgMap      `json:"pgmap"`
	ProgressEvents struct{}       `json:"progress_events"`
	Quorum         []int          `json:"quorum"`
	QuorumAge      int            `json:"quorum_age"`
	QuorumNames    []string       `json:"quorum_names"`
	Servicemap     CephServiceMap `json:"servicemap"`
}

type ClusterConfigNodeEntry added in v0.7.0 

type ClusterConfigNodeEntry struct {
	Node string `json:"node,omitempty"`
}

ClusterConfigNodeEntry is one row from GET /cluster/config/nodes — the bare corosync node list (just names). Use the typed cluster status for richer per-node state.

type ClusterCreateOptions added in v0.7.0 

type ClusterCreateOptions struct {
	ClusterName      string `json:"clustername,omitempty"` // required, max 15 chars
	NodeID           int    `json:"nodeid,omitempty"`
	Votes            int    `json:"votes,omitempty"`
	TokenCoefficient int    `json:"token-coefficient,omitempty"` // PVE default 125
	Link0            string `json:"link0,omitempty"`
	Link1            string `json:"link1,omitempty"`
	Link2            string `json:"link2,omitempty"`
	Link3            string `json:"link3,omitempty"`
	Link4            string `json:"link4,omitempty"`
	Link5            string `json:"link5,omitempty"`
	Link6            string `json:"link6,omitempty"`
	Link7            string `json:"link7,omitempty"`
}

ClusterCreateOptions is the body of POST /cluster/config — "create cluster".

type ClusterDirMapping added in v0.6.0 

type ClusterDirMapping struct {
	ID          string                 `json:"id,omitempty"`
	Description string                 `json:"description,omitempty"`
	Map         []string               `json:"map,omitempty"`
	Checks      []*ClusterMappingCheck `json:"checks,omitempty"`
	Digest      string                 `json:"digest,omitempty"`
}

ClusterDirMapping describes a single directory mapping. The "map" field is a list of PVE property-strings ("node=...,path=...") rather than structured objects — that's what the API returns.

type ClusterDirMappingOptions added in v0.6.0 

type ClusterDirMappingOptions struct {
	ID          string   `json:"id,omitempty"`
	Description string   `json:"description,omitempty"`
	Map         []string `json:"map,omitempty"`
	Digest      string   `json:"digest,omitempty"`
	Delete      string   `json:"delete,omitempty"`
}

ClusterDirMappingOptions is the create/update payload for dir mappings.

type ClusterDirMappings added in v0.6.0 

type ClusterDirMappings []*ClusterDirMapping

ClusterDirMappings is the list payload returned by GET /cluster/mapping/dir.

type ClusterJobIndexEntry added in v0.6.0 

type ClusterJobIndexEntry struct {
	SubDir string `json:"subdir,omitempty"`
}

ClusterJobIndexEntry is one row in the /cluster/jobs directory index.

type ClusterJoinInfo added in v0.7.0 

type ClusterJoinInfo struct {
	ConfigDigest  string                 `json:"config_digest,omitempty"`
	PreferredNode string                 `json:"preferred_node,omitempty"`
	NodeList      []*ClusterJoinNodeInfo `json:"nodelist,omitempty"`
	// Totem is the corosync totem subtree as returned by PVE — open shape
	// because the config can carry arbitrary corosync-format keys.
	Totem map[string]any `json:"totem,omitempty"`
}

ClusterJoinInfo is the response shape of GET /cluster/config/join — the payload a new node needs (or that pvecm consumes) to join the cluster.

type ClusterJoinNodeInfo added in v0.7.0 

type ClusterJoinNodeInfo struct {
	Name        string `json:"name,omitempty"`
	NodeID      int    `json:"nodeid,omitempty"`
	PVEAddr     string `json:"pve_addr,omitempty"`
	PVEFP       string `json:"pve_fp,omitempty"` // SHA-256 certificate fingerprint
	QuorumVotes int    `json:"quorum_votes,omitempty"`
	Ring0Addr   string `json:"ring0_addr,omitempty"`
}

ClusterJoinNodeInfo is one entry in the join-info nodelist.

type ClusterJoinOptions added in v0.7.0 

type ClusterJoinOptions struct {
	Hostname    string `json:"hostname,omitempty"`    // required: existing cluster member
	Password    string `json:"password,omitempty"`    // required: root password of peer
	Fingerprint string `json:"fingerprint,omitempty"` // required: peer SHA-256 cert FP
	// Force, when true, suppresses the "node already exists" error.
	// PVE schema is boolean; pointer keeps an unset field out of the body.
	Force  *bool  `json:"force,omitempty"`
	NodeID int    `json:"nodeid,omitempty"`
	Votes  int    `json:"votes,omitempty"`
	Link0  string `json:"link0,omitempty"` // [address=]<IP>[,priority=<int>]
	Link1  string `json:"link1,omitempty"`
	Link2  string `json:"link2,omitempty"`
	Link3  string `json:"link3,omitempty"`
	Link4  string `json:"link4,omitempty"`
	Link5  string `json:"link5,omitempty"`
	Link6  string `json:"link6,omitempty"`
	Link7  string `json:"link7,omitempty"`
}

ClusterJoinOptions is the body of POST /cluster/config/join.

type ClusterLogEntry added in v0.7.0 

type ClusterLogEntry struct {
	Node string `json:"node,omitempty"`
	Time int64  `json:"time,omitempty"`
	UID  int    `json:"uid,omitempty"`
	User string `json:"user,omitempty"`
	Pri  int    `json:"pri,omitempty"`
	Tag  string `json:"tag,omitempty"`
	Pid  int    `json:"pid,omitempty"`
	Msg  string `json:"msg,omitempty"`
	UPID string `json:"upid,omitempty"`
}

ClusterLogEntry is one row from /cluster/log — a single task-log line. PVE's response shape is open (it varies per task kind); we expose the common fields and Extra for the rest.

type ClusterMappingCheck added in v0.6.0 

type ClusterMappingCheck struct {
	Message  string `json:"message,omitempty"`
	Severity string `json:"severity,omitempty"`
}

ClusterMappingCheck captures the optional per-node diagnostic returned when the list endpoints are called with check-node set.

type ClusterMappingIndexEntry added in v0.6.0 

type ClusterMappingIndexEntry struct {
	Name string `json:"name,omitempty"`
}

ClusterMappingIndexEntry is one row in the top-level mapping index.

type ClusterMappings added in v0.6.0 

type ClusterMappings []*ClusterMappingIndexEntry

ClusterMappings is the directory index returned by GET /cluster/mapping.

type ClusterMetricServer added in v0.6.0 

type ClusterMetricServer struct {
	ID            string    `json:"id,omitempty"`
	Type          string    `json:"type,omitempty"`
	Server        string    `json:"server,omitempty"`
	Port          int       `json:"port,omitempty"`
	Disable       IntOrBool `json:"disable,omitempty"`
	APIPathPrefix string    `json:"api-path-prefix,omitempty"`
	Bucket        string    `json:"bucket,omitempty"`
	InfluxDBProto string    `json:"influxdbproto,omitempty"`
	MaxBodySize   uint64    `json:"max-body-size,omitempty"`
	MTU           uint      `json:"mtu,omitempty"`
	Organization  string    `json:"organization,omitempty"`
	Path          string    `json:"path,omitempty"`
	Proto         string    `json:"proto,omitempty"`
	Timeout       uint      `json:"timeout,omitempty"`
	Token         string    `json:"token,omitempty"`
	// OpenTelemetry-specific knobs.
	OtelCompression        string    `json:"otel-compression,omitempty"`
	OtelHeaders            string    `json:"otel-headers,omitempty"`
	OtelMaxBodySize        uint64    `json:"otel-max-body-size,omitempty"`
	OtelPath               string    `json:"otel-path,omitempty"`
	OtelProtocol           string    `json:"otel-protocol,omitempty"`
	OtelResourceAttributes string    `json:"otel-resource-attributes,omitempty"`
	OtelTimeout            uint      `json:"otel-timeout,omitempty"`
	OtelVerifySSL          IntOrBool `json:"otel-verify-ssl,omitempty"`
	VerifyCertificate      IntOrBool `json:"verify-certificate,omitempty"`
	Digest                 string    `json:"digest,omitempty"`
}

ClusterMetricServer is the union of fields PVE returns for a single configured metric server. PVE multiplexes graphite / influxdb / opentelemetry plugins behind one config-id; per-plugin fields are populated only when relevant.

type ClusterMetricServerOptions added in v0.6.0 

type ClusterMetricServerOptions struct {
	ID            string `json:"id,omitempty"`
	Type          string `json:"type,omitempty"` // graphite | influxdb | opentelemetry — POST only
	Server        string `json:"server,omitempty"`
	Port          int    `json:"port,omitempty"`
	Disable       *bool  `json:"disable,omitempty"`
	APIPathPrefix string `json:"api-path-prefix,omitempty"`
	Bucket        string `json:"bucket,omitempty"`
	InfluxDBProto string `json:"influxdbproto,omitempty"`
	MaxBodySize   uint64 `json:"max-body-size,omitempty"`
	MTU           uint   `json:"mtu,omitempty"`
	Organization  string `json:"organization,omitempty"`
	Path          string `json:"path,omitempty"`
	Proto         string `json:"proto,omitempty"`
	Timeout       uint   `json:"timeout,omitempty"`
	Token         string `json:"token,omitempty"`
	// OpenTelemetry-specific knobs.
	OtelCompression        string `json:"otel-compression,omitempty"`
	OtelHeaders            string `json:"otel-headers,omitempty"`
	OtelMaxBodySize        uint64 `json:"otel-max-body-size,omitempty"`
	OtelPath               string `json:"otel-path,omitempty"`
	OtelProtocol           string `json:"otel-protocol,omitempty"`
	OtelResourceAttributes string `json:"otel-resource-attributes,omitempty"`
	OtelTimeout            uint   `json:"otel-timeout,omitempty"`
	OtelVerifySSL          *bool  `json:"otel-verify-ssl,omitempty"`    // PVE default true; pointer so unset doesn't flip server-side
	VerifyCertificate      *bool  `json:"verify-certificate,omitempty"` // PVE default true; pointer to avoid silently disabling TLS verification
	Digest                 string `json:"digest,omitempty"`             // PUT only — optimistic concurrency
	Delete                 string `json:"delete,omitempty"`             // PUT only — comma-separated keys to clear
}

ClusterMetricServerOptions is the create/update payload. POST requires id+type; PUT uses id from the URL and accepts a "delete" comma list to unset keys.

type ClusterMetricServerSummary added in v0.6.0 

type ClusterMetricServerSummary struct {
	ID      string    `json:"id,omitempty"`
	Type    string    `json:"type,omitempty"`
	Server  string    `json:"server,omitempty"`
	Port    int       `json:"port,omitempty"`
	Disable IntOrBool `json:"disable,omitempty"`
}

ClusterMetricServerSummary is the trimmed shape returned by the list endpoint. The detailed GET /cluster/metrics/server/{id} returns the full plugin config in ClusterMetricServer.

type ClusterMetricServers added in v0.6.0 

type ClusterMetricServers []*ClusterMetricServerSummary

ClusterMetricServers is the list payload returned by GET /cluster/metrics/server.

type ClusterNotificationGotifyEndpoint added in v0.6.0 

type ClusterNotificationGotifyEndpoint struct {
	Name    string    `json:"name,omitempty"`
	Server  string    `json:"server,omitempty"`
	Comment string    `json:"comment,omitempty"`
	Disable IntOrBool `json:"disable,omitempty"`
	Origin  string    `json:"origin,omitempty"`
	Digest  string    `json:"digest,omitempty"`
}

ClusterNotificationGotifyEndpoint is a Gotify endpoint configuration. The `token` field is write-only on PVE — GET never returns it.

type ClusterNotificationGotifyOptions added in v0.6.0 

type ClusterNotificationGotifyOptions struct {
	Name    string   `json:"name,omitempty"`
	Server  string   `json:"server,omitempty"`
	Token   string   `json:"token,omitempty"`
	Comment string   `json:"comment,omitempty"`
	Disable *bool    `json:"disable,omitempty"`
	Digest  string   `json:"digest,omitempty"`
	Delete  []string `json:"delete,omitempty"`
}

ClusterNotificationGotifyOptions is the create/update payload for gotify.

type ClusterNotificationIndex added in v0.6.0 

type ClusterNotificationIndex []*ClusterNotificationIndexEntry

ClusterNotificationIndex is the top-level directory under /cluster/notifications.

type ClusterNotificationIndexEntry added in v0.6.0 

type ClusterNotificationIndexEntry struct {
	Name string `json:"name,omitempty"`
}

ClusterNotificationIndexEntry is one row in the notifications index.

type ClusterNotificationMatcher added in v0.6.0 

type ClusterNotificationMatcher struct {
	Name          string    `json:"name,omitempty"`
	Comment       string    `json:"comment,omitempty"`
	Mode          string    `json:"mode,omitempty"` // all | any
	Disable       IntOrBool `json:"disable,omitempty"`
	InvertMatch   IntOrBool `json:"invert-match,omitempty"`
	MatchCalendar []string  `json:"match-calendar,omitempty"`
	MatchField    []string  `json:"match-field,omitempty"`
	MatchSeverity []string  `json:"match-severity,omitempty"`
	Target        []string  `json:"target,omitempty"`
	Origin        string    `json:"origin,omitempty"`
	Digest        string    `json:"digest,omitempty"`
}

ClusterNotificationMatcher is a single matcher.

type ClusterNotificationMatcherField added in v0.6.0 

type ClusterNotificationMatcherField struct {
	Name string `json:"name,omitempty"`
}

ClusterNotificationMatcherField is a row from /cluster/notifications/matcher-fields.

type ClusterNotificationMatcherFieldValue added in v0.6.0 

type ClusterNotificationMatcherFieldValue struct {
	Field   string `json:"field,omitempty"`
	Value   string `json:"value,omitempty"`
	Comment string `json:"comment,omitempty"`
}

ClusterNotificationMatcherFieldValue is a row from /cluster/notifications/matcher-field-values.

type ClusterNotificationMatcherOptions added in v0.6.0 

type ClusterNotificationMatcherOptions struct {
	Name          string   `json:"name,omitempty"`
	Comment       string   `json:"comment,omitempty"`
	Mode          string   `json:"mode,omitempty"`
	Disable       *bool    `json:"disable,omitempty"`
	InvertMatch   *bool    `json:"invert-match,omitempty"`
	MatchCalendar []string `json:"match-calendar,omitempty"`
	MatchField    []string `json:"match-field,omitempty"`
	MatchSeverity []string `json:"match-severity,omitempty"`
	Target        []string `json:"target,omitempty"`
	Digest        string   `json:"digest,omitempty"`
	Delete        []string `json:"delete,omitempty"`
}

ClusterNotificationMatcherOptions is the create/update payload for matchers. Delete is an array of keys (not a comma-string) per PVE schema.

type ClusterNotificationSMTPEndpoint added in v0.6.0 

type ClusterNotificationSMTPEndpoint struct {
	Name        string    `json:"name,omitempty"`
	Server      string    `json:"server,omitempty"`
	Port        int       `json:"port,omitempty"`
	Mode        string    `json:"mode,omitempty"` // insecure | starttls | tls
	Username    string    `json:"username,omitempty"`
	FromAddress string    `json:"from-address,omitempty"`
	Author      string    `json:"author,omitempty"`
	MailTo      []string  `json:"mailto,omitempty"`
	MailToUser  []string  `json:"mailto-user,omitempty"`
	Comment     string    `json:"comment,omitempty"`
	Disable     IntOrBool `json:"disable,omitempty"`
	Origin      string    `json:"origin,omitempty"`
	Digest      string    `json:"digest,omitempty"`
}

ClusterNotificationSMTPEndpoint is an SMTP endpoint. Password is write-only.

type ClusterNotificationSMTPOptions added in v0.6.0 

type ClusterNotificationSMTPOptions struct {
	Name        string   `json:"name,omitempty"`
	Server      string   `json:"server,omitempty"`
	Port        int      `json:"port,omitempty"`
	Mode        string   `json:"mode,omitempty"`
	Username    string   `json:"username,omitempty"`
	Password    string   `json:"password,omitempty"`
	FromAddress string   `json:"from-address,omitempty"`
	Author      string   `json:"author,omitempty"`
	MailTo      []string `json:"mailto,omitempty"`
	MailToUser  []string `json:"mailto-user,omitempty"`
	Comment     string   `json:"comment,omitempty"`
	Disable     *bool    `json:"disable,omitempty"`
	Digest      string   `json:"digest,omitempty"`
	Delete      []string `json:"delete,omitempty"`
}

ClusterNotificationSMTPOptions is the create/update payload for smtp.

type ClusterNotificationSendmailEndpoint added in v0.6.0 

type ClusterNotificationSendmailEndpoint struct {
	Name        string    `json:"name,omitempty"`
	Author      string    `json:"author,omitempty"`
	FromAddress string    `json:"from-address,omitempty"`
	MailTo      []string  `json:"mailto,omitempty"`
	MailToUser  []string  `json:"mailto-user,omitempty"`
	Comment     string    `json:"comment,omitempty"`
	Disable     IntOrBool `json:"disable,omitempty"`
	Origin      string    `json:"origin,omitempty"`
	Digest      string    `json:"digest,omitempty"`
}

ClusterNotificationSendmailEndpoint is a sendmail endpoint.

type ClusterNotificationSendmailOptions added in v0.6.0 

type ClusterNotificationSendmailOptions struct {
	Name        string   `json:"name,omitempty"`
	Author      string   `json:"author,omitempty"`
	FromAddress string   `json:"from-address,omitempty"`
	MailTo      []string `json:"mailto,omitempty"`
	MailToUser  []string `json:"mailto-user,omitempty"`
	Comment     string   `json:"comment,omitempty"`
	Disable     *bool    `json:"disable,omitempty"`
	Digest      string   `json:"digest,omitempty"`
	Delete      []string `json:"delete,omitempty"`
}

ClusterNotificationSendmailOptions is the create/update payload for sendmail.

type ClusterNotificationTarget added in v0.6.0 

type ClusterNotificationTarget struct {
	Name    string    `json:"name,omitempty"`
	Type    string    `json:"type,omitempty"`
	Comment string    `json:"comment,omitempty"`
	Origin  string    `json:"origin,omitempty"`
	Disable IntOrBool `json:"disable,omitempty"`
}

ClusterNotificationTarget is a row from /cluster/notifications/targets — a flattened view across all endpoint plugin types (sendmail/gotify/smtp/webhook).

type ClusterNotificationWebhookEndpoint added in v0.6.0 

type ClusterNotificationWebhookEndpoint struct {
	Name    string    `json:"name,omitempty"`
	URL     string    `json:"url,omitempty"`
	Method  string    `json:"method,omitempty"` // post | put | get
	Header  []string  `json:"header,omitempty"`
	Body    string    `json:"body,omitempty"`
	Secret  []string  `json:"secret,omitempty"`
	Comment string    `json:"comment,omitempty"`
	Disable IntOrBool `json:"disable,omitempty"`
	Origin  string    `json:"origin,omitempty"`
	Digest  string    `json:"digest,omitempty"`
}

ClusterNotificationWebhookEndpoint is a webhook endpoint. The header / secret arrays use PVE property-string format ("name=...,value=<base64>"); body is already base64-encoded on the wire.

type ClusterNotificationWebhookOptions added in v0.6.0 

type ClusterNotificationWebhookOptions struct {
	Name    string   `json:"name,omitempty"`
	URL     string   `json:"url,omitempty"`
	Method  string   `json:"method,omitempty"`
	Header  []string `json:"header,omitempty"`
	Body    string   `json:"body,omitempty"`
	Secret  []string `json:"secret,omitempty"`
	Comment string   `json:"comment,omitempty"`
	Disable *bool    `json:"disable,omitempty"`
	Digest  string   `json:"digest,omitempty"`
	Delete  []string `json:"delete,omitempty"`
}

ClusterNotificationWebhookOptions is the create/update payload for webhook.

type ClusterOptionsResponse added in v0.7.0 

type ClusterOptionsResponse struct {
	BWLimit     string `json:"bwlimit,omitempty"`
	ConsentText string `json:"consent-text,omitempty"`
	Console     string `json:"console,omitempty"` // applet | vv | html5 | xtermjs
	Description string `json:"description,omitempty"`
	EmailFrom   string `json:"email_from,omitempty"`
	Fencing     string `json:"fencing,omitempty"` // watchdog (default) | hardware | both
	HTTPProxy   string `json:"http_proxy,omitempty"`
	Keyboard    string `json:"keyboard,omitempty"`
	Language    string `json:"language,omitempty"`
	MACPrefix   string `json:"mac_prefix,omitempty"`
	MaxWorkers  int    `json:"max_workers,omitempty"`
	Migration   string `json:"migration,omitempty"`
	// MigrationUnsecure: deprecated in favor of migration=insecure. PVE
	// schema is boolean (no documented default beyond "off"); pointer keeps
	// the field out of the body when callers leave it unset.
	MigrationUnsecure *bool  `json:"migration_unsecure,omitempty"`
	RegisteredTags    string `json:"registered-tags,omitempty"`

	// Extra captures every other top-level key PVE returned (HA, CRS,
	// replication, notify, location, tag-style, u2f, webauthn, next-id, etc.).
	// It is populated by a custom UnmarshalJSON; on the way back through
	// ClusterOptionsUpdate.Extra it is sent verbatim.
	Extra map[string]any `json:"-"`
}

ClusterOptionsResponse is the response of GET /cluster/options — the datacenter.cfg surface. Common scalars are typed; the long tail (HA, CRS, replication, notify, location, tag-style, u2f, webauthn, next-id, etc.) lives in Extra so callers can read every key PVE returned without us having to enumerate the entire wide config space.

func (*ClusterOptionsResponse) UnmarshalJSON added in v0.7.0 

func (r *ClusterOptionsResponse) UnmarshalJSON(data []byte) error

UnmarshalJSON splits the wire payload into typed scalars and the Extra catch-all map so callers can read every key PVE returned without us enumerating the entire wide datacenter.cfg surface.

type ClusterOptionsUpdate added in v0.7.0 

type ClusterOptionsUpdate struct {
	BWLimit           string `json:"bwlimit,omitempty"`
	ConsentText       string `json:"consent-text,omitempty"`
	Console           string `json:"console,omitempty"`
	Description       string `json:"description,omitempty"`
	EmailFrom         string `json:"email_from,omitempty"`
	Fencing           string `json:"fencing,omitempty"`
	HTTPProxy         string `json:"http_proxy,omitempty"`
	Keyboard          string `json:"keyboard,omitempty"`
	Language          string `json:"language,omitempty"`
	MACPrefix         string `json:"mac_prefix,omitempty"`
	MaxWorkers        int    `json:"max_workers,omitempty"`
	Migration         string `json:"migration,omitempty"`
	MigrationUnsecure *bool  `json:"migration_unsecure,omitempty"` // deprecated; see ClusterOptionsResponse
	RegisteredTags    string `json:"registered-tags,omitempty"`
	// Delete is a comma-separated list of keys to reset to PVE defaults.
	Delete string `json:"delete,omitempty"`
	// Extra is merged into the request body alongside the typed fields,
	// covering the long tail of datacenter.cfg keys (HA, CRS, replication,
	// notify, location, tag-style, u2f, webauthn, next-id, …). Marshaling is
	// handled by a custom MarshalJSON.
	Extra map[string]any `json:"-"`
}

ClusterOptionsUpdate is the body of PUT /cluster/options.

func (ClusterOptionsUpdate) MarshalJSON added in v0.7.0 

func (u ClusterOptionsUpdate) MarshalJSON() ([]byte, error)

MarshalJSON merges Extra into the wire payload alongside the typed scalars. Typed keys take precedence over Extra (a caller mistake — typed scalar should be the source of truth).

type ClusterPCIMapping added in v0.6.0 

type ClusterPCIMapping struct {
	ID                   string                 `json:"id,omitempty"`
	Description          string                 `json:"description,omitempty"`
	Map                  []string               `json:"map,omitempty"`
	Checks               []*ClusterMappingCheck `json:"checks,omitempty"`
	MDev                 IntOrBool              `json:"mdev,omitempty"`
	LiveMigrationCapable IntOrBool              `json:"live-migration-capable,omitempty"`
	Digest               string                 `json:"digest,omitempty"`
}

ClusterPCIMapping describes a logical PCI device mapping.

type ClusterPCIMappingOptions added in v0.6.0 

type ClusterPCIMappingOptions struct {
	ID                   string   `json:"id,omitempty"`
	Description          string   `json:"description,omitempty"`
	Map                  []string `json:"map,omitempty"`
	MDev                 bool     `json:"mdev,omitempty"`
	LiveMigrationCapable bool     `json:"live-migration-capable,omitempty"`
	Digest               string   `json:"digest,omitempty"`
	Delete               string   `json:"delete,omitempty"`
}

ClusterPCIMappingOptions is the create/update payload for PCI mappings. mdev / live-migration-capable both default to false on PVE, so plain bool with omitempty is safe.

type ClusterPCIMappings added in v0.6.0 

type ClusterPCIMappings []*ClusterPCIMapping

ClusterPCIMappings is the list payload returned by GET /cluster/mapping/pci.

type ClusterRealmSyncJob added in v0.6.0 

type ClusterRealmSyncJob struct {
	ID             string    `json:"id,omitempty"`
	Comment        string    `json:"comment,omitempty"`
	EnableNew      IntOrBool `json:"enable-new,omitempty"`
	Enabled        IntOrBool `json:"enabled,omitempty"`
	LastRun        int64     `json:"last-run,omitempty"`
	NextRun        int64     `json:"next-run,omitempty"`
	Realm          string    `json:"realm,omitempty"`
	RemoveVanished string    `json:"remove-vanished,omitempty"`
	Schedule       string    `json:"schedule,omitempty"`
	Scope          string    `json:"scope,omitempty"`
}

ClusterRealmSyncJob is the GET shape for a realm-sync job. PVE returns Enabled / EnableNew as integers; using IntOrBool to stay safe.

type ClusterRealmSyncJobOptions added in v0.6.0 

type ClusterRealmSyncJobOptions struct {
	Comment        string `json:"comment,omitempty"`
	EnableNew      *bool  `json:"enable-new,omitempty"` // PVE default true; pointer so unset doesn't flip
	Enabled        *bool  `json:"enabled,omitempty"`    // PVE default true; pointer so unset doesn't flip
	Realm          string `json:"realm,omitempty"`      // POST only — identifies the auth realm
	RemoveVanished string `json:"remove-vanished,omitempty"`
	Schedule       string `json:"schedule,omitempty"` // required on create
	Scope          string `json:"scope,omitempty"`
	Delete         string `json:"delete,omitempty"` // PUT only — comma-separated keys to clear
}

ClusterRealmSyncJobOptions is the body for both POST (create) and PUT (update). Pointer fields preserve PVE's defaults when unset.

type ClusterResource 

type ClusterResource struct {
	ID         string  `json:"id"`
	Type       string  `json:"type"`
	CGroupMode uint64  `json:"cgroup-mode,omitempty"`
	Content    string  `json:",omitempty"`
	CPU        float64 `json:",omitempty"`
	Disk       uint64  `json:",omitempty"` // documented as string but this is an int
	DiskRead   uint64  `json:",omitempty"`
	DiskWrite  uint64  `json:",omitempty"`
	HAstate    string  `json:",omitempty"`
	Level      string  `json:",omitempty"`
	MaxCPU     uint64  `json:",omitempty"`
	MaxDisk    uint64  `json:",omitempty"`
	MaxMem     uint64  `json:",omitempty"`
	Mem        uint64  `json:",omitempty"` // documented as string but this is an int
	Name       string  `json:",omitempty"`
	NetIn      uint64  `json:",omitempty"`
	NetOut     uint64  `json:",omitempty"`
	Node       string  `json:",omitempty"`
	PluginType string  `json:",omitempty"`
	Pool       string  `json:",omitempty"`
	Shared     uint64  `json:",omitempty"`
	Status     string  `json:",omitempty"`
	Storage    string  `json:",omitempty"`
	Tags       string  `json:",omitempty"`
	Template   uint64  `json:",omitempty"`
	Uptime     uint64  `json:",omitempty"`
	VMID       uint64  `json:",omitempty"`
}

type ClusterResources 

type ClusterResources []*ClusterResource

type ClusterScheduleEvent added in v0.6.0 

type ClusterScheduleEvent struct {
	Timestamp int64  `json:"timestamp,omitempty"`
	UTC       string `json:"utc,omitempty"`
}

ClusterScheduleEvent is one firing in the schedule-analyze preview — a human-readable UTC timestamp + UNIX epoch.

type ClusterStorage added in v0.1.1 

type ClusterStorage struct {
	Content  string
	Digest   string
	Storage  string
	Type     string
	Shared   int    `json:",omitempty"`
	Nodes    string `json:",omitempty"`
	Thinpool string `json:",omitempty"`
	Path     string `json:",omitempty"`
	VgName   string `json:",omitempty"`
	// contains filtered or unexported fields
}

type ClusterStorageOptions added in v0.1.1 

type ClusterStorageOptions struct {
	Name  string
	Value string
}

type ClusterStorages added in v0.1.1 

type ClusterStorages []*ClusterStorage

type ClusterUSBMapping added in v0.6.0 

type ClusterUSBMapping struct {
	ID          string                 `json:"id,omitempty"`
	Description string                 `json:"description,omitempty"`
	Map         []string               `json:"map,omitempty"`
	Error       []*ClusterMappingCheck `json:"error,omitempty"`
	Digest      string                 `json:"digest,omitempty"`
}

ClusterUSBMapping describes a logical USB device mapping. USB uses "error" instead of "checks" in the list response (PVE quirk — not normalised).

type ClusterUSBMappingOptions added in v0.6.0 

type ClusterUSBMappingOptions struct {
	ID          string   `json:"id,omitempty"`
	Description string   `json:"description,omitempty"`
	Map         []string `json:"map,omitempty"`
	Digest      string   `json:"digest,omitempty"`
	Delete      string   `json:"delete,omitempty"`
}

ClusterUSBMappingOptions is the create/update payload for USB mappings.

type ClusterUSBMappings added in v0.6.0 

type ClusterUSBMappings []*ClusterUSBMapping

ClusterUSBMappings is the list payload returned by GET /cluster/mapping/usb.

type ConsolidationFunction 

type ConsolidationFunction string

type Container 

type Container struct {
	ContainerConfig *ContainerConfig

	CPUs    int
	MaxDisk uint64
	MaxMem  uint64
	MaxSwap uint64
	Name    string
	Node    string
	Status  string
	Tags    string
	Uptime  uint64
	VMID    StringOrUint64
	// contains filtered or unexported fields
}

func (*Container) AddTag added in v0.1.2 

func (c *Container) AddTag(ctx context.Context, value string) (*Task, error)

AddTag appends the passed value to TagsSlice and updates Tags via c.Config If accurate state is important, then reassign the value of Container after the task has completed.

func (*Container) Clone 

func (c *Container) Clone(ctx context.Context, params *ContainerCloneOptions) (newid int, task *Task, err error)

func (*Container) Config 

func (c *Container) Config(ctx context.Context, options ...ContainerOption) (*Task, error)

Config sets ContainerOptions for Container see https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/lxc/{vmid}/config for available attributes

func (*Container) Delete 

func (c *Container) Delete(ctx context.Context, params *ContainerDeleteOptions) (task *Task, err error)

Delete removes the container. Pass a non-nil *ContainerDeleteOptions to force-delete a running container (Force), purge it from related configurations (Purge), or destroy unreferenced disks (DestroyUnreferencedDisks). nil applies the API defaults.

func (*Container) DeleteFirewallAlias 

func (c *Container) DeleteFirewallAlias(ctx context.Context, name string) error

func (*Container) DeleteFirewallIPSet 

func (c *Container) DeleteFirewallIPSet(ctx context.Context, name string, force bool) error

func (*Container) DeleteFirewallIPSetEntry added in v0.2.3 

func (c *Container) DeleteFirewallIPSetEntry(ctx context.Context, name string, cidr string, digest string) error

func (*Container) DirIndex added in v0.6.0 

func (c *Container) DirIndex(ctx context.Context) (entries []*ContainerDirIndexEntry, err error)

DirIndex returns the per-container directory index (GET /nodes/{node}/lxc/{vmid}) — one entry per sub-resource (config, status, snapshot, firewall, …). The sub-resources themselves are wrapped as their own methods on *Container; this is mostly useful for discovery.

func (*Container) Feature 

func (c *Container) Feature(ctx context.Context) (hasFeature bool, err error)

func (*Container) Firewall 

func (c *Container) Firewall(ctx context.Context) (firewall *Firewall, err error)

func (*Container) FirewallLog added in v0.6.0 

func (c *Container) FirewallLog(ctx context.Context) (entries []*FirewallLogEntry, err error)

FirewallLog returns the per-container firewall log entries.

func (*Container) FirewallRefs added in v0.6.0 

func (c *Container) FirewallRefs(ctx context.Context) (refs []*FirewallRef, err error)

FirewallRefs returns the IPSets and aliases referenceable from this container's firewall rules (cluster-level + node-level + container-level).

func (*Container) FirewallRule added in v0.7.0 

func (c *Container) FirewallRule(pos int) *FirewallRule

FirewallRule returns a *FirewallRule wired to the container's firewall scope at the given position. The returned instance is a lazy handle — call Get(ctx) to populate it from /firewall/rules/{pos}.

func (*Container) FirewallRules 

func (c *Container) FirewallRules(ctx context.Context) (rules []*FirewallRule, err error)

FirewallRules lists firewall rules for the container. Returned rules carry the parent context required to call (*FirewallRule).Get/Update/Delete.

func (*Container) GetFirewallAlias 

func (c *Container) GetFirewallAlias(ctx context.Context, name string) (alias *FirewallAlias, err error)

func (*Container) GetFirewallAliases 

func (c *Container) GetFirewallAliases(ctx context.Context) (aliases []*FirewallAlias, err error)

func (*Container) GetFirewallIPSet 

func (c *Container) GetFirewallIPSet(ctx context.Context) (ipsets []*FirewallIPSet, err error)

func (*Container) GetFirewallIPSetEntries added in v0.2.3 

func (c *Container) GetFirewallIPSetEntries(ctx context.Context, name string) (entries []*FirewallIPSetEntry, err error)

func (*Container) GetFirewallIPSetEntry added in v0.2.3 

func (c *Container) GetFirewallIPSetEntry(ctx context.Context, name string, cidr string) (entry *FirewallIPSetEntry, err error)

func (*Container) GetFirewallOptions 

func (c *Container) GetFirewallOptions(ctx context.Context) (options *FirewallVirtualMachineOption, err error)

func (*Container) HasTag added in v0.1.2 

func (c *Container) HasTag(value string) bool

HasTag returns if a Tag is present in TagSlice

func (*Container) Interfaces 

func (c *Container) Interfaces(ctx context.Context) (interfaces ContainerInterfaces, err error)

func (*Container) Migrate 

func (c *Container) Migrate(ctx context.Context, params *ContainerMigrateOptions) (task *Task, err error)

func (*Container) MigratePreconditions added in v0.6.0 

func (c *Container) MigratePreconditions(ctx context.Context, target string) (preconditions *ContainerMigratePreconditions, err error)

MigratePreconditions returns the precondition check for migrating this container (GET /nodes/{node}/lxc/{vmid}/migrate). If target is non-empty, PVE evaluates the check against that specific target node; otherwise it reports which nodes are allowed/not-allowed and any local-disk constraints.

func (*Container) MigrationTunnel added in v0.6.0 

func (c *Container) MigrationTunnel(ctx context.Context, options *ContainerMigrationTunnelOptions) (tunnel *ContainerMigrationTunnel, err error)

MigrationTunnel opens a migration tunnel for this container (POST /nodes/{node}/lxc/{vmid}/mtunnel) and returns the Unix socket path, authentication ticket, and worker UPID.

PVE marks this endpoint as "for internal use by VM migration" — callers should generally use Migrate or the higher-level migration flow rather than wiring this up directly. Wrapped here for full API surface coverage.

func (*Container) MigrationTunnelWebSocketPath added in v0.6.0 

func (c *Container) MigrationTunnelWebSocketPath(tunnel *ContainerMigrationTunnel) string

MigrationTunnelWebSocketPath returns the path callers can pass to a websocket dialer to upgrade the migration tunnel returned by MigrationTunnel (GET /nodes/{node}/lxc/{vmid}/mtunnelwebsocket).

PVE marks this endpoint as "for internal use by VM migration"; this helper just builds the path with the correct query string. There is no generic Client helper for migration-tunnel websockets — dial it directly with the authenticated cookies/headers if you need to consume it.

func (*Container) MoveVolume 

func (c *Container) MoveVolume(ctx context.Context, params *VirtualMachineMoveDiskOptions) (task *Task, err error)

func (*Container) NewFirewallAlias 

func (c *Container) NewFirewallAlias(ctx context.Context, alias *FirewallAlias) error

func (*Container) NewFirewallIPSet 

func (c *Container) NewFirewallIPSet(ctx context.Context, ipset FirewallIPSetCreationOption) error

func (*Container) NewFirewallIPSetEntry added in v0.2.3 

func (c *Container) NewFirewallIPSetEntry(ctx context.Context, name string, entry FirewallIPSetEntryCreationOption) error

func (*Container) NewFirewallRule 

func (c *Container) NewFirewallRule(ctx context.Context, rule *FirewallRule) error

NewFirewallRule creates a firewall rule on the container. After a successful POST the rule is wired with parent context so subsequent Update/Delete/Get calls route correctly. Note: PVE's POST does not return the assigned position; callers that need it should re-list via FirewallRules.

func (*Container) NewSnapshot 

func (c *Container) NewSnapshot(ctx context.Context, snapName string) (task *Task, err error)

NewSnapshot creates a snapshot of the container and returns the worker task. The returned snapshot's metadata is reachable via c.Snapshot(name) once the task completes.

func (*Container) Pending added in v0.6.0 

func (c *Container) Pending(ctx context.Context) (pending []*ContainerPending, err error)

Pending returns the container's staged config changes — keys whose desired value differs from the running value. Empty list when the container's live config matches its on-disk config.

func (*Container) Ping added in v0.4.0 

func (c *Container) Ping(ctx context.Context) error

func (*Container) RRD added in v0.6.0 

func (c *Container) RRD(ctx context.Context, ds string, timeframe Timeframe, consolidationFunction ...ConsolidationFunction) (rrd *ContainerRRD, err error)

RRD asks PVE to render a single timeframe PNG on the server and returns its on-disk filename (the file lives in PVE's rrdcached dir). Most callers want RRDData instead for numeric series; this exists for API parity.

func (*Container) RRDData 

func (c *Container) RRDData(ctx context.Context, timeframe Timeframe, consolidationFunction ...ConsolidationFunction) (rrddata []*RRDData, err error)

func (*Container) Reboot 

func (c *Container) Reboot(ctx context.Context) (task *Task, err error)

func (*Container) RemoteMigrate added in v0.6.0 

func (c *Container) RemoteMigrate(ctx context.Context, params *ContainerRemoteMigrateOptions) (task *Task, err error)

RemoteMigrate triggers a cross-cluster migration of this container. The target endpoint is an API-token bundle string per PVE's pvesh docs.

func (*Container) RemoveTag added in v0.1.2 

func (c *Container) RemoveTag(ctx context.Context, value string) (*Task, error)

RemoveTag removes the passed value from TagsSlice and updates Tags via c.Config If accurate state is important, then reassign the value of Container after the task has completed.

func (*Container) Resize 

func (c *Container) Resize(ctx context.Context, disk, size string) (task *Task, err error)

func (*Container) Resume 

func (c *Container) Resume(ctx context.Context) (task *Task, err error)

func (*Container) Shutdown 

func (c *Container) Shutdown(ctx context.Context, force bool, timeout int) (task *Task, err error)

func (*Container) Snapshot added in v0.7.0 

func (c *Container) Snapshot(name string) *ContainerSnapshot

Snapshot constructs a handle to a single snapshot by name. It performs no API call; the returned *ContainerSnapshot is wired to the container's client and node/vmid so its instance methods (Rollback, Delete, Config, UpdateConfig, SubResources) target the correct snapshot path.

func (*Container) Snapshots 

func (c *Container) Snapshots(ctx context.Context) (snapshots []*ContainerSnapshot, err error)

Snapshots lists every snapshot of the container. Each returned *ContainerSnapshot has its client/Node/VMID pre-populated so callers can invoke instance methods (Rollback, Delete, Config, …) directly.

func (*Container) SpiceProxy added in v0.6.0 

func (c *Container) SpiceProxy(ctx context.Context) (spice *SpiceProxy, err error)

SpiceProxy returns SPICE proxy connection info for the container. PVE supports SPICE primarily for QEMU VMs; LXC support depends on the container's console configuration and may error on most setups.

func (*Container) SplitTags added in v0.1.2 

func (c *Container) SplitTags()

SplitTags sets ContainerConfig TagsSlice my splitting the value of ContainerConfig.Tags with TagSeparator

func (*Container) Start 

func (c *Container) Start(ctx context.Context) (task *Task, err error)

func (*Container) StatusIndex added in v0.6.0 

func (c *Container) StatusIndex(ctx context.Context) (entries []*ContainerStatusIndexEntry, err error)

StatusIndex returns the container status directory index (GET /nodes/{node}/lxc/{vmid}/status) — one entry per status sub-command (current, start, stop, …). The operations are wrapped as Start/Stop/etc. on *Container.

func (*Container) Stop 

func (c *Container) Stop(ctx context.Context) (task *Task, err error)

func (*Container) Suspend 

func (c *Container) Suspend(ctx context.Context) (task *Task, err error)

func (*Container) Template 

func (c *Container) Template(ctx context.Context) error

func (*Container) TermProxy 

func (c *Container) TermProxy(ctx context.Context) (term *Term, err error)

func (*Container) TermWebSocket added in v0.1.2 

func (c *Container) TermWebSocket(term *Term) (chan []byte, chan []byte, chan error, func() error, error)

func (*Container) UpdateFirewallAlias 

func (c *Container) UpdateFirewallAlias(ctx context.Context, name string, alias *FirewallAlias) error

func (*Container) UpdateFirewallIPSetEntry added in v0.2.3 

func (c *Container) UpdateFirewallIPSetEntry(ctx context.Context, name string, cidr string, entry *FirewallIPSetEntryUpdateOption) error

func (*Container) UpdateFirewallOptions 

func (c *Container) UpdateFirewallOptions(ctx context.Context, options *FirewallVirtualMachineOption) error

func (*Container) VNCProxy 

func (c *Container) VNCProxy(ctx context.Context, vncOptions VNCProxyOptions) (vnc *VNC, err error)

func (*Container) VNCWebSocket 

func (c *Container) VNCWebSocket(vnc *VNC) (chan []byte, chan []byte, chan error, func() error, error)

type ContainerCloneOptions 

type ContainerCloneOptions struct {
	NewID int `json:"newid"`
	// BWLimit — see VirtualMachineCloneOptions.BWLimit; same datacenter
	// default applies for container clones.
	BWLimit     *uint64   `json:"bwlimit,omitempty"`
	Description string    `json:"description,omitempty"`
	Full        IntOrBool `json:"full,omitempty"`
	Hostname    string    `json:"hostname,omitempty"`
	Pool        string    `json:"pool,omitempty"`
	SnapName    string    `json:"snapname,omitempty"`
	Storage     string    `json:"storage,omitempty"`
	Target      string    `json:"target,omitempty"`
}

type ContainerConfig added in v0.1.2 

type ContainerConfig struct {
	// Arch — PVE default "amd64". Pointer keeps the server default on edit
	// when the caller leaves the field nil. See #199.
	Arch *string `json:"arch,omitempty"`
	// CMode — PVE default "tty". Switching it on a partial update can
	// break console access; pointer keeps the server default when nil. See #199.
	CMode *string `json:"cmode,omitempty"`
	// Console — PVE default 1 (console enabled). A non-pointer zero would
	// silently disable the container console on any update that didn't set
	// the field. See #178 (boolean wire type) + #199.
	Console  *IntOrBool `json:"console,omitempty"`
	Cores    int        `json:"cores,omitempty"`
	CPULimit int        `json:"cpulimit,omitempty"`
	// CPUUnits — PVE default 1024 (cgroup v1) / 100 (cgroup v2). Plain int
	// would default to 0 and override the server's CPU weight on edit. See #199.
	CPUUnits    *int      `json:"cpuunits,omitempty"`
	Debug       IntOrBool `json:"debug,omitempty"`
	Description string    `json:"description,omitempty"`

	// Indexed devices. Populated by UnmarshalJSON; keys are the on-the-wire
	// form ("net0", "mp42", "dev15", "unused100").
	Devs    map[string]string `json:"-"`
	Mps     map[string]string `json:"-"`
	Nets    map[string]string `json:"-"`
	Unuseds map[string]string `json:"-"`

	Digest     string     `json:"digest"`
	Features   string     `json:"features,omitempty"`
	HookScript string     `json:"hookscript,omitempty"`
	LXC        [][]string `json:"lxc,omitempty"`
	Hostname   string     `json:"hostname,omitempty"`
	Lock       string     `json:"lock,omitempty"`
	// Memory — PVE default 512 (MB). A plain int defaults to 0, which the
	// API rejects on create and which silently shrinks RAM on edit. See #199.
	Memory       *int      `json:"memory,omitempty"`
	Nameserver   string    `json:"nameserver,omitempty"`
	OnBoot       IntOrBool `json:"onboot,omitempty"`
	OSType       string    `json:"ostype,omitempty"`
	Protection   IntOrBool `json:"protection,omitempty"`
	RootFS       string    `json:"rootfs,omitempty"`
	SearchDomain string    `json:"searchdomain,omitempty"`
	Startup      string    `json:"startup,omitempty"`
	// Swap — PVE default 512 (MB). Same trap as Memory: a zero would
	// override the server-side swap allocation on edit. See #199.
	Swap      *int      `json:"swap,omitempty"`
	TagsSlice []string  `json:"-"` // internal helper to manage tags easier
	Tags      string    `json:"tags,omitempty"`
	Template  IntOrBool `json:"template,omitempty"`
	Timezone  string    `json:"timezone,omitempty"`
	// TTY — PVE default 2 (number of getty TTYs). A zero would disable
	// container login TTYs entirely on edit. See #199.
	TTY          *int      `json:"tty,omitempty"`
	Unprivileged IntOrBool `json:"unprivileged,omitempty"`
}

func (*ContainerConfig) UnmarshalJSON added in v0.1.2 

func (cc *ContainerConfig) UnmarshalJSON(data []byte) error

type ContainerDeleteOptions added in v0.6.0 

type ContainerDeleteOptions struct {
	// Force destroys the container even if it is currently running.
	Force IntOrBool `json:"force,omitempty"`
	// Purge also removes the container from all related configurations
	// (backup jobs, replication jobs, HA), in addition to deleting it.
	Purge IntOrBool `json:"purge,omitempty"`
	// DestroyUnreferencedDisks also destroys disks across enabled storages
	// that match the VMID but are not referenced by the container's config.
	DestroyUnreferencedDisks IntOrBool `json:"destroy-unreferenced-disks,omitempty"`
}

ContainerDeleteOptions maps to the optional query parameters that DELETE /nodes/{node}/lxc/{vmid} accepts. A nil *ContainerDeleteOptions passed to Container.Delete is equivalent to all defaults.

type ContainerDirIndexEntry added in v0.6.0 

type ContainerDirIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

ContainerDirIndexEntry is one row of the /nodes/{node}/lxc/{vmid} directory index — each entry names a child resource (config, status, snapshot, firewall, …).

type ContainerInterface 

type ContainerInterface struct {
	HWAddr string `json:"hwaddr,omitempty"`
	Name   string `json:"name,omitempty"`
	Inet   string `json:"inet,omitempty"`
	Inet6  string `json:"inet6,omitempty"`
}

type ContainerInterfaces 

type ContainerInterfaces []*ContainerInterface

type ContainerMigrateOptions 

type ContainerMigrateOptions struct {
	Target string `json:"target"`
	// BWLimit — see VirtualMachineMigrateOptions.BWLimit; same datacenter
	// default applies for container migrations.
	BWLimit *uint64   `json:"bwlimit,omitempty"`
	Online  IntOrBool `json:"online,omitempty"`
	Restart IntOrBool `json:"restart,omitempty"`
}

type ContainerMigratePreconditions added in v0.6.0 

type ContainerMigratePreconditions struct {
	Running         bool                                                          `json:"running"`
	AllowedNodes    []string                                                      `json:"allowed_nodes,omitempty"`
	NotAllowedNodes map[string]*VirtualMachineMigratePreconditionsNotAllowedNodes `json:"not_allowed_nodes,omitempty"`
	LocalDisks      []*VirtualMachineMigratePreconditionsLocalDisk                `json:"local_disks,omitempty"`
	LocalResources  []string                                                      `json:"local_resources,omitempty"`
}

ContainerMigratePreconditions is the response from GET /nodes/{node}/lxc/{vmid}/migrate — the migration precondition check. Re-uses the VM-side sub-types (NotAllowedNodes, LocalDisk) because PVE shares the same migration-constraint shapes between qemu and lxc.

type ContainerMigrationTunnel added in v0.6.0 

type ContainerMigrationTunnel struct {
	Socket string `json:"socket,omitempty"`
	Ticket string `json:"ticket,omitempty"`
	UPID   string `json:"upid,omitempty"`
}

ContainerMigrationTunnel is the response from POST /nodes/{node}/lxc/{vmid}/mtunnel — the migration tunnel handle that MigrationTunnelWebSocketPath consumes.

type ContainerMigrationTunnelOptions added in v0.6.0 

type ContainerMigrationTunnelOptions struct {
	// Bridges is a comma-separated list of network bridges to check
	// availability for. Optional.
	Bridges string `json:"bridges,omitempty"`
	// Storages is a comma-separated list of storages to check permission
	// and availability for. Optional.
	Storages string `json:"storages,omitempty"`
}

ContainerMigrationTunnelOptions are the parameters for POST /nodes/{node}/lxc/{vmid}/mtunnel. PVE marks this endpoint internal — most callers go through Migrate or RemoteMigrate, which manage the tunnel lifecycle themselves.

type ContainerOption 

type ContainerOption struct {
	Name  string
	Value interface{}
}

type ContainerOptions 

type ContainerOptions []*ContainerOption

ContainerOptions A key/value pair used to modify a container(LXC) config Refer to https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/lxc/{vmid}/config for a list of valid values

type ContainerPending added in v0.6.0 

type ContainerPending struct {
	Key     string      `json:"key"`
	Value   interface{} `json:"value,omitempty"`
	Pending interface{} `json:"pending,omitempty"`
	Delete  int         `json:"delete,omitempty"`
}

ContainerPending describes a single staged config change returned by GET /nodes/{node}/lxc/{vmid}/pending. Value is the currently active value; Pending is the value queued for the next start. Delete is set when the key is queued for removal.

type ContainerRRD added in v0.6.0 

type ContainerRRD struct {
	Filename string `json:"filename"`
}

ContainerRRD is the response from GET /nodes/{node}/lxc/{vmid}/rrd. PVE renders a single PNG on the server and returns its on-disk filename; callers typically want RRDData instead for usable numeric series.

type ContainerRemoteMigrateOptions added in v0.6.0 

type ContainerRemoteMigrateOptions struct {
	TargetEndpoint string    `json:"target-endpoint"`
	TargetBridge   string    `json:"target-bridge"`  // "src=tgt,src2=tgt2" map
	TargetStorage  string    `json:"target-storage"` // "src=tgt,src2=tgt2" map
	TargetVMID     int       `json:"target-vmid,omitempty"`
	BWLimit        uint64    `json:"bwlimit,omitempty"`
	Delete         IntOrBool `json:"delete,omitempty"`
	Online         IntOrBool `json:"online,omitempty"`
	Restart        IntOrBool `json:"restart,omitempty"`
	Timeout        uint64    `json:"timeout,omitempty"`
}

ContainerRemoteMigrateOptions configures POST /nodes/{node}/lxc/{vmid}/remote_migrate (cross-cluster migration). TargetEndpoint is the API-token bundle string PVE accepts ("apitoken=PVEAPIToken=... host=... fingerprint=..."); see the pvesh docs for the exact shape.

type ContainerSnapshot 

type ContainerSnapshot struct {

	// Node is the cluster node that hosts the parent container. Populated
	// by the getter and not part of the upstream JSON payload.
	Node string `json:"-"`
	// VMID is the parent container's numeric id. Populated by the getter
	// and not part of the upstream JSON payload.
	VMID int `json:"-"`

	Description          string `json:"description,omitempty"`
	Name                 string `json:"name,omitempty"`
	Parent               string `json:"parent,omitempty"`
	SnapshotCreationTime int64  `json:"snaptime,omitempty"`
	// contains filtered or unexported fields
}

ContainerSnapshot is one entry from GET /nodes/{node}/lxc/{vmid}/snapshot. The unexported client and the parent-identifying Node/VMID fields are populated by (*Container).Snapshots and (*Container).Snapshot so callers can invoke instance methods (Rollback, Delete, Config, UpdateConfig, SubResources) without re-threading those identifiers.

func (*ContainerSnapshot) Config added in v0.7.0 

func (s *ContainerSnapshot) Config(ctx context.Context) (config map[string]interface{}, err error)

Config reads this snapshot's metadata (description, parent, etc.). PVE returns a free-form map since snapshot configs include arbitrary device keys snapshotted at the time of creation.

func (*ContainerSnapshot) Delete added in v0.7.0 

func (s *ContainerSnapshot) Delete(ctx context.Context) (task *Task, err error)

Delete removes this snapshot from the container. Returns the worker task.

func (*ContainerSnapshot) Rollback added in v0.7.0 

func (s *ContainerSnapshot) Rollback(ctx context.Context, start bool) (task *Task, err error)

Rollback rolls the container back to this snapshot. When start is true the container is started after the rollback completes.

func (*ContainerSnapshot) SubResources added in v0.7.0 

func (s *ContainerSnapshot) SubResources(ctx context.Context) (entries []*ContainerSnapshotIndexEntry, err error)

SubResources returns the per-snapshot directory index (GET /nodes/{node}/lxc/{vmid}/snapshot/{snapname}) — one entry per sub-resource (config, rollback) on this snapshot.

func (*ContainerSnapshot) UpdateConfig added in v0.7.0 

func (s *ContainerSnapshot) UpdateConfig(ctx context.Context, options *ContainerSnapshotUpdateOptions) error

UpdateConfig updates this snapshot's metadata. PVE only allows changing the description on this endpoint; pass nil options to clear it.

type ContainerSnapshotIndexEntry added in v0.7.0 

type ContainerSnapshotIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

ContainerSnapshotIndexEntry is one row in the per-snapshot directory index (GET /nodes/{node}/lxc/{vmid}/snapshot/{snapname}) — each entry names a sub-resource on the snapshot (config, rollback).

type ContainerSnapshotUpdateOptions added in v0.6.0 

type ContainerSnapshotUpdateOptions struct {
	Description string `json:"description,omitempty"`
}

ContainerSnapshotUpdateOptions is the body for PUT /snapshot/{name}/config. PVE accepts only the description field on this endpoint.

type ContainerStatusIndexEntry added in v0.6.0 

type ContainerStatusIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

ContainerStatusIndexEntry is one row of the /nodes/{node}/lxc/{vmid}/status directory index — each entry names a status sub-command (current, start, stop, …).

type Containers 

type Containers []*Container

type Content 

type Content struct {
	URL     string
	Node    string
	Storage string `json:",omitempty"`
	Content string `json:",omitempty"`
	VolID   string `json:",omitempty"`
	CTime   uint64 `json:",omitempty"`
	Format  string
	Size    StringOrUint64
	Used    StringOrUint64 `json:",omitempty"`
	Path    string         `json:",omitempty"`
	Notes   string         `json:",omitempty"`
	// contains filtered or unexported fields
}

type Credentials 

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
	Otp      string `json:"otp,omitempty"` // One-time password for Two-factor authentication.
	Path     string `json:"path,omitempty"`
	Privs    string `json:"privs,omitempty"`
	Realm    string `json:"realm,omitempty"`
}

type CustomCPUModel added in v0.7.0 

type CustomCPUModel struct {
	CPUType       string `json:"cputype,omitempty"`
	Flags         string `json:"flags,omitempty"`
	GuestPhysBits int    `json:"guest-phys-bits,omitempty"`
	Hidden        int    `json:"hidden,omitempty"`
	HVVendorID    string `json:"hv-vendor-id,omitempty"`
	Level         int    `json:"level,omitempty"`
	PhysBits      string `json:"phys-bits,omitempty"`
	ReportedModel string `json:"reported-model,omitempty"`
	Digest        string `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

CustomCPUModel is a single custom CPU model definition (the inverse of the `cpu: custom-<name>` field in a VM config). client is populated by the list/getter on the parent; identifying fields drive instance methods.

func (*CustomCPUModel) Delete added in v0.7.0 

func (m *CustomCPUModel) Delete(ctx context.Context) error

Delete removes a custom CPU model definition.

DELETE /cluster/qemu/custom-cpu-models/{cputype}

func (*CustomCPUModel) Read added in v0.7.0 

func (m *CustomCPUModel) Read(ctx context.Context) error

Read populates the receiver with the current definition.

GET /cluster/qemu/custom-cpu-models/{cputype}

func (*CustomCPUModel) Update added in v0.7.0 

func (m *CustomCPUModel) Update(ctx context.Context, opts *CustomCPUModelOptions) error

Update mutates an existing custom CPU model.

PUT /cluster/qemu/custom-cpu-models/{cputype}

type CustomCPUModelOptions added in v0.7.0 

type CustomCPUModelOptions struct {
	CPUType       string `json:"cputype,omitempty"` // required
	Flags         string `json:"flags,omitempty"`
	GuestPhysBits int    `json:"guest-phys-bits,omitempty"`
	// Hidden: do not identify as a KVM virtual machine. PVE default 0,
	// matches Go zero — plain bool with omitempty would still flip it when
	// the caller omits the field, so we keep an int matching the wire shape
	// and rely on omitempty.
	Hidden     int    `json:"hidden,omitempty"`
	HVVendorID string `json:"hv-vendor-id,omitempty"`
	Level      int    `json:"level,omitempty"`
	PhysBits   string `json:"phys-bits,omitempty"`
	// ReportedModel is required on POST (PVE schema marks it optional=0).
	ReportedModel string `json:"reported-model,omitempty"`
	Digest        string `json:"digest,omitempty"` // PUT only — optimistic concurrency
	Delete        string `json:"delete,omitempty"` // PUT only — comma list of keys to reset
}

CustomCPUModelOptions is the body of POST /cluster/qemu/custom-cpu-models (create) and PUT /cluster/qemu/custom-cpu-models/{cputype} (update).

type CustomCertificate 

type CustomCertificate struct {
	Certificates string `json:"certificates,omitempty"` // PEM encoded certificate (chain)
	Force        bool   `json:"force,omitempty"`        // overwrite existing certificate
	Key          string `json:"key,omitempty"`          // PEM encoded private key
	Restart      bool   `json:"restart,omitempty"`      // restart pveproxy
}

type Disk added in v0.6.0 

type Disk struct {
	DevPath      string    `json:"devpath,omitempty"`
	Used         string    `json:"used,omitempty"`
	GPT          IntOrBool `json:"gpt,omitempty"`
	Size         uint64    `json:"size,omitempty"`
	Health       string    `json:"health,omitempty"`
	Model        string    `json:"model,omitempty"`
	Serial       string    `json:"serial,omitempty"`
	Type         string    `json:"type,omitempty"`
	Vendor       string    `json:"vendor,omitempty"`
	WWN          string    `json:"wwn,omitempty"`
	ByIDLink     string    `json:"by_id_link,omitempty"`
	Wearout      string    `json:"wearout,omitempty"`
	OSDID        int       `json:"osdid,omitempty"`
	OSDEncrypted IntOrBool `json:"osdencrypted,omitempty"`
	Parent       string    `json:"parent,omitempty"`
	RPM          int       `json:"rpm,omitempty"`
	BLKSize      int       `json:"blocksize,omitempty"`
	MountPoint   string    `json:"mounted,omitempty"`
	Vendor2      string    `json:"vendor2,omitempty"`
}

Disk is one row returned by GET /nodes/{node}/disks/list. Fields are best-effort optional — PVE omits keys that don't apply to a given device.

type DiskSMART added in v0.6.0 

type DiskSMART struct {
	Health     string           `json:"health,omitempty"`
	Type       string           `json:"type,omitempty"`
	Text       string           `json:"text,omitempty"`
	Attributes []map[string]any `json:"attributes,omitempty"`
}

DiskSMART is the response from GET /nodes/{node}/disks/smart.

type Domain 

type Domain struct {
	Realm string `json:",omitempty"`
	Type  string `json:",omitempty"`

	// options https://pve.proxmox.com/pve-docs/api-viewer/#/access/domains
	ACRValues      string    `json:"acr-values,omitempty"`
	AutoCreate     IntOrBool `json:"autocreate,omitempty"`
	BaseDN         string    `json:"base_dn,omitempty"`
	BindDN         string    `json:"bind_dn,omitempty"`
	CAPath         string    `json:"capath,omitempty"`
	CaseSensitive  IntOrBool `json:"case-sensitive,omitempty"`
	Cert           string    `json:"cert,omitempty"`
	CertKey        string    `json:"certkey,omitempty"`
	ClientID       string    `json:"client-id,omitempty"`
	ClientKey      string    `json:"client-key,omitempty"`
	Comment        string    `json:"comment,omitempty"`
	Default        IntOrBool `json:"default,omitempty"`
	DeleteList     string    `json:"delete,omitempty"` // a list of settings you want to delete?
	Digest         string    `json:"digest,omitempty"`
	Domain         string    `json:"domain,omitempty"`
	Filter         string    `json:"filter,omitempty"`
	GroupClasses   string    `json:"group_classes,omitempty"`
	GroupDN        string    `json:"group_dn,omitempty"`
	GroupFilter    string    `json:"group_filter,omitempty"`
	GroupName      string    `json:"group_name,omitempty"`
	IssuerURL      string    `json:"issuer-url,omitempty"`
	Mode           string    `json:"mode,omitempty"` // ldap, ldaps,ldap+starttls
	Password       string    `json:"password,omitempty"`
	Port           int       `json:"port,omitempty"`
	Prompt         string    `json:"prompt,omitempty"`
	Scopes         string    `json:"scopes,omitempty"`
	Secure         IntOrBool `json:"secure,omitempty"`
	Server1        string    `json:"server1,omitempty"`
	Server2        string    `json:"server2,omitempty"`
	SSLVersion     string    `json:"sslversion,omitempty"`
	SyncDefaults   string    `json:"sync-defaults,omitempty"`
	SyncAttributes string    `json:"sync_attributes,omitempty"`
	TFA            string    `json:"tfa,omitempty"`
	UserAttr       string    `json:"user_attr,omitempty"`
	UserClasses    string    `json:"user_classes,omitempty"`
	Verify         IntOrBool `json:"verify"`
	// contains filtered or unexported fields
}

func (*Domain) Delete 

func (d *Domain) Delete(ctx context.Context) error

func (*Domain) Sync 

func (d *Domain) Sync(ctx context.Context, options DomainSyncOptions) error

func (*Domain) Update 

func (d *Domain) Update(ctx context.Context) error

type DomainSyncOptions 

type DomainSyncOptions struct {
	DryRun IntOrBool `json:"dry-run,omitempty"`
	// EnableNew — PVE default 1 (newly synced users start enabled).
	// Unset on partial updates would disable freshly synced accounts. See
	// #178 + #199.
	EnableNew *IntOrBool `json:"enable-new,omitempty"`
	// RemoveVanished — PVE default "none". Empty/missing value preserves
	// "none"; pointer prevents an unset Go zero from being interpreted as
	// an override. See #199.
	RemoveVanished *string `json:"remove-vanished,omitempty"`
	Scope          string  `json:"scope,omitempty"` // users, groups, both
}

DomainSyncOptions see details https://pve.proxmox.com/pve-docs/api-viewer/#/access/domains/{realm}/sync

type DomainType 

type DomainType string

type Domains 

type Domains []*Domain

type Firewall 

type Firewall struct {
	Aliases []*FirewallAlias    `json:"aliases,omitempty"`
	Ipset   []*FirewallIPSet    `json:"ipset,omitempty"`
	Rules   []*FirewallRule     `json:"rules,omitempty"`
	Options *FirewallNodeOption `json:"options,omitempty"`
}

type FirewallAlias 

type FirewallAlias struct {
	Cidr    string `json:"cidr,omitempty"`
	Digest  string `json:"digest,omitempty"`
	Name    string `json:"name,omitempty"`
	Comment string `json:"comment,omitempty"`
}

type FirewallAliasCreateOption added in v0.7.0 

type FirewallAliasCreateOption struct {
	CIDR    string `json:"cidr"`
	Name    string `json:"name"`
	Comment string `json:"comment,omitempty"`
}

FirewallAliasCreateOption is the POST body for /cluster/firewall/aliases. CIDR and Name are both required by PVE.

type FirewallAliasUpdateOption added in v0.7.0 

type FirewallAliasUpdateOption struct {
	CIDR    string `json:"cidr,omitempty"`
	Comment string `json:"comment,omitempty"`
	Digest  string `json:"digest,omitempty"`
	Rename  string `json:"rename,omitempty"`
}

FirewallAliasUpdateOption is the PUT body for /cluster/firewall/aliases/{name}. Rename lets a caller change the alias name in place; same value as Name updates only the comment.

type FirewallClusterOption added in v0.7.0 

type FirewallClusterOption struct {
	Enable        int        `json:"enable,omitempty"`
	Ebtables      *IntOrBool `json:"ebtables,omitempty"`
	LogRatelimit  string     `json:"log_ratelimit,omitempty"`
	PolicyForward string     `json:"policy_forward,omitempty"`
	PolicyIn      string     `json:"policy_in,omitempty"`
	PolicyOut     string     `json:"policy_out,omitempty"`
}

Cluster-wide firewall option set. Distinct from FirewallNodeOption / FirewallVirtualMachineOption: this is the top of the three-gate model — if Enable is 0 here, neither node nor VM firewalls do anything regardless of their own settings. Note the schema asymmetry: `enable` is declared `type: integer` (default 0), while `ebtables` is `type: boolean` (default 1). Ebtables therefore needs *IntOrBool so an unset value stays off the wire and PVE keeps its default; silently shipping 0 would disable bridge-level filtering cluster-wide.

type FirewallClusterOptionUpdateOption added in v0.7.0 

type FirewallClusterOptionUpdateOption struct {
	Delete        string     `json:"delete,omitempty"`
	Digest        string     `json:"digest,omitempty"`
	Enable        int        `json:"enable,omitempty"`
	Ebtables      *IntOrBool `json:"ebtables,omitempty"`
	LogRatelimit  string     `json:"log_ratelimit,omitempty"`
	PolicyForward string     `json:"policy_forward,omitempty"`
	PolicyIn      string     `json:"policy_in,omitempty"`
	PolicyOut     string     `json:"policy_out,omitempty"`
}

FirewallClusterOptionUpdateOption mirrors FirewallClusterOption but adds the PUT-only `delete` selector for unsetting individual fields server-side.

type FirewallIPSet 

type FirewallIPSet struct {
	Name    string `json:"name,omitempty"`
	Digest  string `json:"digest,omitempty"`
	Comment string `json:"comment,omitempty"`
}

type FirewallIPSetCreationOption added in v0.2.3 

type FirewallIPSetCreationOption struct {
	Name    string `json:"name"`
	Digest  string `json:"digest,omitempty"`
	Comment string `json:"comment,omitempty"`
	Rename  string `json:"rename,omitempty"`
}

type FirewallIPSetEntry added in v0.2.3 

type FirewallIPSetEntry struct {
	CIDR    string `json:"cidr,omitempty"`
	Digest  string `json:"digest,omitempty"`
	Comment string `json:"comment,omitempty"`
	NoMatch bool   `json:"nomatch,omitempty"`
}

type FirewallIPSetEntryCreationOption added in v0.2.3 

type FirewallIPSetEntryCreationOption struct {
	CIDR    string `json:"cidr"`
	Comment string `json:"comment,omitempty"`
	NoMatch bool   `json:"nomatch,omitempty"`
}

type FirewallIPSetEntryUpdateOption added in v0.2.3 

type FirewallIPSetEntryUpdateOption struct {
	Comment string `json:"comment,omitempty"`
	Digest  string `json:"digest,omitempty"`
	NoMatch bool   `json:"nomatch,omitempty"`
}

type FirewallLogEntry added in v0.6.0 

type FirewallLogEntry struct {
	LineNum int    `json:"n"`
	Text    string `json:"t"`
}

FirewallLogEntry is one line from GET /firewall/log. PVE returns each entry as a [line-number, text] JSON tuple — the custom UnmarshalJSON below flattens that into named fields.

func (*FirewallLogEntry) UnmarshalJSON added in v0.6.0 

func (f *FirewallLogEntry) UnmarshalJSON(b []byte) error

type FirewallMacro added in v0.7.0 

type FirewallMacro struct {
	Macro string `json:"macro"`
	Descr string `json:"descr,omitempty"`
}

FirewallMacro is one entry from GET /cluster/firewall/macros — read-only.

type FirewallNodeOption 

type FirewallNodeOption struct {
	// Enable — PVE default 1 (node firewall on). Unset/zero on partial
	// updates silently disables an already-enabled node firewall. See
	// #178 + #199.
	Enable         *IntOrBool `json:"enable,omitempty"`
	LogLevelIn     string     `json:"log_level_in,omitempty"`
	LogLevelOut    string     `json:"log_level_out,omitempty"`
	LogNfConntrack IntOrBool  `json:"log_nf_conntrack,omitempty"`
	// NDP — Neighbor Discovery Protocol toggle (PVE default 1). Use this
	// field rather than Ntp; the upstream API field is `ndp`, not `ntp`.
	NDP IntOrBool `json:"ndp,omitempty"`
	// Deprecated: PVE never had an `ntp` firewall option — this was a typo
	// shipped since v0.1.x. The intended field is NDP (above). Setting Ntp
	// has no effect on PVE and reads always return zero. Will be removed in
	// v0.8.0.
	Ntp                     IntOrBool `json:"-"`
	NFConntrackAllowInvalid IntOrBool `json:"nf_conntrack_allow_invalid,omitempty"`
	// NFConntrackMax — PVE default 262144. Pointer so unset doesn't shrink
	// the conntrack table to 0. See #199.
	NFConntrackMax *int `json:"nf_conntrack_max,omitempty"`
	// NFConntrackTCPTimeoutEstablished — PVE default 432000 (seconds).
	// Pointer so unset doesn't drop established connections immediately. See #199.
	NFConntrackTCPTimeoutEstablished *int `json:"nf_conntrack_tcp_timeout_established,omitempty"`
	// NFConntrackTCPTimeoutSynRecv — PVE default 60 (seconds). Pointer so
	// unset doesn't override the SYN_RECV timeout. See #199.
	NFConntrackTCPTimeoutSynRecv *int      `json:"nf_conntrack_tcp_timeout_syn_recv,omitempty"`
	Nosmurfs                     IntOrBool `json:"nosmurfs,omitempty"`
	ProtectionSynflood           IntOrBool `json:"protection_synflood,omitempty"`
	// ProtectionSynfloodBurst — PVE default 1000. Pointer so unset doesn't
	// reduce the SYN-flood burst tolerance. See #199.
	ProtectionSynfloodBurst *int `json:"protection_synflood_burst,omitempty"`
	// ProtectionSynfloodRate — PVE default 200 (packets/sec). Pointer so
	// unset doesn't override the SYN-flood rate threshold. See #199.
	ProtectionSynfloodRate *int      `json:"protection_synflood_rate,omitempty"`
	SmurfLogLevel          string    `json:"smurf_log_level,omitempty"`
	TCPFlagsLogLevel       string    `json:"tcp_flags_log_level,omitempty"`
	TCPflags               IntOrBool `json:"tcpflags,omitempty"`
}

PVE's three-gate firewall design: cluster + node + VM. Node-level ships enabled by default (Enable=1) so flipping the cluster gate activates node rules; per-VM stays opt-in (FirewallVirtualMachineOption.Enable defaults to 0). The asymmetric defaults are intentional — see PVE wiki "Proxmox VE Firewall".

type FirewallRef added in v0.6.0 

type FirewallRef struct {
	Name    string `json:"name"`
	Ref     string `json:"ref,omitempty"`
	Scope   string `json:"scope,omitempty"`
	Type    string `json:"type"` // "alias" or "ipset"
	Comment string `json:"comment,omitempty"`
}

FirewallRef is one entry from GET /firewall/refs — a referencable IPSet or alias visible at this scope. Returned by both the cluster-level (/cluster/firewall/refs) and per-guest (/nodes/.../firewall/refs) endpoints; cluster responses also populate Ref and Scope.

type FirewallRule 

type FirewallRule struct {
	Type     string `json:"type,omitempty"`
	Action   string `json:"action,omitempty"`
	Pos      int    `json:"pos,omitempty"`
	Comment  string `json:"comment,omitempty"`
	Dest     string `json:"dest,omitempty"`
	Dport    string `json:"dport,omitempty"`
	Enable   int    `json:"enable,omitempty"`
	IcmpType string `json:"icmp-type,omitempty"`
	Iface    string `json:"iface,omitempty"`
	Log      string `json:"log,omitempty"`
	Macro    string `json:"macro,omitempty"`
	Proto    string `json:"proto,omitempty"`
	Source   string `json:"source,omitempty"`
	Sport    string `json:"sport,omitempty"`
	// contains filtered or unexported fields
}

func (*FirewallRule) Delete added in v0.7.0 

func (r *FirewallRule) Delete(ctx context.Context) error

Delete removes /firewall/rules/{pos} on the owning resource.

func (*FirewallRule) Get added in v0.7.0 

func (r *FirewallRule) Get(ctx context.Context) error

Get fetches /firewall/rules/{pos} for the owning resource and refreshes the receiver in place. Requires the rule to have been produced by a parent getter (Node.FirewallRule, VirtualMachine.FirewallRule, Container.FirewallRule).

func (*FirewallRule) IsEnable 

func (r *FirewallRule) IsEnable() bool

func (*FirewallRule) Update added in v0.7.0 

func (r *FirewallRule) Update(ctx context.Context) error

Update PUTs the receiver to /firewall/rules/{pos} on the owning resource.

type FirewallSecurityGroup 

type FirewallSecurityGroup struct {
	Group   string          `json:"group,omitempty"`
	Comment string          `json:"comment,omitempty"`
	Rules   []*FirewallRule `json:"rules,omitempty"`
	// contains filtered or unexported fields
}

func (*FirewallSecurityGroup) Delete 

func (g *FirewallSecurityGroup) Delete(ctx context.Context) error

func (*FirewallSecurityGroup) GetRule added in v0.7.0 

func (g *FirewallSecurityGroup) GetRule(ctx context.Context, pos int) (rule *FirewallRule, err error)

FWGroupRule returns a single firewall rule in this security group by position. Companion to (*FirewallSecurityGroup).RuleCreate / RuleUpdate / RuleDelete.

GET /cluster/firewall/groups/{group}/{pos}

func (*FirewallSecurityGroup) GetRules 

func (g *FirewallSecurityGroup) GetRules(ctx context.Context) ([]*FirewallRule, error)

func (*FirewallSecurityGroup) RuleCreate 

func (g *FirewallSecurityGroup) RuleCreate(ctx context.Context, rule *FirewallRule) error

func (*FirewallSecurityGroup) RuleDelete 

func (g *FirewallSecurityGroup) RuleDelete(ctx context.Context, rulePos int) error

func (*FirewallSecurityGroup) RuleUpdate 

func (g *FirewallSecurityGroup) RuleUpdate(ctx context.Context, rule *FirewallRule) error

type FirewallVirtualMachineOption 

type FirewallVirtualMachineOption struct {
	Enable      IntOrBool `json:"enable,omitempty"`
	Dhcp        IntOrBool `json:"dhcp,omitempty"`
	Ipfilter    IntOrBool `json:"ipfilter,omitempty"`
	LogLevelIn  string    `json:"log_level_in,omitempty"`
	LogLevelOut string    `json:"log_level_out,omitempty"`
	// Macfilter — PVE default 1 (MAC filtering on). Unset on partial
	// updates would disable a security feature that's enabled by default.
	// See #178 + #199.
	Macfilter *IntOrBool `json:"macfilter,omitempty"`
	// NDP — Neighbor Discovery Protocol toggle (PVE default 1). Use this
	// field rather than Ntp; the upstream API field is `ndp`, not `ntp`.
	NDP IntOrBool `json:"ndp,omitempty"`
	// Deprecated: PVE never had an `ntp` firewall option — this was a typo
	// shipped since v0.1.x. The intended field is NDP (above). Setting Ntp
	// has no effect on PVE and reads always return zero. Will be removed in
	// v0.8.0.
	Ntp       IntOrBool `json:"-"`
	PolicyIn  string    `json:"policy_in,omitempty"`
	PolicyOut string    `json:"policy_out,omitempty"`
	Radv      IntOrBool `json:"radv,omitempty"`
}

Per-VM firewall is opt-in (Enable defaults to 0) by design, in contrast to FirewallNodeOption which ships enabled. See the doc comment on FirewallNodeOption for the three-gate model.

type Group 

type Group struct {
	GroupID string   `json:"groupid,omitempty"`
	Comment string   `json:"comment,omitempty"`
	Users   string   `json:"users,omitempty"`   // only populated via Groups lister
	Members []string `json:"members,omitempty"` // only populated via Group read
	// contains filtered or unexported fields
}

func (*Group) Delete 

func (g *Group) Delete(ctx context.Context) error

func (*Group) Update 

func (g *Group) Update(ctx context.Context) error

type Groups 

type Groups []*Group

type HA 

type HA struct {
	Managed int
}

type HAGroup added in v0.7.0 

type HAGroup struct {
	Group      string    `json:"group"`
	Type       string    `json:"type,omitempty"`
	Nodes      string    `json:"nodes,omitempty"`
	Comment    string    `json:"comment,omitempty"`
	Digest     string    `json:"digest,omitempty"`
	NoFailback IntOrBool `json:"nofailback,omitempty"`
	Restricted IntOrBool `json:"restricted,omitempty"`
}

HAGroup is a node-affinity group resources can be bound to. Deprecated by PVE in favor of HA rules but still functional; existing clusters use these heavily, so the wrapper stays for compatibility.

type HAGroupCreateOption added in v0.7.0 

type HAGroupCreateOption struct {
	Group      string    `json:"group"`
	Nodes      string    `json:"nodes"`
	Type       string    `json:"type,omitempty"`
	Comment    string    `json:"comment,omitempty"`
	NoFailback IntOrBool `json:"nofailback,omitempty"`
	Restricted IntOrBool `json:"restricted,omitempty"`
}

type HAGroupUpdateOption added in v0.7.0 

type HAGroupUpdateOption struct {
	Delete     string    `json:"delete,omitempty"`
	Digest     string    `json:"digest,omitempty"`
	Comment    string    `json:"comment,omitempty"`
	Nodes      string    `json:"nodes,omitempty"`
	NoFailback IntOrBool `json:"nofailback,omitempty"`
	Restricted IntOrBool `json:"restricted,omitempty"`
}

type HAManagerStatus added in v0.7.0 

type HAManagerStatus struct {
	ManagerStatus map[string]any            `json:"manager_status,omitempty"`
	NodeStatus    map[string]string         `json:"node_status,omitempty"`
	ServiceStatus map[string]map[string]any `json:"service_status,omitempty"`
	Quorum        map[string]any            `json:"quorum,omitempty"`
}

HAManagerStatus mirrors the JSON shape of GET /cluster/ha/status/manager_status — the master process state plus LRM details. Fields are loosely typed because PVE's manager_status is a JSON blob that evolves between releases.

type HAResource added in v0.7.0 

type HAResource struct {
	SID         string     `json:"sid"`
	Type        string     `json:"type,omitempty"`
	Group       string     `json:"group,omitempty"`
	Comment     string     `json:"comment,omitempty"`
	Digest      string     `json:"digest,omitempty"`
	State       *string    `json:"state,omitempty"`
	Failback    *IntOrBool `json:"failback,omitempty"`
	MaxRelocate *int       `json:"max_relocate,omitempty"`
	MaxRestart  *int       `json:"max_restart,omitempty"`
}

HAResource is a managed HA-controlled guest (VM or container). Failback / MaxRelocate / MaxRestart use pointer types: PVE defaults are 1 for all three, so unset → omitted → server applies its default; an explicit Ptr(IntOrBool(false)) / Ptr(0) reaches the wire as 0 (the "disable failback" / "no relocations" cases users actually want). State defaults to "started" — pointer for the same reason.

type HAResourceCreateOption added in v0.7.0 

type HAResourceCreateOption struct {
	SID         string     `json:"sid"`
	Type        string     `json:"type,omitempty"`
	Group       string     `json:"group,omitempty"`
	Comment     string     `json:"comment,omitempty"`
	State       *string    `json:"state,omitempty"`
	Failback    *IntOrBool `json:"failback,omitempty"`
	MaxRelocate *int       `json:"max_relocate,omitempty"`
	MaxRestart  *int       `json:"max_restart,omitempty"`
}

HAResourceCreateOption mirrors HAResource for POST; State/Failback/ MaxRelocate/MaxRestart use pointers for the same reason — see HAResource.

type HAResourceUpdateOption added in v0.7.0 

type HAResourceUpdateOption struct {
	Delete      string     `json:"delete,omitempty"`
	Digest      string     `json:"digest,omitempty"`
	Group       string     `json:"group,omitempty"`
	Comment     string     `json:"comment,omitempty"`
	State       *string    `json:"state,omitempty"`
	Failback    *IntOrBool `json:"failback,omitempty"`
	MaxRelocate *int       `json:"max_relocate,omitempty"`
	MaxRestart  *int       `json:"max_restart,omitempty"`
}

HAResourceUpdateOption mirrors HAResource for PUT; pointer fields per HAResource. The PUT-only Delete selector unsets fields server-side.

type HARule added in v0.7.0 

type HARule struct {
	Rule      string    `json:"rule"`
	Type      string    `json:"type,omitempty"`
	Affinity  string    `json:"affinity,omitempty"`
	Comment   string    `json:"comment,omitempty"`
	Digest    string    `json:"digest,omitempty"`
	Nodes     string    `json:"nodes,omitempty"`
	Resources string    `json:"resources,omitempty"`
	Disable   IntOrBool `json:"disable,omitempty"`
	Strict    IntOrBool `json:"strict,omitempty"`
}

HARule is the modern HA configuration unit (replaces groups). Type and Affinity together describe whether resources should colocate, anti-colocate, or pin to specific nodes. Strict (default 0) and Disable (no default in schema) are both schema-boolean; plain IntOrBool is fine because the "unset" semantic matches the Go zero for both.

type HARuleCreateOption added in v0.7.0 

type HARuleCreateOption struct {
	Rule      string    `json:"rule"`
	Type      string    `json:"type"`
	Resources string    `json:"resources"`
	Affinity  string    `json:"affinity,omitempty"`
	Comment   string    `json:"comment,omitempty"`
	Nodes     string    `json:"nodes,omitempty"`
	Disable   IntOrBool `json:"disable,omitempty"`
	Strict    IntOrBool `json:"strict,omitempty"`
}

type HARuleUpdateOption added in v0.7.0 

type HARuleUpdateOption struct {
	Delete    string    `json:"delete,omitempty"`
	Digest    string    `json:"digest,omitempty"`
	Type      string    `json:"type,omitempty"`
	Affinity  string    `json:"affinity,omitempty"`
	Comment   string    `json:"comment,omitempty"`
	Nodes     string    `json:"nodes,omitempty"`
	Resources string    `json:"resources,omitempty"`
	Disable   IntOrBool `json:"disable,omitempty"`
	Strict    IntOrBool `json:"strict,omitempty"`
}

type HAStatusEntry added in v0.7.0 

type HAStatusEntry struct {
	ID           string `json:"id"`
	Type         string `json:"type"`
	Status       string `json:"status,omitempty"`
	Node         string `json:"node,omitempty"`
	Quorate      int    `json:"quorate,omitempty"`
	CRMState     string `json:"crm_state,omitempty"`
	LRMState     string `json:"lrm_state,omitempty"`
	Service      string `json:"service,omitempty"`
	ServiceState string `json:"state,omitempty"`
	Request      string `json:"request_state,omitempty"`
	Comment      string `json:"comment,omitempty"`
	Timestamp    int64  `json:"timestamp,omitempty"`
}

HAStatusEntry is one row from GET /cluster/ha/status/current. The schema is loose because PVE mixes per-resource, per-node, and overall-manager rows in the same list — fields are populated based on the row's `type`.

type HardwarePCIOptions added in v0.6.0 

type HardwarePCIOptions struct {
	ClassBlacklist []string
	Terse          bool
}

HardwarePCIOptions is the query payload for ListPCIDevices. ClassBlacklist is a list of PCI class hex codes to filter out (default server-side: "05;06;0b" — memory, bridge, processor). Verbose unset means the verbose default (1) — set Terse=true to get only PCI IDs.

type IPAM added in v0.2.3 

type IPAM struct {
	Hostname string `json:"hostname,omitempty"`
	IP       string `json:"ip,omitempty"`
	Mac      string `json:"mac,omitempty"`
	Subnet   string `json:"subnet,omitempty"`
	VMID     string `json:"vmid,omitempty"`
	VNet     string `json:"vnet,omitempty"`
	Zone     string `json:"zone,omitempty"`
	Gateway  int    `json:"gateway,omitempty"`
}

type ISO 

type ISO struct{ Content }

func (*ISO) Delete 

func (i *ISO) Delete(ctx context.Context) (*Task, error)

type ISOs 

type ISOs []*ISO

type Import added in v0.3.2 

type Import struct{ Content }

type ImportMetadata added in v0.6.0 

type ImportMetadata struct {
	Type       string                  `json:"type"`
	Source     string                  `json:"source"`
	CreateArgs map[string]interface{}  `json:"create-args"`
	Disks      map[string]string       `json:"disks,omitempty"`
	Net        map[string]interface{}  `json:"net,omitempty"`
	Warnings   []ImportMetadataWarning `json:"warnings,omitempty"`
}

ImportMetadata is the result of Storage.ImportMetadata for an external disk volume on an "import"-capable storage (e.g. an ESXi-imported guest). It describes how Proxmox interprets the source and supplies ready-to-use arguments for creating a guest from it.

type ImportMetadataWarning added in v0.6.0 

type ImportMetadataWarning struct {
	Type  string `json:"type"`
	Key   string `json:"key,omitempty"`
	Value string `json:"value,omitempty"`
}

type Imports added in v0.3.2 

type Imports []*Import

type IntOrBool 

type IntOrBool bool

func (*IntOrBool) MarshalJSON 

func (b *IntOrBool) MarshalJSON() ([]byte, error)

func (*IntOrBool) UnmarshalJSON 

func (b *IntOrBool) UnmarshalJSON(i []byte) error

type IsTemplate 

type IsTemplate bool

func (*IsTemplate) UnmarshalJSON 

func (it *IsTemplate) UnmarshalJSON(b []byte) error

type Ksm 

type Ksm struct {
	Shared int64
}

type LeveledLogger 

type LeveledLogger struct {
	// Level is the minimum logging level that will be emitted by this logger.
	//
	// For example, a Level set to LevelWarn will emit warnings and errors, but
	// not informational or debug messages.
	//
	// Always set this with a constant like LevelWarn because the individual
	// values are not guaranteed to be stable.
	Level int
	// contains filtered or unexported fields
}

func (*LeveledLogger) Debugf 

func (l *LeveledLogger) Debugf(format string, v ...interface{})

Debugf logs a debug message using Printf conventions.

func (*LeveledLogger) Errorf 

func (l *LeveledLogger) Errorf(format string, v ...interface{})

Errorf logs a warning message using Printf conventions.

func (*LeveledLogger) Infof 

func (l *LeveledLogger) Infof(format string, v ...interface{})

Infof logs an informational message using Printf conventions.

func (*LeveledLogger) Warnf 

func (l *LeveledLogger) Warnf(format string, v ...interface{})

Warnf logs a warning message using Printf conventions.

type LeveledLoggerInterface 

type LeveledLoggerInterface interface {
	Debugf(format string, v ...interface{})
	Errorf(format string, v ...interface{})
	Infof(format string, v ...interface{})
	Warnf(format string, v ...interface{})
}

type Log 

type Log map[int]string

func (*Log) UnmarshalJSON 

func (l *Log) UnmarshalJSON(b []byte) error

line numbers in the response start a 1 but the start param indexes from 0 so converting to that

type LogEntry added in v0.6.0 

type LogEntry struct {
	N int    `json:"n"`
	T string `json:"t"`
}

LogEntry is a single line from PVE log endpoints (task log, replication log, etc.) — N is the 1-based line number, T the line text.

type Memory 

type Memory struct {
	Used  uint64
	Free  uint64
	Total uint64
}

type MetricsExportEntry added in v0.7.0 

type MetricsExportEntry struct {
	ID        string  `json:"id"`        // e.g. "node/node1", "qemu/100"
	Metric    string  `json:"metric"`    // metric name
	Timestamp int64   `json:"timestamp"` // unix seconds
	Type      string  `json:"type"`      // "gauge" | "counter" | "derive"
	Value     float64 `json:"value"`
}

MetricsExportEntry is one observation in the export series.

type MetricsExportOptions added in v0.7.0 

type MetricsExportOptions struct {
	// History returns the full historic series instead of just the latest
	// observation. PVE default false; matches Go zero, so plain bool is safe.
	History bool
	// LocalOnly restricts the output to the current node instead of the whole
	// cluster. PVE default false; matches Go zero.
	LocalOnly bool
	// StartTime: only include metrics with timestamp > start-time (unix
	// seconds). 0 disables the filter.
	StartTime int64
	// NodeList: comma-separated node names to scope the export to. Empty =
	// all nodes (or local-only when LocalOnly is true).
	NodeList string
}

MetricsExportOptions filters the /cluster/metrics/export response.

type MetricsExportResponse added in v0.7.0 

type MetricsExportResponse struct {
	Data []*MetricsExportEntry `json:"data,omitempty"`
}

MetricsExportResponse is the response of GET /cluster/metrics/export.

type NetRange added in v0.2.3 

type NetRange struct {
	StartAddress string `json:"start-address,omitempty"`
	EndAddress   string `json:"end-address,omitempty"`
}

type NewAPIToken 

type NewAPIToken struct {
	FullTokenID string      `json:"full-tokenid,omitempty"`
	Info        interface{} `json:"info,omitempty"`
	Value       string      `json:"value,omitempty"`
}

type NewUser 

type NewUser struct {
	UserID    string   `json:"userid"`
	Comment   string   `json:"comment,omitempty"`
	Email     string   `json:"email,omitempty"`
	Enable    bool     `json:"enable"`
	Expire    int      `json:"expire,omitempty"`
	Firstname string   `json:"firstname,omitempty"`
	Groups    CSV      `json:"groups,omitempty"`
	Keys      []string `json:"keys,omitempty"`
	Lastname  string   `json:"lastname,omitempty"`
	Password  string   `json:"password,omitempty"`
}

type Node 

type Node struct {
	Name string

	Kversion   string
	LoadAvg    []string
	CPU        float64
	RootFS     RootFS
	PVEVersion string
	CPUInfo    CPUInfo
	Swap       Memory
	Idle       int
	Memory     Memory
	Ksm        Ksm
	Uptime     uint64
	Wait       float64
	// contains filtered or unexported fields
}

func (*Node) APT added in v0.6.0 

func (n *Node) APT(ctx context.Context) (entries []*APTIndexEntry, err error)

APT returns the directory index for /nodes/{node}/apt — a small list of child handles (changelog, repositories, update, versions). Mostly useful as a probe; the real data lives on the children.

func (*Node) APTAddRepository added in v0.6.0 

func (n *Node) APTAddRepository(ctx context.Context, handle, digest string) error

APTAddRepository adds one of PVE's standard repositories (identified by handle, e.g. "no-subscription", "enterprise") to the node's apt configuration. digest is optional for optimistic concurrency.

func (*Node) APTChangeRepository added in v0.6.0 

func (n *Node) APTChangeRepository(ctx context.Context, path string, index int, enabled bool, digest string) error

APTChangeRepository enables or disables an existing repository entry, identified by the containing file path and its index within that file. digest is optional; pass the value from APTRepositories to detect concurrent edits.

func (*Node) APTChangelog added in v0.6.0 

func (n *Node) APTChangelog(ctx context.Context, name, version string) (changelog string, err error)

APTChangelog returns the changelog text for a single package. version is optional — when empty PVE picks the candidate version. The endpoint returns a single string, not structured data.

func (*Node) APTRepositories added in v0.6.0 

func (n *Node) APTRepositories(ctx context.Context) (repos *APTRepositories, err error)

APTRepositories returns the parsed contents of /etc/apt/sources.list(.d) on the node, plus a digest used for optimistic-concurrency on writes and a catalog of standard repositories PVE knows how to add.

func (*Node) APTUpdate added in v0.6.0 

func (n *Node) APTUpdate(ctx context.Context, notify, quiet bool) (*Task, error)

APTUpdate resynchronizes the apt package index (apt-get update) on the node. notify=true asks PVE to send its configured "new packages available" notification; quiet=true suppresses progress output in the task log. Returns the worker task.

func (*Node) APTUpdates added in v0.6.0 

func (n *Node) APTUpdates(ctx context.Context) (updates []*APTUpdate, err error)

APTUpdates lists the packages with available upgrades on the node, as produced by the last `apt-get update`. Empty list means the index is clean or has never been refreshed; call APTUpdate to resync first.

func (*Node) APTVersions added in v0.6.0 

func (n *Node) APTVersions(ctx context.Context) (versions []*APTPackageVersion, err error)

APTVersions returns the installed versions of the Proxmox-relevant packages (pve-manager, kernel, qemu-server, etc.) — the same data shown on the GUI "Updates → Package Versions" panel.

func (*Node) Appliances 

func (n *Node) Appliances(ctx context.Context) (appliances Appliances, err error)

func (*Node) CapabilitiesIndex added in v0.6.0 

func (n *Node) CapabilitiesIndex(ctx context.Context) ([]string, error)

CapabilitiesIndex enumerates the top-level capability subsystems ("qemu").

func (*Node) CephCfg added in v0.6.0 

func (n *Node) CephCfg(ctx context.Context) (entries []map[string]interface{}, err error)

CephCfg returns the directory index for /nodes/{node}/ceph/cfg. PVE exposes no useful payload on the index itself; the real data lives on the child endpoints (db, raw, value).

func (*Node) CephCfgDB added in v0.6.0 

func (n *Node) CephCfgDB(ctx context.Context) (entries []*CephCfgDBEntry, err error)

CephCfgDB returns the Ceph mon config database — every key/value the cluster has stored in the centralised KV config, scoped by section and optional mask.

func (*Node) CephCfgRaw added in v0.6.0 

func (n *Node) CephCfgRaw(ctx context.Context) (raw string, err error)

CephCfgRaw returns the raw text contents of /etc/pve/ceph.conf as a single string — exactly what the on-disk file looks like.

func (*Node) CephCfgValue added in v0.6.0 

func (n *Node) CephCfgValue(ctx context.Context, configKeys string) (values CephCfgValue, err error)

CephCfgValue resolves specific config values from either ceph.conf or the mon config DB. configKeys is a string of `<section>:<key>` items separated by `;`, `,`, or space (e.g. "global:auth_cluster_required;osd:osd_pool_default_size"). PVE normalises underscores in section and key names to hyphens in the response, so callers should not key off the requested spelling.

func (*Node) CephCmdSafety added in v0.6.0 

func (n *Node) CephCmdSafety(ctx context.Context, service, id, action string) (safety *CephCmdSafety, err error)

CephCmdSafety asks Ceph whether a planned mutation is safe right now — e.g. stopping an OSD without losing data redundancy. service must be one of "osd"|"mon"|"mds", action must be "stop"|"destroy", id is the service-specific identifier (numeric for osd, name for mon/mds).

func (*Node) CephCrush added in v0.6.0 

func (n *Node) CephCrush(ctx context.Context) (crush string, err error)

CephCrush returns the OSD CRUSH map as a textual dump (the format produced by `ceph osd crush dump`). PVE returns it as a single string blob.

func (*Node) CephFS added in v0.6.0 

func (n *Node) CephFS(name string) *CephFS

CephFS returns an operations handle for the CephFS filesystem with the given name. No API call is made.

func (*Node) CephFSs added in v0.6.0 

func (n *Node) CephFSs(ctx context.Context) (fss []*CephFS, err error)

CephFSs lists the CephFS filesystems known to the cluster, as seen by this node. Each entry carries the metadata pool and one or more data pools, with `client` + `Node` populated for chaining.

func (*Node) CephIndex added in v0.6.0 

func (n *Node) CephIndex(ctx context.Context) (entries []*CephIndexEntry, err error)

CephIndex returns the /nodes/{node}/ceph directory index — a flat list of child handles (osd, mon, mgr, pool, fs, status, log, …). Mostly a probe; the actual resources are wrapped by sibling methods on *Node.

func (*Node) CephLog added in v0.6.0 

func (n *Node) CephLog(ctx context.Context, start, limit int) (entries []*CephLogEntry, err error)

CephLog reads the ceph cluster log. start is the 0-based offset of the first line to return; pass 0 for the head of the log. limit caps the number of lines (0 = PVE's default, typically 50).

func (*Node) CephMDS added in v0.6.0 

func (n *Node) CephMDS(name string) *CephMDS

CephMDS returns an operations handle for the metadata server with the given name. No API call is made.

func (*Node) CephMDSs added in v0.6.0 

func (n *Node) CephMDSs(ctx context.Context) (mdss []*CephMDS, err error)

CephMDSs lists the CephFS metadata-server daemons PVE knows about on this node. Includes both active/standby MDSes visible to the cluster and configured daemons that are currently stopped/unknown. Each returned entry has `client` + `Node` populated for chaining.

func (*Node) CephMgr added in v0.6.0 

func (n *Node) CephMgr(id string) *CephMgr

CephMgr returns an operations handle for the manager with the given id. No API call is made.

func (*Node) CephMgrs added in v0.6.0 

func (n *Node) CephMgrs(ctx context.Context) (mgrs []*CephMgr, err error)

CephMgrs lists the Ceph manager daemons PVE knows about on this node. Each returned entry has `client` + `Node` populated for chaining.

func (*Node) CephMon added in v0.6.0 

func (n *Node) CephMon(monid string) *CephMon

CephMon returns an operations handle for the monitor with the given monid. No API call is made.

func (*Node) CephMons added in v0.6.0 

func (n *Node) CephMons(ctx context.Context) (mons []*CephMon, err error)

CephMons lists the Ceph monitor daemons PVE knows about on this node. Includes both running monitors visible to the cluster and configured daemons that are currently stopped/unknown. Each returned entry has `client` + `Node` populated so callers can chain `.Delete()` directly.

func (*Node) CephOSD added in v0.6.0 

func (n *Node) CephOSD(osdID int) *CephOSD

CephOSD returns an operations handle for the OSD with the given id. No API call is made — the handle holds Node + id and dispatches when methods are invoked.

func (*Node) CephOSDs added in v0.6.0 

func (n *Node) CephOSDs(ctx context.Context) (tree *CephOSDTree, err error)

CephOSDs returns the cluster CRUSH tree plus any cluster-wide OSD flags from GET /nodes/{node}/ceph/osd. The CRUSH bucket hierarchy is recursive and per-bucket properties are not statically typed.

func (*Node) CephPool added in v0.6.0 

func (n *Node) CephPool(name string) *CephPool

CephPool returns an operations handle for the pool with the given name. No API call is made — the handle holds Node + name and dispatches when methods are invoked.

func (*Node) CephPools added in v0.6.0 

func (n *Node) CephPools(ctx context.Context) (pools []*CephPool, err error)

CephPools lists every Ceph pool visible to the node with the same settings exposed by the per-pool PUT endpoint plus a few read-only stats. Each entry is returned with `client` + `Node` populated so callers can chain methods.

func (*Node) CephRules added in v0.6.0 

func (n *Node) CephRules(ctx context.Context) (rules []*CephRule, err error)

CephRules lists the configured CRUSH rules (one entry per rule, name only — the body of each rule lives in the CRUSH map dumped by CephCrush).

func (*Node) CephStatus added in v0.6.0 

func (n *Node) CephStatus(ctx context.Context) (status *ClusterCephStatus, err error)

CephStatus returns the raw `ceph status` output (mon/mgr/osd/pg maps, health checks, quorum). Cluster-wide — identical payload to Cluster.Ceph().Status; this node-level alias just runs the ceph CLI on the requested node.

func (*Node) Container 

func (n *Node) Container(ctx context.Context, vmid int) (*Container, error)

func (*Node) Containers 

func (n *Node) Containers(ctx context.Context) (c Containers, err error)

func (*Node) CreateCephFS added in v0.6.0 

func (n *Node) CreateCephFS(ctx context.Context, name string, opts *CephFSOptions) (*Task, error)

CreateCephFS creates a new CephFS filesystem with the given name. opts is optional; PVE defaults PgNum to 128 and AddStorage to false. The endpoint runs as a worker task — returns the Task so the caller can wait on it.

func (*Node) CreateCephMDS added in v0.6.0 

func (n *Node) CreateCephMDS(ctx context.Context, name string, opts *CephMDSOptions) (*Task, error)

CreateCephMDS creates a CephFS metadata server on this node with the given name. Pass an empty name to default to the nodename. Set opts.HotStandby to spin the daemon up as a standby-replay MDS that polls and replays the log of an active MDS for faster failover.

func (*Node) CreateCephMgr added in v0.6.0 

func (n *Node) CreateCephMgr(ctx context.Context, id string) (*Task, error)

CreateCephMgr creates a Ceph manager on this node with the given id. Pass an empty id to default to the nodename.

func (*Node) CreateCephMon added in v0.6.0 

func (n *Node) CreateCephMon(ctx context.Context, monid string, opts *CephMonOptions) (*Task, error)

CreateCephMon creates a Ceph monitor on this node with the given monid. Pass an empty monid to default to the nodename. Also auto-creates a manager for the first monitor in the cluster.

func (*Node) CreateCephOSD added in v0.6.0 

func (n *Node) CreateCephOSD(ctx context.Context, opts *CephOSDCreateOptions) (*Task, error)

CreateCephOSD provisions a new OSD on a block device. opts.Dev is required. Returns a Task — PVE runs the ceph-volume / mkfs work via the task queue.

func (*Node) CreateCephPool added in v0.6.0 

func (n *Node) CreateCephPool(ctx context.Context, opts *CephPoolOptions) (*Task, error)

CreateCephPool creates a Ceph pool. opts.Name is required. For erasure-coded pools pass opts.ErasureCoding (k/m required, the rest optional); PVE will additionally create a replicated metadata pool. Returns a Task.

func (*Node) DNS added in v0.6.0 

func (n *Node) DNS(ctx context.Context) (*NodeDNS, error)

DNS returns the resolver configuration for this node — what gets written to /etc/resolv.conf. Any of search/dns1/dns2/dns3 may be empty if the node has no value set for that slot.

func (*Node) DeleteCustomCertificate 

func (n *Node) DeleteCustomCertificate(ctx context.Context) error

func (*Node) DeleteDirectory added in v0.6.0 

func (n *Node) DeleteDirectory(ctx context.Context, name string, cleanupConfig, cleanupDisks bool) (*Task, error)

DeleteDirectory tears down a directory-mount storage. cleanupConfig also removes the storage.cfg entry; cleanupDisks wipes the underlying disk so it can be repurposed.

func (*Node) DeleteLVM added in v0.6.0 

func (n *Node) DeleteLVM(ctx context.Context, name string, cleanupConfig, cleanupDisks bool) (*Task, error)

DeleteLVM removes an LVM volume group. See DeleteDirectory for cleanup semantics.

func (*Node) DeleteLVMThin added in v0.6.0 

func (n *Node) DeleteLVMThin(ctx context.Context, name, volumeGroup string, cleanupConfig, cleanupDisks bool) (*Task, error)

DeleteLVMThin removes an LVM-thin pool. Unlike directory / LVM / ZFS, this endpoint *requires* the parent volume-group name to disambiguate when a node has multiple VGs containing thin pools by the same name.

func (*Node) DeleteSubscription added in v0.6.0 

func (n *Node) DeleteSubscription(ctx context.Context) error

DeleteSubscription removes the subscription key from the node, returning it to community-edition status. DELETE /nodes/{node}/subscription.

func (*Node) DeleteZFSPool added in v0.6.0 

func (n *Node) DeleteZFSPool(ctx context.Context, name string, cleanupConfig, cleanupDisks bool) (*Task, error)

DeleteZFSPool destroys a ZFS pool. cleanupConfig/cleanupDisks semantics match DeleteDirectory.

func (*Node) Directories added in v0.6.0 

func (n *Node) Directories(ctx context.Context) (dirs []*NodeDirectory, err error)

Directories lists per-node directory-mount storages backed by raw devices.

func (*Node) DiskInitGPT added in v0.6.0 

func (n *Node) DiskInitGPT(ctx context.Context, disk, uuid string) (*Task, error)

DiskInitGPT writes a fresh GPT partition table to disk. uuid is optional; pass "" to let the kernel assign one. Returns a Task.

func (*Node) DiskSMART added in v0.6.0 

func (n *Node) DiskSMART(ctx context.Context, disk string, healthOnly bool) (smart *DiskSMART, err error)

DiskSMART returns SMART data for one disk. Pass healthOnly=true for just the "PASS"/"FAIL" string (faster — skips the full attribute dump).

func (*Node) DiskWipe added in v0.6.0 

func (n *Node) DiskWipe(ctx context.Context, disk string) (*Task, error)

DiskWipe zeroes the first and last megabytes of disk and clears the partition table — destructive. Returns a Task.

func (*Node) Disks added in v0.6.0 

func (n *Node) Disks(ctx context.Context, includePartitions, skipSMART bool, diskType string) (disks []*Disk, err error)

Disks lists every block device PVE sees on the node. Pass includePartitions to also surface partition entries, skipSMART to avoid the per-disk SMART probe, and diskType ("unused"|"journal_disks"|"") to filter.

func (*Node) DisksSubdirs added in v0.7.0 

func (n *Node) DisksSubdirs(ctx context.Context) ([]string, error)

DisksSubdirs enumerates the children of /nodes/{node}/disks ("list", "smart", "initgpt", "wipedisk", "directory", "lvm", "lvmthin", "zfs").

func (*Node) DownloadAppliance 

func (n *Node) DownloadAppliance(ctx context.Context, template, storage string) (ret string, err error)

func (*Node) Execute added in v0.6.0 

func (n *Node) Execute(ctx context.Context, commands []*NodeExecuteCommand) (results []map[string]any, err error)

Execute runs a batch of API calls in order. Root-only on PVE. Returns the responses in submission order — each entry is the same envelope PVE would return from the single endpoint.

func (*Node) FirewallGetRule added in v0.6.0 

func (n *Node) FirewallGetRule(ctx context.Context, rulePos int) (rule *FirewallRule, err error)

FirewallGetRule fetches one rule by position. Companion to FirewallGetRules, mirroring the per-rule getter on Container/VirtualMachine.

func (*Node) FirewallLog added in v0.6.0 

func (n *Node) FirewallLog(ctx context.Context, opts *NodeFirewallLogOptions) (entries []*LogEntry, err error)

FirewallLog returns the host firewall's iptables/nftables log entries. Each LogEntry is {n: line-number, t: text}.

func (*Node) FirewallOptionGet 

func (n *Node) FirewallOptionGet(ctx context.Context) (firewallOption *FirewallNodeOption, err error)

func (*Node) FirewallOptionSet 

func (n *Node) FirewallOptionSet(ctx context.Context, firewallOption *FirewallNodeOption) error

func (*Node) FirewallRule added in v0.7.0 

func (n *Node) FirewallRule(pos int) *FirewallRule

FirewallRule returns a *FirewallRule wired to the node's firewall scope at the given position. The returned instance is a lazy handle — call Get(ctx) to populate it from /firewall/rules/{pos}.

func (*Node) FirewallRules added in v0.7.0 

func (n *Node) FirewallRules(ctx context.Context) (rules []*FirewallRule, err error)

FirewallRules lists firewall rules for the node. Returned rules carry the parent context required to call (*FirewallRule).Get/Update/Delete.

func (*Node) FirewallSubdirs added in v0.7.0 

func (n *Node) FirewallSubdirs(ctx context.Context) ([]string, error)

FirewallSubdirs enumerates the children of /nodes/{node}/firewall ("rules", "options", "log").

func (*Node) GetConfig added in v0.6.0 

func (n *Node) GetConfig(ctx context.Context) (cfg *NodeConfig, err error)

GetConfig returns node-level config (acme/acmedomain[0-5], description, location, ballooning-target, startall-onboot-delay, wakeonlan, digest). PVE encodes substructures (acme, location, wakeonlan) as property strings.

func (*Node) GetConfigProperty added in v0.6.0 

func (n *Node) GetConfigProperty(ctx context.Context, property string) (cfg *NodeConfig, err error)

GetConfigProperty fetches just one property from the node config ("acme"|"acmedomain0..5"|"ballooning-target"|"description"|"location" |"startall-onboot-delay"|"wakeonlan"). The returned config has only that field populated; others are zero-valued.

func (*Node) GetCustomCertificates 

func (n *Node) GetCustomCertificates(ctx context.Context) (certs *NodeCertificates, err error)

func (*Node) HardwareIndex added in v0.6.0 

func (n *Node) HardwareIndex(ctx context.Context) ([]string, error)

HardwareIndex enumerates the hardware subtypes ("pci", "usb").

func (*Node) Hosts added in v0.6.0 

func (n *Node) Hosts(ctx context.Context) (hosts *NodeHosts, err error)

Hosts returns the full contents of /etc/hosts plus a digest for optimistic concurrency. Pass the digest back to UpdateHosts to refuse the write on concurrent modification.

func (*Node) IPAM added in v0.2.3 

func (n *Node) IPAM(ctx context.Context) (ipam []*IPAM, err error)

func (*Node) InitCeph added in v0.6.0 

func (n *Node) InitCeph(ctx context.Context, opts *CephInitOptions) (*Task, error)

InitCeph performs the one-time Ceph bootstrap on the node — writes /etc/ceph/ceph.conf with the cluster fsid, default pool sizing, and auth/network settings. Idempotent: re-calling with an existing [global] section preserves the original values and silently ignores most params. Pass a nil *opts to accept all PVE defaults.

func (*Node) Journal added in v0.6.0 

func (n *Node) Journal(ctx context.Context, opts *NodeJournalOptions) (lines []string, err error)

Journal returns systemd journal lines as plain strings. PVE caps line count server-side; use LastEntries or a Since/Until range to bound output.

func (*Node) LVMThins added in v0.6.0 

func (n *Node) LVMThins(ctx context.Context) (thins []*NodeLVMThin, err error)

LVMThins lists LVM-thin pools.

func (*Node) LVMs added in v0.6.0 

func (n *Node) LVMs(ctx context.Context) (lvm *NodeLVMTree, err error)

LVMs returns the nested LVM tree (volume groups → physical volumes).

func (*Node) ListACMECertificateSubresources added in v0.6.0 

func (n *Node) ListACMECertificateSubresources(ctx context.Context) ([]string, error)

ListACMECertificateSubresources enumerates the children of /nodes/{node}/certificates/acme (typically just "certificate").

func (*Node) ListCertificateSubresources added in v0.6.0 

func (n *Node) ListCertificateSubresources(ctx context.Context) ([]string, error)

ListCertificateSubresources enumerates the children of /nodes/{node}/certificates (typically "info", "custom", "acme"). The PVE schema only documents this as a directory index, so we collapse the {"name": ...} link objects into a flat []string.

func (*Node) ListPCIDevices added in v0.6.0 

func (n *Node) ListPCIDevices(ctx context.Context, opts *HardwarePCIOptions) (devices []*PCIDevice, err error)

ListPCIDevices returns the PCI devices on this node. Returned *PCIDevice handles are pre-populated with client/Node so callers can chain Index()/Mdev() directly.

func (*Node) ListUSBDevices added in v0.6.0 

func (n *Node) ListUSBDevices(ctx context.Context) (devices []*USBDevice, err error)

ListUSBDevices returns the USB devices on this node.

func (*Node) MigrateAll added in v0.6.0 

func (n *Node) MigrateAll(ctx context.Context, opts *NodeMigrateAllOptions) (*Task, error)

MigrateAll migrates every VM and container on the node to opts.Target. Target is required.

func (*Node) Netstat added in v0.6.0 

func (n *Node) Netstat(ctx context.Context) (entries []map[string]any, err error)

Netstat returns per-VM/CT tap interface counters. PVE leaves the response shape loose — wrap each entry as a generic map.

func (*Node) Network 

func (n *Node) Network(ctx context.Context, iface string) (network *NodeNetwork, err error)

func (*Node) NetworkReload 

func (n *Node) NetworkReload(ctx context.Context) (*Task, error)

func (*Node) Networks 

func (n *Node) Networks(ctx context.Context, ifaceType ...string) (networks NodeNetworks, err error)

func (*Node) New added in v0.3.0 

func (n *Node) New(c *Client, name string) *Node

func (*Node) NewContainer 

func (n *Node) NewContainer(ctx context.Context, vmid int, options ...ContainerOption) (*Task, error)

func (*Node) NewDirectory added in v0.6.0 

func (n *Node) NewDirectory(ctx context.Context, opts *NodeDirectoryOptions) (*Task, error)

NewDirectory formats a block device and mounts it as a per-node directory storage. opts.Name and opts.Device are required. opts.Filesystem defaults to ext4 server-side.

func (*Node) NewFirewallRule added in v0.7.0 

func (n *Node) NewFirewallRule(ctx context.Context, rule *FirewallRule) error

NewFirewallRule creates a firewall rule on the node. After a successful POST the rule is wired with parent context so subsequent Update/Delete/Get calls route correctly. Note: PVE's POST does not return the assigned position; callers that need it should re-list via FirewallRules.

func (*Node) NewLVM added in v0.6.0 

func (n *Node) NewLVM(ctx context.Context, opts *NodeLVMOptions) (*Task, error)

NewLVM creates an LVM volume group on a block device. opts.Name and opts.Device are required.

func (*Node) NewLVMThin added in v0.6.0 

func (n *Node) NewLVMThin(ctx context.Context, opts *NodeLVMThinOptions) (*Task, error)

NewLVMThin creates an LVM-thin pool on a block device.

func (*Node) NewNetwork 

func (n *Node) NewNetwork(ctx context.Context, network *NodeNetwork) (task *Task, err error)

func (*Node) NewVirtualMachine 

func (n *Node) NewVirtualMachine(ctx context.Context, vmid int, options ...VirtualMachineOption) (*Task, error)

func (*Node) NewZFSPool added in v0.6.0 

func (n *Node) NewZFSPool(ctx context.Context, opts *NodeZFSPoolOptions) (*Task, error)

NewZFSPool creates a ZFS pool. opts.Name, opts.Devices (space-separated), and opts.RaidLevel are required.

func (*Node) OrderACMECertificate added in v0.6.0 

func (n *Node) OrderACMECertificate(ctx context.Context, force bool) (*Task, error)

OrderACMECertificate orders a new ACME certificate using the node's configured ACME account/plugin. force=true overwrites an existing custom or ACME certificate. POST /nodes/{node}/certificates/acme/certificate.

func (*Node) PCIDevice added in v0.6.0 

func (n *Node) PCIDevice(id string) *PCIDevice

PCIDevice returns a handle for a single PCI device by id ("0000:01:00.0") or by cluster-mapping name. No API call.

func (*Node) QEMUCPUFlags added in v0.6.0 

func (n *Node) QEMUCPUFlags(ctx context.Context, arch, accel string) (flags []*QEMUCPUFlag, err error)

QEMUCPUFlags lists VM-visible CPU flags supported on this node. accel is "kvm" (default) or "tcg"; arch is "" / "x86_64" / "aarch64". aarch64 returns an empty list per PVE — no VM-specific flags are defined yet.

func (*Node) QEMUCPUModels added in v0.6.0 

func (n *Node) QEMUCPUModels(ctx context.Context, arch string) (models []*QEMUCPUModel, err error)

QEMUCPUModels lists all available CPU models, both built-in QEMU types and any custom models defined on the cluster. arch is "" (host default), "x86_64", or "aarch64".

func (*Node) QEMUCapabilitiesIndex added in v0.6.0 

func (n *Node) QEMUCapabilitiesIndex(ctx context.Context) ([]string, error)

QEMUCapabilitiesIndex enumerates the QEMU capability subresources ("cpu", "cpu-flags", "machines", "migration").

func (*Node) QEMUMachineTypes added in v0.6.0 

func (n *Node) QEMUMachineTypes(ctx context.Context, arch string) (types []*QEMUMachineType, err error)

QEMUMachineTypes returns the q35 / i440fx versions available on this host. arch is "" (host default), "x86_64", or "aarch64".

func (*Node) QEMUMigrationCapabilities added in v0.6.0 

func (n *Node) QEMUMigrationCapabilities(ctx context.Context) (caps *QEMUMigrationCapabilities, err error)

QEMUMigrationCapabilities returns node-specific live migration features — currently just whether dbus-vmstate is available for live-migrating additional VM state.

func (*Node) QueryOCIRepoTags added in v0.6.0 

func (n *Node) QueryOCIRepoTags(ctx context.Context, reference string) (tags []string, err error)

QueryOCIRepoTags lists all tags advertised by an OCI registry for the given repo reference (e.g. "docker.io/library/alpine").

func (*Node) QueryURLMetadata added in v0.6.0 

func (n *Node) QueryURLMetadata(ctx context.Context, fileURL string, verifyTLS *bool) (meta *NodeURLMetadata, err error)

QueryURLMetadata HEADs the URL and returns filename / mimetype / size. Used to pre-flight a download-url request without committing storage. verifyTLS=nil uses the PVE default (true); pass false to skip cert validation against self-signed servers.

func (*Node) RRD added in v0.6.0 

func (n *Node) RRD(ctx context.Context, ds string, timeframe Timeframe, cf ConsolidationFunction) (rrd *NodeRRDImage, err error)

RRD asks PVE to render a single-graph PNG and returns its on-disk path (lives in PVE's rrdcached dir). Most callers want RRDData for numbers; this exists for parity with the web UI's graph rendering. ds is a comma-separated list of datasources (cpu/mem/diskread/...). cf is optional — empty defaults to AVERAGE server-side.

func (*Node) RRDData added in v0.6.0 

func (n *Node) RRDData(ctx context.Context, timeframe Timeframe, cf ConsolidationFunction) (data []*RRDData, err error)

RRDData returns the node's historical cpu/mem/disk/net timeseries. cf is optional — empty defaults to AVERAGE server-side.

func (*Node) Reboot added in v0.6.0 

func (n *Node) Reboot(ctx context.Context) error

Reboot reboots the node. Requires Sys.PowerMgmt on /nodes/{node}. PVE returns null — no task to track.

func (*Node) RefreshSubscription added in v0.6.0 

func (n *Node) RefreshSubscription(ctx context.Context, force bool) error

RefreshSubscription asks the node to re-validate the cached subscription status against Proxmox's servers. force=true bypasses the local cache and always hits the upstream. POST /nodes/{node}/subscription.

func (*Node) RenewACMECertificate added in v0.6.0 

func (n *Node) RenewACMECertificate(ctx context.Context, force bool) (*Task, error)

RenewACMECertificate renews the node's ACME certificate. PVE skips renewal when the cert is more than 30 days from expiry — force=true overrides that check. PUT /nodes/{node}/certificates/acme/certificate.

func (*Node) Replication added in v0.6.0 

func (n *Node) Replication(id string) *NodeReplicationJob

Replication returns a handle to a single replication job on this node. It does not perform an API call; use the returned job's methods to query or act on the underlying /nodes/{node}/replication/{id}/* endpoints.

func (*Node) Replications added in v0.6.0 

func (n *Node) Replications(ctx context.Context, guest int) (jobs []*NodeReplicationJob, err error)

Replications returns replication-job status from the node's perspective. The cluster-wide job *configuration* lives at /cluster/replication; this endpoint reports per-node runtime state (last sync, last duration, fail count, etc.) for each job that targets or originates on this node. guest filters to a specific VMID; pass 0 for all.

func (*Node) Report added in v0.2.4 

func (n *Node) Report(ctx context.Context) (report string, err error)

func (*Node) RestartCeph added in v0.6.0 

func (n *Node) RestartCeph(ctx context.Context, service string) (*Task, error)

RestartCeph restarts Ceph services on the node. See StartCeph for service syntax.

func (*Node) RevertNetworkChanges added in v0.6.0 

func (n *Node) RevertNetworkChanges(ctx context.Context) error

RevertNetworkChanges discards any pending /etc/network/interfaces.new staged by network create/update calls but not yet reloaded.

func (*Node) RevokeACMECertificate added in v0.6.0 

func (n *Node) RevokeACMECertificate(ctx context.Context) (*Task, error)

RevokeACMECertificate revokes the node's ACME certificate with the issuing CA. DELETE /nodes/{node}/certificates/acme/certificate.

func (*Node) SDNFabricIndex added in v0.6.0 

func (n *Node) SDNFabricIndex(ctx context.Context, fabric string) ([]string, error)

SDNFabricIndex enumerates the children of /nodes/{node}/sdn/fabrics/{fabric} (typically "routes", "neighbors", "interfaces").

func (*Node) SDNFabricInterfaces added in v0.6.0 

func (n *Node) SDNFabricInterfaces(ctx context.Context, fabric string) (ifaces []*SDNFabricInterface, err error)

SDNFabricInterfaces returns the interfaces participating in the named fabric.

func (*Node) SDNFabricNeighbors added in v0.6.0 

func (n *Node) SDNFabricNeighbors(ctx context.Context, fabric string) (neighbors []*SDNFabricNeighbor, err error)

SDNFabricNeighbors returns the FRR neighbor table for the named fabric.

func (*Node) SDNFabricRoutes added in v0.6.0 

func (n *Node) SDNFabricRoutes(ctx context.Context, fabric string) (routes []*SDNFabricRoute, err error)

SDNFabricRoutes returns routes learned/configured for the named fabric.

func (*Node) SDNIndex added in v0.6.0 

func (n *Node) SDNIndex(ctx context.Context) ([]string, error)

SDNIndex enumerates the children of /nodes/{node}/sdn (typically "vnets", "zones", "fabrics"). The PVE schema documents it as a directory index, so we collapse the {"subdir": ...} link objects into a flat []string.

func (*Node) SDNVNetIndex added in v0.6.0 

func (n *Node) SDNVNetIndex(ctx context.Context, vnet string) ([]string, error)

SDNVNetIndex enumerates the children of /nodes/{node}/sdn/vnets/{vnet} (currently just "mac-vrf" on EVPN zones).

func (*Node) SDNVNetMACVRF added in v0.6.0 

func (n *Node) SDNVNetMACVRF(ctx context.Context, vnet string) (entries []*SDNMACVRFEntry, err error)

SDNVNetMACVRF returns the MAC VRF for a VNet in an EVPN zone — entries either self-originated by this node or learned via BGP.

func (*Node) SDNZoneBridges added in v0.6.0 

func (n *Node) SDNZoneBridges(ctx context.Context, zone string) (bridges []*SDNZoneBridge, err error)

SDNZoneBridges returns the bridges (vnets) deployed for the zone, with their member ports — useful for correlating guest NICs to VLANs.

func (*Node) SDNZoneContent added in v0.6.0 

func (n *Node) SDNZoneContent(ctx context.Context, zone string) (content []*SDNZoneContent, err error)

SDNZoneContent lists VNets in the zone with their per-node deployment status.

func (*Node) SDNZoneIPVRF added in v0.6.0 

func (n *Node) SDNZoneIPVRF(ctx context.Context, zone string) (entries []*SDNIPVRFEntry, err error)

SDNZoneIPVRF returns the IP VRF of an EVPN zone (entries from BGP and the kernel routing table, excluding the /32s for guests on this host — those go through the vnet bridge directly).

func (*Node) SDNZoneIndex added in v0.6.0 

func (n *Node) SDNZoneIndex(ctx context.Context, zone string) ([]string, error)

SDNZoneIndex enumerates the children of /nodes/{node}/sdn/zones/{zone} (typically "content", "bridges", "ip-vrf").

func (*Node) SDNZones added in v0.6.0 

func (n *Node) SDNZones(ctx context.Context) (zones []*SDNZoneStatus, err error)

SDNZones returns the runtime status of every SDN zone visible to the node. Distinct from Cluster.SDNZones, which returns config — this returns per-node deployment state ("available", "pending", "error").

func (*Node) ScanCIFS added in v0.6.0 

func (n *Node) ScanCIFS(ctx context.Context, opts *ScanCIFSOptions) (shares []*ScanCIFSShare, err error)

ScanCIFS lists shares on the given SMB/CIFS server.

func (*Node) ScanISCSI added in v0.6.0 

func (n *Node) ScanISCSI(ctx context.Context, portal string) (targets []*ScanISCSITarget, err error)

ScanISCSI lists iSCSI targets reachable through the portal (IP or DNS, optionally with :port).

func (*Node) ScanIndex added in v0.6.0 

func (n *Node) ScanIndex(ctx context.Context) ([]string, error)

ScanIndex enumerates the children of /nodes/{node}/scan ("zfs", "lvm", "nfs", ...). PVE schema returns [{"method":...}]; collapsed to []string.

func (*Node) ScanLVM added in v0.6.0 

func (n *Node) ScanLVM(ctx context.Context) (vgs []*ScanLVMVG, err error)

ScanLVM lists LVM volume groups on this node — local probe, no parameters.

func (*Node) ScanLVMThin added in v0.6.0 

func (n *Node) ScanLVMThin(ctx context.Context, vg string) (pools []*ScanLVMThinPool, err error)

ScanLVMThin lists thin pools inside the given LVM volume group.

func (*Node) ScanNFS added in v0.6.0 

func (n *Node) ScanNFS(ctx context.Context, server string) (exports []*ScanNFSExport, err error)

ScanNFS lists NFS exports on the given server. Server is name or IP.

func (*Node) ScanPBS added in v0.6.0 

func (n *Node) ScanPBS(ctx context.Context, opts *ScanPBSOptions) (stores []*ScanPBSStore, err error)

ScanPBS lists datastores on the given Proxmox Backup Server.

func (*Node) ScanZFS added in v0.6.0 

func (n *Node) ScanZFS(ctx context.Context) (pools []*ScanZFSPool, err error)

ScanZFS lists ZFS pools on this node — local probe, no parameters.

func (*Node) Service added in v0.6.0 

func (n *Node) Service(name string) *NodeService

Service returns a handle for a single service without making an API call. Use State to populate the handle from /nodes/{node}/services/{name}/state, or just call Start/Stop/Restart/Reload directly.

func (*Node) Services added in v0.6.0 

func (n *Node) Services(ctx context.Context) (services []*NodeService, err error)

Services returns the list of services on the node (pveproxy, pvedaemon, corosync, ssh, etc.). GET /nodes/{node}/services. Each returned *NodeService is pre-populated with client and Node so callers can chain instance methods (Start, Stop, Restart, Reload, State) directly.

func (*Node) SetSubscription added in v0.6.0 

func (n *Node) SetSubscription(ctx context.Context, key string) error

SetSubscription registers a Proxmox VE subscription key on the node. PUT /nodes/{node}/subscription.

func (*Node) SetTimezone added in v0.6.0 

func (n *Node) SetTimezone(ctx context.Context, timezone string) error

SetTimezone sets the node's timezone. Valid names come from /usr/share/zoneinfo/zone.tab. PUT /nodes/{node}/time.

func (*Node) Shutdown added in v0.6.0 

func (n *Node) Shutdown(ctx context.Context) error

Shutdown powers off the node. Requires Sys.PowerMgmt on /nodes/{node}.

func (*Node) SpiceShell added in v0.6.0 

func (n *Node) SpiceShell(ctx context.Context, opts *NodeSpiceShellOptions) (proxy *SpiceProxy, err error)

SpiceShell opens a SPICE proxy. Returned object can be fed directly to remote-viewer.

func (*Node) StartAll added in v0.6.0 

func (n *Node) StartAll(ctx context.Context, opts *NodeStartAllOptions) (*Task, error)

StartAll starts every VM and container on the node honoring the configured startup order. Pass NodeStartAllOptions{Force: IntOrBool(true)} to bypass the order, or VMs to limit the set of guests started.

func (*Node) StartCeph added in v0.6.0 

func (n *Node) StartCeph(ctx context.Context, service string) (*Task, error)

StartCeph starts Ceph services on the node. service is optional (defaults to "ceph.target", i.e. all roles); pass e.g. "osd.3" or "mon" to target a single daemon or role.

func (*Node) Status added in v0.3.0 

func (n *Node) Status(ctx context.Context) error

func (*Node) StopAll added in v0.6.0 

func (n *Node) StopAll(ctx context.Context, opts *NodeStopAllOptions) (*Task, error)

StopAll stops every VM and container on the node. ForceStop defaults to 1 (true) server-side; pass a populated NodeStopAllOptions to override timeout or restrict which guests are stopped.

func (*Node) StopCeph added in v0.6.0 

func (n *Node) StopCeph(ctx context.Context, service string) (*Task, error)

StopCeph stops Ceph services on the node. See StartCeph for service syntax.

func (*Node) Storage 

func (n *Node) Storage(ctx context.Context, name string) (storage *Storage, err error)

func (*Node) StorageBackup 

func (n *Node) StorageBackup(ctx context.Context) (*Storage, error)

func (*Node) StorageDownloadURL 

func (n *Node) StorageDownloadURL(ctx context.Context, options *StorageDownloadURLOptions) (ret string, err error)

func (*Node) StorageISO 

func (n *Node) StorageISO(ctx context.Context) (*Storage, error)

func (*Node) StorageImages 

func (n *Node) StorageImages(ctx context.Context) (*Storage, error)

func (*Node) StorageRootDir 

func (n *Node) StorageRootDir(ctx context.Context) (*Storage, error)

func (*Node) StorageSnippets added in v0.6.0 

func (n *Node) StorageSnippets(ctx context.Context) (*Storage, error)

StorageSnippets returns a storage configured for the "snippets" content type. Note that Proxmox does not expose a REST upload endpoint for snippets — they must be written to the storage path directly (e.g. via SCP/SFTP). This helper is for read-side discovery (e.g. resolving the storage's path so a caller can write to it out-of-band).

func (*Node) StorageVZTmpl 

func (n *Node) StorageVZTmpl(ctx context.Context) (*Storage, error)

func (*Node) Storages 

func (n *Node) Storages(ctx context.Context) (storages Storages, err error)

func (*Node) Subdirs added in v0.7.0 

func (n *Node) Subdirs(ctx context.Context) ([]string, error)

Subdirs enumerates the children of /nodes/{node} (typically "qemu", "lxc", "storage", "network", "tasks", "scan", "services", "subscription", etc.). Useful as a permission probe: PVE filters the list by the caller's ACLs, so the result tells you which sub-APIs the credential can read.

func (*Node) Subscription added in v0.6.0 

func (n *Node) Subscription(ctx context.Context) (sub *Subscription, err error)

Subscription reads the node's subscription state — license level, status, next-due-date, etc. GET /nodes/{node}/subscription.

func (*Node) SuspendAll added in v0.6.0 

func (n *Node) SuspendAll(ctx context.Context, opts *NodeSuspendAllOptions) (*Task, error)

SuspendAll suspends every VM on the node. (LXC containers are not suspended by this endpoint — PVE only honors VMs here.)

func (*Node) Syslog added in v0.6.0 

func (n *Node) Syslog(ctx context.Context, opts *NodeSyslogOptions) (entries []*LogEntry, err error)

Syslog returns rsyslog lines as {n, t} entries — n is the line number, t the text. For systemd journal, use Journal instead.

func (*Node) Tasks added in v0.6.0 

func (n *Node) Tasks(ctx context.Context, opts *NodeTasksOptions) (tasks []*Task, err error)

Tasks lists finished tasks on this node. Pre-populates each *Task with client + node so callers can chain Wait/Log/Stop. Unlike Task.Wait which targets one UPID, this lists archived/active tasks for monitoring.

func (*Node) TermProxy 

func (n *Node) TermProxy(ctx context.Context) (term *Term, err error)

func (*Node) TermWebSocket added in v0.1.2 

func (n *Node) TermWebSocket(term *Term) (chan []byte, chan []byte, chan error, func() error, error)

func (*Node) Time added in v0.6.0 

func (n *Node) Time(ctx context.Context) (t *NodeTime, err error)

Time returns the node's current time and timezone configuration. GET /nodes/{node}/time. The "time" and "localtime" fields are unix epoch seconds — see NodeTime.

func (*Node) UpdateConfig added in v0.6.0 

func (n *Node) UpdateConfig(ctx context.Context, opts *NodeConfigOptions) error

UpdateConfig sets node configuration options. Passing nil opts is a no-op on the server. Use opts.Delete to unset specific keys.

func (*Node) UpdateDNS added in v0.6.0 

func (n *Node) UpdateDNS(ctx context.Context, dns *NodeDNS) error

UpdateDNS rewrites the node's resolver configuration. The Search field is required by PVE; an empty Search will be rejected by the server. The three DNS slots are optional individually but supplied together — sending the struct replaces all of them.

func (*Node) UpdateHosts added in v0.6.0 

func (n *Node) UpdateHosts(ctx context.Context, data, digest string) error

UpdateHosts overwrites /etc/hosts on the node. digest is optional — if non-empty, PVE refuses the write when the current file differs from it.

func (*Node) UploadCustomCertificate 

func (n *Node) UploadCustomCertificate(ctx context.Context, cert *CustomCertificate) error

func (*Node) VNCShell added in v0.6.0 

func (n *Node) VNCShell(ctx context.Context, opts *NodeVNCShellOptions) (vnc *VNC, err error)

VNCShell opens a VNC proxy to the node — typically a serial-like login shell. Returns ticket + port for the websocket follow-up call.

func (*Node) VNCWebSocket 

func (n *Node) VNCWebSocket(vnc *VNC) (chan []byte, chan []byte, chan error, func() error, error)

VNCWebSocket send, recv, errors, closer, error

func (*Node) Version 

func (n *Node) Version(ctx context.Context) (version *Version, err error)

func (*Node) VirtualMachine 

func (n *Node) VirtualMachine(ctx context.Context, vmid int) (*VirtualMachine, error)

func (*Node) VirtualMachines 

func (n *Node) VirtualMachines(ctx context.Context) (vms VirtualMachines, err error)

func (*Node) VzTmpl 

func (n *Node) VzTmpl(ctx context.Context, template, storage string) (*VzTmpl, error)

func (*Node) VzTmpls 

func (n *Node) VzTmpls(ctx context.Context, storage string) (templates VzTmpls, err error)

func (*Node) Vzdump 

func (n *Node) Vzdump(ctx context.Context, params *VirtualMachineBackupOptions) (task *Task, err error)

func (*Node) VzdumpDefaults added in v0.6.0 

func (n *Node) VzdumpDefaults(ctx context.Context, storage string) (defaults map[string]any, err error)

VzdumpDefaults returns the effective default vzdump options for this node, optionally narrowed to a specific backup storage. The schema mirrors POST /nodes/{node}/vzdump — wrapped as a map for forward compatibility.

func (*Node) VzdumpExtractConfig 

func (n *Node) VzdumpExtractConfig(ctx context.Context, volume string) (*VzdumpConfig, error)

func (*Node) WakeOnLAN added in v0.6.0 

func (n *Node) WakeOnLAN(ctx context.Context) (mac string, err error)

WakeOnLAN sends a Wake-on-LAN magic packet to the node and returns the MAC address that was woken. PVE looks up the WoL MAC from the cluster config — the node's wakeonlan setting (see datacenter.cfg) must be configured.

func (*Node) ZFSPool added in v0.6.0 

func (n *Node) ZFSPool(ctx context.Context, name string) (pool *NodeZFSPool, err error)

ZFSPool returns the detailed status of a single pool, including the underlying vdev/device tree and any failure-action recommendation.

func (*Node) ZFSPools added in v0.6.0 

func (n *Node) ZFSPools(ctx context.Context) (pools []*NodeZFSPoolSummary, err error)

ZFSPools lists ZFS pools visible to PVE on the node.

type NodeCertificate 

type NodeCertificate struct {
	Filename      string   `json:"filename,omitempty"`
	Fingerprint   string   `json:"fingerprint,omitempty"`
	Issuer        string   `json:"issuer,omitempty"`
	NotAfter      string   `json:"not-after,omitempty"`
	NotBefore     string   `json:"not-before,omitempty"`
	Pem           string   `json:"pem,omitempty"`
	PublicKeyBits int      `json:"public-key-bits,omitempty"`
	PublicKeyType string   `json:"public-key-type,omitempty"`
	San           []string `json:"san,omitempty"`
	Subject       string   `json:"subject,omitempty"`
}

type NodeCertificates 

type NodeCertificates []*NodeCertificate

type NodeConfig added in v0.6.0 

type NodeConfig struct {
	Acme                string `json:"acme,omitempty"`
	AcmeDomain0         string `json:"acmedomain0,omitempty"`
	AcmeDomain1         string `json:"acmedomain1,omitempty"`
	AcmeDomain2         string `json:"acmedomain2,omitempty"`
	AcmeDomain3         string `json:"acmedomain3,omitempty"`
	AcmeDomain4         string `json:"acmedomain4,omitempty"`
	AcmeDomain5         string `json:"acmedomain5,omitempty"`
	BallooningTarget    int    `json:"ballooning-target,omitempty"`
	Description         string `json:"description,omitempty"`
	Digest              string `json:"digest,omitempty"`
	Location            string `json:"location,omitempty"`
	StartAllOnBootDelay int    `json:"startall-onboot-delay,omitempty"`
	WakeOnLAN           string `json:"wakeonlan,omitempty"`
}

NodeConfig is the read shape of GET /nodes/{node}/config. Substructure fields (Acme, AcmeDomain[N], Location, WakeOnLAN) come back as PVE property strings ("key=val,..."); parsing them is left to callers since the schema may grow.

type NodeConfigOptions added in v0.6.0 

type NodeConfigOptions struct {
	Acme        string `json:"acme,omitempty"`
	AcmeDomain0 string `json:"acmedomain0,omitempty"`
	AcmeDomain1 string `json:"acmedomain1,omitempty"`
	AcmeDomain2 string `json:"acmedomain2,omitempty"`
	AcmeDomain3 string `json:"acmedomain3,omitempty"`
	AcmeDomain4 string `json:"acmedomain4,omitempty"`
	AcmeDomain5 string `json:"acmedomain5,omitempty"`
	// BallooningTarget — PVE default 80 (% of host RAM the ballooning target
	// dials toward). Pointer so unset doesn't reset the target to 0% on edit.
	// See #199.
	BallooningTarget *int   `json:"ballooning-target,omitempty"`
	Delete           string `json:"delete,omitempty"`
	Description      string `json:"description,omitempty"`
	Digest           string `json:"digest,omitempty"`
	Location         string `json:"location,omitempty"`
	// StartAllOnBootDelay — PVE default 1 (second of delay between guests
	// during the boot-time startall sweep). Pointer so unset doesn't
	// collapse the delay to 0. See #199.
	StartAllOnBootDelay *int   `json:"startall-onboot-delay,omitempty"`
	WakeOnLAN           string `json:"wakeonlan,omitempty"`
}

NodeConfigOptions is the write shape for PUT /nodes/{node}/config. Set Delete to a comma-separated list of keys to unset them; pass Digest from a prior GetConfig for optimistic concurrency.

type NodeConsoleCmd added in v0.6.0 

type NodeConsoleCmd string

NodeConsoleCmd narrows the shell command. Empty defaults to "login" (requires root@pam). 

const (
	NodeConsoleLogin       NodeConsoleCmd = "login"
	NodeConsoleUpgrade     NodeConsoleCmd = "upgrade"
	NodeConsoleCephInstall NodeConsoleCmd = "ceph_install"
)

type NodeDNS added in v0.6.0 

type NodeDNS struct {
	Search string `json:"search,omitempty"`
	DNS1   string `json:"dns1,omitempty"`
	DNS2   string `json:"dns2,omitempty"`
	DNS3   string `json:"dns3,omitempty"`
}

NodeDNS represents the resolver configuration for a single node, as returned by GET /nodes/{node}/dns and accepted by PUT /nodes/{node}/dns. Search is required on update; the three DNS slots are individually optional.

type NodeDirectory added in v0.6.0 

type NodeDirectory struct {
	Device  string `json:"device,omitempty"`
	Options string `json:"options,omitempty"`
	Path    string `json:"path,omitempty"`
	Type    string `json:"type,omitempty"`
	UUID    string `json:"unitfile,omitempty"`
}

NodeDirectory is one row returned by GET /nodes/{node}/disks/directory.

type NodeDirectoryOptions added in v0.6.0 

type NodeDirectoryOptions struct {
	Name       string    `json:"name"`
	Device     string    `json:"device"`
	Filesystem string    `json:"filesystem,omitempty"` // PVE default ext4
	AddStorage IntOrBool `json:"add_storage,omitempty"`
}

NodeDirectoryOptions is the POST body for /nodes/{node}/disks/directory.

type NodeExecuteCommand added in v0.6.0 

type NodeExecuteCommand struct {
	Method string                 `json:"method"`
	Path   string                 `json:"path"`
	Args   map[string]interface{} `json:"args,omitempty"`
}

NodeExecuteCommand is one entry in the Execute batch. Args carries the API parameters as PVE-native key/value pairs.

type NodeFirewallLogOptions added in v0.6.0 

type NodeFirewallLogOptions struct {
	Start int
	Limit int
	Since int64 // unix epoch
	Until int64 // unix epoch
}

NodeFirewallLogOptions filters the host-firewall log read. All optional.

type NodeHosts added in v0.6.0 

type NodeHosts struct {
	Data   string `json:"data"`
	Digest string `json:"digest,omitempty"`
}

NodeHosts is the read shape of GET /nodes/{node}/hosts. Pass Digest back to UpdateHosts for concurrency-safe writes.

type NodeJournalOptions added in v0.6.0 

type NodeJournalOptions struct {
	Since       int64
	Until       int64
	StartCursor string
	EndCursor   string
	LastEntries int
}

NodeJournalOptions filters the systemd journal read. Pass either Since/ Until OR StartCursor/EndCursor (PVE rejects mixing). LastEntries conflicts with any range.

type NodeLVMOptions added in v0.6.0 

type NodeLVMOptions struct {
	Name       string    `json:"name"`
	Device     string    `json:"device"`
	AddStorage IntOrBool `json:"add_storage,omitempty"`
}

NodeLVMOptions is the POST body for /nodes/{node}/disks/lvm.

type NodeLVMPhysical added in v0.6.0 

type NodeLVMPhysical struct {
	Name string    `json:"name,omitempty"`
	Size uint64    `json:"size,omitempty"`
	Free uint64    `json:"free,omitempty"`
	Leaf IntOrBool `json:"leaf,omitempty"`
}

type NodeLVMThin added in v0.6.0 

type NodeLVMThin struct {
	LV           string `json:"lv,omitempty"`
	LVSize       uint64 `json:"lv_size,omitempty"`
	MetadataSize uint64 `json:"metadata_size,omitempty"`
	MetadataUsed uint64 `json:"metadata_used,omitempty"`
	Used         uint64 `json:"used,omitempty"`
}

NodeLVMThin is one row from GET /nodes/{node}/disks/lvmthin.

type NodeLVMThinOptions added in v0.6.0 

type NodeLVMThinOptions struct {
	Name       string    `json:"name"`
	Device     string    `json:"device"`
	AddStorage IntOrBool `json:"add_storage,omitempty"`
}

NodeLVMThinOptions is the POST body for /nodes/{node}/disks/lvmthin.

type NodeLVMTree added in v0.6.0 

type NodeLVMTree struct {
	Children []NodeLVMVolumeGroup `json:"children,omitempty"`
	Leaf     IntOrBool            `json:"leaf,omitempty"`
}

NodeLVMTree is the nested response from GET /nodes/{node}/disks/lvm. Each child is a volume group whose own children are the constituent physical volumes.

type NodeLVMVolumeGroup added in v0.6.0 

type NodeLVMVolumeGroup struct {
	Name     string            `json:"name,omitempty"`
	Size     uint64            `json:"size,omitempty"`
	Free     uint64            `json:"free,omitempty"`
	Leaf     IntOrBool         `json:"leaf,omitempty"`
	Children []NodeLVMPhysical `json:"children,omitempty"`
}

type NodeMigrateAllOptions added in v0.6.0 

type NodeMigrateAllOptions struct {
	Target         string    `json:"target"`
	MaxWorkers     uint64    `json:"maxworkers,omitempty"`       // parallel migration workers
	VMs            string    `json:"vms,omitempty"`              // comma-separated VMID list to limit
	WithLocalDisks IntOrBool `json:"with-local-disks,omitempty"` // include local disks via storage migration
}

NodeMigrateAllOptions is the body for POST /nodes/{node}/migrateall. Target is required — the destination node name.

type NodeNetwork 

type NodeNetwork struct {
	Node    string `json:"-"`
	NodeAPI *Node  `json:"-"`

	Iface     string `json:"iface,omitempty"`
	Autostart int    `json:"autostart,omitempty"`

	CIDR               string `json:"cidr,omitempty"`
	CIDR6              string `json:"cidr6,omitempty"`
	Gateway            string `json:"gateway,omitempty"`
	Gateway6           string `json:"gateway6,omitempty"`
	MTU                string `json:"mtu,omitempty"`
	Netmask            string `json:"netmask,omitempty"`
	Netmask6           string `json:"netmask6,omitempty"`
	VLANID             string `json:"vlan-id,omitempty"`
	VLANRawDevice      string `json:"vlan-raw-device,omitempty"`
	BridgeVLANAware    int    `json:"bridge_vlan_aware,omitempty"`
	BridgePorts        string `json:"bridge_ports,omitempty"`
	BridgeStp          string `json:"bridge_stp,omitempty"` // not in current docs, deprecated?
	BridgeFd           string `json:"bridge_fd,omitempty"`  // not in current docs, deprecated?
	Comments           string `json:"comments,omitempty"`
	Comments6          string `json:"comments6,omitempty"`
	BondPrimary        string `json:"bond-primary,omitempty"`
	BondMode           string `json:"bond_mode,omitempty"`
	BondXmit           string `json:"bond_xmit,omitempty"`
	BondXmitHashPolicy string `json:"bond_xmit_hash_policy,omitempty"`

	OVSBonds   string `json:"ovs_bonds,omitempty"`
	OVSBridge  string `json:"ovs_bridge,omitempty"`
	OVSOptions string `json:"ovs_options,omitempty"`
	OVSPorts   string `json:"ovs_ports,omitempty"`
	OVSTags    string `json:"ovs_tag,omitempty"`

	Slaves   string      `json:"slaves,omitempty"`
	Address  string      `json:"address,omitempty"`
	Address6 string      `json:"address6,omitempty"`
	Type     string      `json:"type,omitempty"`
	Active   StringOrInt `json:"active,omitempty"`
	Method   string      `json:"method,omitempty"`
	Method6  string      `json:"method6,omitempty"`
	Priority int         `json:"priority,omitempty"`
	// contains filtered or unexported fields
}

func (*NodeNetwork) Delete 

func (nw *NodeNetwork) Delete(ctx context.Context) (task *Task, err error)

func (*NodeNetwork) Update 

func (nw *NodeNetwork) Update(ctx context.Context) error

type NodeNetworks 

type NodeNetworks []*NodeNetwork

type NodeRRDImage added in v0.6.0 

type NodeRRDImage struct {
	Filename string `json:"filename"`
}

NodeRRDImage is the response shape of GET /nodes/{node}/rrd — and the matching storage variant. The filename lives in PVE's rrdcached directory.

type NodeReplicationJob added in v0.6.0 

type NodeReplicationJob struct {
	Node string `json:"-"`

	ID        string  `json:"id"`
	Type      string  `json:"type,omitempty"`
	Source    string  `json:"source,omitempty"`
	Target    string  `json:"target,omitempty"`
	Guest     int     `json:"guest,omitempty"`
	JobNum    int     `json:"jobnum,omitempty"`
	Schedule  string  `json:"schedule,omitempty"`
	LastSync  int64   `json:"last_sync,omitempty"` // epoch
	LastTry   int64   `json:"last_try,omitempty"`  // epoch
	NextSync  int64   `json:"next_sync,omitempty"` // epoch
	Duration  float64 `json:"duration,omitempty"`  // seconds
	FailCount int     `json:"fail_count,omitempty"`
	Error     string  `json:"error,omitempty"`
	PID       int     `json:"pid,omitempty"`
	State     string  `json:"state,omitempty"`
	// contains filtered or unexported fields
}

NodeReplicationJob is a handle to a replication job on a node and the runtime state for that job: what was last synced, fail count, next-sync time. The cluster-wide configuration of the job lives at /cluster/replication; this is the per-node view of how that job is *running*. Methods on this type wrap /nodes/{node}/replication/{id}/*.

func (*NodeReplicationJob) Log added in v0.6.0 

func (r *NodeReplicationJob) Log(ctx context.Context, start, limit int) (entries []*LogEntry, err error)

Log returns the job's log lines. start/limit are optional pagination — pass 0 for default. PVE returns a list of {n, t} entries where n is line number and t is the line text.

func (*NodeReplicationJob) ScheduleNow added in v0.6.0 

func (r *NodeReplicationJob) ScheduleNow(ctx context.Context) (*Task, error)

ScheduleNow asks PVE to run this replication job as soon as possible (bypassing its schedule). POST /nodes/{node}/replication/{id}/schedule_now — returns a Task UPID.

func (*NodeReplicationJob) Status added in v0.6.0 

func (r *NodeReplicationJob) Status(ctx context.Context) error

Status refreshes runtime state for this replication job in-place. GET /nodes/{node}/replication/{id}/status. The /replication/{id} root is just a tree index and is intentionally not wrapped.

func (*NodeReplicationJob) Subdirs added in v0.7.0 

func (r *NodeReplicationJob) Subdirs(ctx context.Context) ([]string, error)

Subdirs enumerates the children of /nodes/{node}/replication/{id} ("status", "log", "schedule_now"). /nodes/{node}/replication (without {id}) is a true list endpoint, not a diridx; use (*Node).Replications for that.

type NodeService added in v0.6.0 

type NodeService struct {
	Node string `json:"-"`

	Service string `json:"service"`
	Name    string `json:"name,omitempty"`
	Desc    string `json:"desc,omitempty"`
	// Status is PVE's "state" field — running / stopped / unknown. Renamed
	// from State so the instance method State(ctx) can populate the handle
	// without colliding with a field of the same name.
	Status      string `json:"state,omitempty"`
	ActiveState string `json:"active-state,omitempty"` // active / inactive / failed
	UnitState   string `json:"unit-state,omitempty"`   // enabled / disabled / masked
	// contains filtered or unexported fields
}

NodeService is one row of the services list and the response shape of /nodes/{node}/services/{service}/state. The same struct fits both because the list returns the same per-service info, just batched.

client and Node are populated by Node.Services and Node.Service so callers can chain instance methods (Start/Stop/Restart/Reload/State) without re-threading the client. Name holds the service identifier (e.g. "pveproxy") — it doubles as the JSON-decoded "name" field returned by PVE and as the path segment used by the instance methods.

func (*NodeService) Reload added in v0.6.0 

func (s *NodeService) Reload(ctx context.Context) (*Task, error)

Reload issues POST /nodes/{node}/services/{name}/reload, which PVE documents as "falls back to restart if reload isn't supported".

func (*NodeService) Restart added in v0.6.0 

func (s *NodeService) Restart(ctx context.Context) (*Task, error)

Restart issues POST /nodes/{node}/services/{name}/restart — a hard restart. Use Reload for graceful restart of services that support it.

func (*NodeService) Start added in v0.6.0 

func (s *NodeService) Start(ctx context.Context) (*Task, error)

Start issues POST /nodes/{node}/services/{name}/start. Returns a Task because PVE does service control asynchronously.

func (*NodeService) State added in v0.6.0 

func (s *NodeService) State(ctx context.Context) error

State refreshes the service handle from GET /nodes/{node}/services/{name}/state. The /services/{name} root is just a directory index and is intentionally not wrapped — state is the only useful read on a specific service.

func (*NodeService) Stop added in v0.6.0 

func (s *NodeService) Stop(ctx context.Context) (*Task, error)

Stop issues POST /nodes/{node}/services/{name}/stop.

func (*NodeService) Subdirs added in v0.7.0 

func (s *NodeService) Subdirs(ctx context.Context) ([]string, error)

Subdirs enumerates the children of /nodes/{node}/services/{service} ("state", "start", "stop", "restart", "reload"). /nodes/{node}/services (without {service}) is a true list endpoint — use (*Node).Services.

type NodeSpiceShellOptions added in v0.6.0 

type NodeSpiceShellOptions struct {
	Cmd     NodeConsoleCmd
	CmdOpts string
	Proxy   string
}

NodeSpiceShellOptions configures the SPICE console launcher. Proxy overrides the SPICE proxy hostname (defaults to the node itself).

type NodeStartAllOptions added in v0.6.0 

type NodeStartAllOptions struct {
	Force IntOrBool `json:"force,omitempty"` // bypass configured startup order
	VMs   string    `json:"vms,omitempty"`   // comma-separated VMID list to limit which guests are started
}

NodeStartAllOptions is the optional body for POST /nodes/{node}/startall.

type NodeStatus 

type NodeStatus struct {
	// shared
	Status string `json:",omitempty"`
	Level  string `json:",omitempty"`
	ID     string `json:",omitempty"` // format "node/<name>"

	// from /nodes endpoint
	Node           string  `json:",omitempty"`
	Type           string  `json:",omitempty"`
	MaxCPU         int     `json:",omitempty"`
	MaxMem         uint64  `json:",omitempty"`
	Disk           uint64  `json:",omitempty"`
	SSLFingerprint string  `json:"ssl_fingerprint,omitempty"`
	MaxDisk        uint64  `json:",omitempty"`
	Mem            uint64  `json:",omitempty"`
	CPU            float64 `json:",omitempty"`
	Uptime         uint64  `json:",omitempty"`

	// from /cluster endpoint
	NodeID int    `json:",omitempty"` // the internal id of the node
	Name   string `json:",omitempty"`
	IP     string `json:",omitempty"`
	Online int    `json:",omitempty"`
	Local  int    `json:",omitempty"`
}

type NodeStatuses 

type NodeStatuses []*NodeStatus

type NodeStopAllOptions added in v0.6.0 

type NodeStopAllOptions struct {
	ForceStop IntOrBool `json:"force-stop,omitempty"` // PVE default 1; pass IntOrBool(false) to allow graceful shutdown to time out
	Timeout   uint64    `json:"timeout,omitempty"`    // per-guest shutdown timeout in seconds (PVE default 180)
	VMs       string    `json:"vms,omitempty"`        // comma-separated VMID list to limit
}

NodeStopAllOptions is the optional body for POST /nodes/{node}/stopall.

type NodeSuspendAllOptions added in v0.6.0 

type NodeSuspendAllOptions struct {
	VMs string `json:"vms,omitempty"` // comma-separated VMID list to limit
}

NodeSuspendAllOptions is the optional body for POST /nodes/{node}/suspendall.

type NodeSyslogOptions added in v0.6.0 

type NodeSyslogOptions struct {
	Start   int
	Limit   int
	Since   string
	Until   string
	Service string
}

NodeSyslogOptions filters the classic syslog reader. Since/Until are "YYYY-MM-DD[ HH:MM[:SS]]" strings per PVE; Service filters to one unit.

type NodeTasksOptions added in v0.6.0 

type NodeTasksOptions struct {
	Errors       bool
	Limit        int
	Since        int64
	Until        int64
	Source       string // "archive" | "active" | "all"
	Start        int
	StatusFilter string // comma-separated task statuses
	TypeFilter   string // task type, e.g. "vzdump"
	UserFilter   string
	VMID         int
}

NodeTasksOptions filters the finished-task index. All fields are optional.

type NodeTime added in v0.6.0 

type NodeTime struct {
	Time      int64  `json:"time"`
	Localtime int64  `json:"localtime"`
	Timezone  string `json:"timezone"`
}

NodeTime is the response from GET /nodes/{node}/time. Time and Localtime are unix epoch seconds (UTC and local-tz-adjusted respectively); Timezone is the IANA name.

type NodeURLMetadata added in v0.6.0 

type NodeURLMetadata struct {
	Filename string `json:"filename,omitempty"`
	MimeType string `json:"mimetype,omitempty"`
	Size     int64  `json:"size,omitempty"`
}

NodeURLMetadata is the response shape of GET /nodes/{node}/query-url-metadata. All fields are optional; PVE leaves them blank when the upstream HEAD response omits the corresponding header.

type NodeVNCShellOptions added in v0.6.0 

type NodeVNCShellOptions struct {
	Cmd       NodeConsoleCmd
	CmdOpts   string
	Width     int
	Height    int
	WebSocket bool
}

NodeVNCShellOptions configures the noVNC console launcher. WebSocket enables noVNC-style transport; Width/Height are pixel dimensions (16-4096 / 16-2160). CmdOpts are null-separated arguments to Cmd.

type NodeZFSPool added in v0.6.0 

type NodeZFSPool struct {
	Name     string        `json:"name,omitempty"`
	State    string        `json:"state,omitempty"`
	Status   string        `json:"status,omitempty"`
	Action   string        `json:"action,omitempty"`
	Scan     string        `json:"scan,omitempty"`
	Errors   string        `json:"errors,omitempty"`
	Children []NodeZFSVdev `json:"children,omitempty"`
}

NodeZFSPool is the detailed pool status from GET /nodes/{node}/disks/zfs/{name}.

type NodeZFSPoolOptions added in v0.6.0 

type NodeZFSPoolOptions struct {
	Name        string    `json:"name"`
	Devices     string    `json:"devices"` // space-separated device list per PVE
	RaidLevel   string    `json:"raidlevel"`
	Ashift      int       `json:"ashift,omitempty"`
	Compression string    `json:"compression,omitempty"`
	DraidConfig string    `json:"draid-config,omitempty"`
	AddStorage  IntOrBool `json:"add_storage,omitempty"`
}

NodeZFSPoolOptions is the POST body for /nodes/{node}/disks/zfs.

type NodeZFSPoolSummary added in v0.6.0 

type NodeZFSPoolSummary struct {
	Name   string  `json:"name,omitempty"`
	Health string  `json:"health,omitempty"`
	Size   uint64  `json:"size,omitempty"`
	Alloc  uint64  `json:"alloc,omitempty"`
	Free   uint64  `json:"free,omitempty"`
	Frag   int     `json:"frag,omitempty"`
	Dedup  float64 `json:"dedup,omitempty"`
}

NodeZFSPoolSummary is one row from GET /nodes/{node}/disks/zfs.

type NodeZFSVdev added in v0.6.0 

type NodeZFSVdev struct {
	Name     string        `json:"name,omitempty"`
	State    string        `json:"state,omitempty"`
	Read     uint64        `json:"read,omitempty"`
	Write    uint64        `json:"write,omitempty"`
	Cksum    uint64        `json:"cksum,omitempty"`
	Msg      string        `json:"msg,omitempty"`
	Children []NodeZFSVdev `json:"children,omitempty"`
	Leaf     IntOrBool     `json:"leaf,omitempty"`
}

type OpenIDAuthURLResponse added in v0.6.0 

type OpenIDAuthURLResponse string

OpenIDAuthURLResponse is what PVE returns from POST /access/openid/auth-url — a URL the caller redirects the browser to so the user can authenticate with the configured OIDC provider.

type OpenIDLoginResponse added in v0.6.0 

type OpenIDLoginResponse struct {
	Ticket              string `json:"ticket,omitempty"`
	CSRFPreventionToken string `json:"CSRFPreventionToken,omitempty"`
	Username            string `json:"username,omitempty"`
	Cap                 any    `json:"cap,omitempty"`
	ClusterName         string `json:"clustername,omitempty"`
}

OpenIDLoginResponse is the post-callback exchange result — same shape as the regular /access/ticket login response (ticket + CSRF token + user).

type Option 

type Option func(*Client)

func WithAPIToken 

func WithAPIToken(tokenID, secret string) Option

func WithClient deprecated 

func WithClient(client *http.Client) Option

Deprecated: Use WithHTTPClient

func WithClientCertificate added in v0.7.0 

func WithClientCertificate(cert tls.Certificate) Option

WithClientCertificate adds a client certificate for mutual TLS. Appends to tls.Config.Certificates so multiple calls compose. Composes with the other TLS options.

func WithCredentials 

func WithCredentials(credentials *Credentials) Option

func WithDefaultRealm added in v0.7.0 

func WithDefaultRealm(realm string) Option

WithDefaultRealm auto-appends "@<realm>" to Credentials.Username if the supplied username has no @realm suffix and Credentials.Realm is empty. Saves the most common credential-auth typo ("root" vs "root@pam").

No effect when token auth is used or when the username already carries a realm.

func WithEagerAuth added in v0.7.0 

func WithEagerAuth() Option

WithEagerAuth makes NewClient call CreateSession synchronously so the first user-facing request doesn't trigger PVE pveproxy's hardcoded 3-second 401 delay on unauthenticated requests. Pveproxy enforces this delay on every failed-or-missing-auth response — see PVE::APIServer::AnyEvent's `# always delay unauthorized calls by 3 seconds` block. With credential auth the client's first request is always unauthenticated (the cookie+CSRF aren't set until /access/ticket succeeds), so it eats the full 3s before the library retries with the ticket. WithEagerAuth pays that cost once at construction instead.

Has no effect with token auth — tokens attach Authorization on every request and never trigger the 401 path. Has no effect when neither credentials nor token are set.

Errors from the eager CreateSession are logged at debug level and otherwise swallowed; the next user request will retry via the existing lazy-auth path. To surface auth errors at startup explicitly, call (*Client).CreateSession yourself instead of using this option.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

func WithInsecureSkipVerify added in v0.7.0 

func WithInsecureSkipVerify() Option

WithInsecureSkipVerify disables TLS certificate verification. For lab use only — production clusters should pin the cluster's CA via WithRootCAs or WithRootCAFile instead.

Composes with WithHTTPClient, WithRootCAs, WithRootCAFile, and WithClientCertificate; option order doesn't matter.

func WithLogger 

func WithLogger(logger LeveledLoggerInterface) Option

func WithLogins deprecated 

func WithLogins(username, password string) Option

Deprecated: Use WithCredential

func WithOTP added in v0.7.0 

func WithOTP(otp string) Option

WithOTP supplies a one-time password (TOTP, Yubico OTP, etc.) for the initial /access/ticket call when the user has two-factor auth enabled. The code is consumed exactly once on the first CreateSession call; subsequent RefreshTicket calls renew the session via the ticket itself and do not need a new OTP.

Requires WithCredentials. No effect when using token auth — tokens bypass 2FA by design.

If the session is fully lost later (PVE restart, ticket past the renewal window) and the client tries to re-authenticate, that call will fail because the OTP is single-use. Callers in that scenario must construct a fresh client with a fresh OTP — the library cannot keep a TOTP around.

func WithProxy added in v0.7.0 

func WithProxy(u *url.URL) Option

WithProxy routes all client traffic through the given proxy URL. The proxy function is applied to the underlying *http.Transport so every request goes through u (use http://, https://, or socks5:// schemes).

Composes with WithHTTPClient regardless of option order: the proxy is applied to whatever client the constructor settles on after all options have run, via the shared finalizeOptions step. If the resulting transport is not an *http.Transport (custom RoundTripper), the option logs a debug warning and no-ops — set .Proxy yourself on a transport you control before passing it to WithHTTPClient.

func WithProxyFromEnvironment added in v0.7.0 

func WithProxyFromEnvironment() Option

WithProxyFromEnvironment uses Go's standard http.ProxyFromEnvironment lookup (HTTP_PROXY, HTTPS_PROXY, NO_PROXY env vars). Env vars are read per-request by http.ProxyFromEnvironment, not at option-eval time, so later changes to the environment are picked up on the next request.

Composes with WithHTTPClient the same way as WithProxy.

func WithRequestInterceptor added in v0.7.0 

func WithRequestInterceptor(fn func(*http.Request) error) Option

WithRequestInterceptor registers a function called on every outgoing HTTP request after the client's auth headers are added and before the request is sent. Use cases: tracing (OpenTelemetry span injection), custom audit headers, correlation IDs, request logging.

The interceptor fires from Client.Req, Client.Upload, and Client.UploadReader. Websocket upgrades (Client.TermWebSocket and Client.VNCWebSocket) are exempt — the dialer does not surface a request object the chain could mutate.

Multiple WithRequestInterceptor options compose — each call appends to the interceptor chain. Interceptors run in registration order. The first non-nil error short-circuits the request, is wrapped with a "request interceptor:" prefix (so callers can errors.Is against their own sentinel errors), and is returned to the caller; the HTTP request is never sent.

A nil fn is silently skipped at registration; nil entries in the chain are also skipped at request time.

func WithRetry added in v0.7.0 

func WithRetry(opts ...RetryOption) Option

WithRetry installs a RoundTripper wrapper that retries transient failures on the underlying transport.

Default policy: max 3 attempts, exponential backoff with full jitter from 200ms to 5s, retries on network errors and HTTP 502, 503, 504, 429. The Retry-After header on 429 or 503 overrides the computed backoff (capped at the configured max). Only idempotent verbs (GET, PUT, DELETE) and POST with a fully-buffered body are retried; in this client request bodies are always []byte, so POST is rewindable.

Cumulative timeout is bounded by the request context; the wrapper respects ctx.Done() between attempts and returns the context error as soon as cancellation is observed.

WithRetry composes with the other transport-touching options (WithInsecureSkipVerify, WithRootCAs, WithClientCertificate, WithProxy, WithProxyFromEnvironment, WithRequestInterceptor). It wraps whichever transport the client currently has when the option runs; if a subsequent WithHTTPClient replaces the client, the retry wrapper is rewrapped onto the new client's transport so the caller's intent is preserved.

func WithRootCAFile added in v0.7.0 

func WithRootCAFile(path string) Option

WithRootCAFile loads a PEM-encoded CA bundle from path and appends every certificate it contains to the TLS root pool. Convenience wrapper around WithRootCAs for the common single-file case.

The file is read at NewClient time (when this option is evaluated). If the file can't be read or contains no valid certificates, the error is logged via the client logger and the option is a no-op — option funcs can't return errors. Callers who need the file-IO error surfaced explicitly should read the file themselves and pass the resulting pool to WithRootCAs.

func WithRootCAs added in v0.7.0 

func WithRootCAs(pool *x509.CertPool) Option

WithRootCAs sets the *x509.CertPool used to verify the cluster's TLS certificate. Use this when the cluster presents a cert chain signed by your org's CA. Composes with the other TLS options.

func WithSession 

func WithSession(ticket, csrfPreventionToken string) Option

WithSession experimental

func WithTimeout added in v0.7.0 

func WithTimeout(d time.Duration) Option

WithTimeout sets the *http.Client.Timeout used for every request. Composes with WithHTTPClient regardless of option order — if the caller passed their own *http.Client, the timeout is applied to it.

The default http.DefaultClient has no timeout. Without this option, a hung PVE node means a hung caller forever; setting at least a generous upper bound is recommended for any non-interactive use.

func WithUserAgent 

func WithUserAgent(ua string) Option

type PCIDevice added in v0.6.0 

type PCIDevice struct {
	Node string `json:"-"`

	ID                  string `json:"id"`
	Class               string `json:"class,omitempty"`
	Vendor              string `json:"vendor,omitempty"`
	VendorName          string `json:"vendor_name,omitempty"`
	Device              string `json:"device,omitempty"`
	DeviceName          string `json:"device_name,omitempty"`
	SubsystemVendor     string `json:"subsystem_vendor,omitempty"`
	SubsystemVendorName string `json:"subsystem_vendor_name,omitempty"`
	SubsystemDevice     string `json:"subsystem_device,omitempty"`
	SubsystemDeviceName string `json:"subsystem_device_name,omitempty"`
	IOMMUGroup          int    `json:"iommugroup,omitempty"`
	MdevCapable         bool   `json:"mdev,omitempty"`
	// contains filtered or unexported fields
}

PCIDevice is one local PCI device, also serves as the handle for the /hardware/pci/{id}/* multi-instance subresources (per AGENTS.md). client and Node are populated by ListPCIDevices and Node.PCIDevice().

func (*PCIDevice) Index added in v0.6.0 

func (d *PCIDevice) Index(ctx context.Context) ([]string, error)

Index enumerates the subresources of the PCI device — currently just ["mdev"].

func (*PCIDevice) Mdev added in v0.6.0 

func (d *PCIDevice) Mdev(ctx context.Context) (types []*PCIMdevType, err error)

Mdev lists the mediated-device types this PCI device supports. Empty result for cards without SR-IOV/mdev capability.

type PCIMdevType added in v0.6.0 

type PCIMdevType struct {
	Type        string `json:"type"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Available   int    `json:"available"`
}

PCIMdevType is one mediated-device type advertised by a PCI device.

type PendingConfigItem added in v0.2.2 

type PendingConfigItem struct {
	Key    string `json:"key,omitempty"`
	Delete *int   `json:"delete,omitempty"`
	// Proxmox API doc says "Pending" & "Value" fields return string but in reality it could be anything
	Pending interface{} `json:"pending,omitempty"`
	Value   interface{} `json:"value,omitempty"`
}

type PendingConfiguration added in v0.2.2 

type PendingConfiguration []PendingConfigItem

type Permission 

type Permission map[string]IntOrBool

type Permissions 

type Permissions map[string]Permission

type PermissionsOptions 

type PermissionsOptions struct {
	Path   string // path to limit the return e.g. / or /nodes
	UserID string // username e.g. root@pam or token
}

type Pool 

type Pool struct {
	PoolID  string            `json:"poolid,omitempty"`
	Comment string            `json:"comment,omitempty"`
	Members []ClusterResource `json:"members,omitempty"`
	// contains filtered or unexported fields
}

func (*Pool) Delete 

func (p *Pool) Delete(ctx context.Context) error

Delete removes the pool via the non-deprecated DELETE /pools endpoint. Use this in preference to DeleteDeprecated.

func (*Pool) DeleteDeprecated deprecated added in v0.6.0 

func (p *Pool) DeleteDeprecated(ctx context.Context) error

DeleteDeprecated removes the pool via the deprecated DELETE /pools/{poolid} endpoint. It does not support nested pools.

Deprecated: use Pool.Delete.

func (*Pool) GetDeprecated deprecated added in v0.6.0 

func (p *Pool) GetDeprecated(ctx context.Context, filters ...string) (*Pool, error)

GetDeprecated reads the pool via the deprecated GET /pools/{poolid} endpoint. It does not support nested pools — prefer Client.Pool, which uses the non-deprecated /pools?poolid= form.

Deprecated: use Client.Pool.

func (*Pool) Update 

func (p *Pool) Update(ctx context.Context, opt *PoolUpdateOption) error

Update modifies the pool via the non-deprecated PUT /pools endpoint (poolid travels in the body alongside the other params). Use this in preference to UpdateDeprecated so nested pools work correctly.

func (*Pool) UpdateDeprecated deprecated added in v0.6.0 

func (p *Pool) UpdateDeprecated(ctx context.Context, opt *PoolUpdateOption) error

UpdateDeprecated writes to the deprecated PUT /pools/{poolid} endpoint. It does not support nested pools.

Deprecated: use Pool.Update.

type PoolUpdateOption 

type PoolUpdateOption struct {
	Comment string `json:"comment,omitempty"`
	// Delete objects rather than adding them
	Delete IntOrBool `json:"delete,omitempty"`
	// AllowMove permits adding a guest that already belongs to another pool;
	// the guest is silently moved instead of the request being rejected.
	AllowMove IntOrBool `json:"allow-move,omitempty"`
	// Comma separated lists of Storage names to add/delete to the pool
	Storage string `json:"storage,omitempty"`
	// Comma separated lists of Virtual Machine IDs to add/delete to the pool
	VirtualMachines string `json:"vms,omitempty"`
}

type Pools 

type Pools []*Pool

type PruneBackupItem added in v0.6.0 

type PruneBackupItem struct {
	Volid string         `json:"volid"`
	Ctime StringOrUint64 `json:"ctime"`
	Mark  string         `json:"mark"`
	Type  string         `json:"type"`
	VMID  uint64         `json:"vmid,omitempty"`
}

PruneBackupItem is one row in the dryrun listing returned by Storage.PreviewPruneBackups. Mark indicates what PruneBackups would do with this volume: "keep", "remove", "protected" (retained by a protection flag), or "renamed" (retained because its name doesn't match the standard scheme).

type QEMUCPUFlag added in v0.6.0 

type QEMUCPUFlag struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	SupportedOn []string `json:"supported-on,omitempty"`
}

QEMUCPUFlag is one VM-visible CPU flag and which cluster nodes support it under the queried acceleration mode.

type QEMUCPUModel added in v0.6.0 

type QEMUCPUModel struct {
	Name     string `json:"name"`
	Vendor   string `json:"vendor"`
	Custom   bool   `json:"custom"`
	Abstract bool   `json:"abstract,omitempty"`
}

QEMUCPUModel is one row of /capabilities/qemu/cpu — both QEMU built-ins and custom CPU models defined on the cluster. Custom models are prefixed "custom-" in Name. Abstract is true for PVE-internal profiles like x86-64-v2/v3/v4 — those don't correspond to a real QEMU CPU type and can't be used as a custom model's reported-model.

type QEMUMachineType added in v0.6.0 

type QEMUMachineType struct {
	ID      string `json:"id"`
	Type    string `json:"type"`
	Version string `json:"version"`
	Changes string `json:"changes,omitempty"`
}

QEMUMachineType is one row of /capabilities/qemu/machines — a q35 or i440fx variant available on this host. Changes is set for +pveX versions.

type QEMUMigrationCapabilities added in v0.6.0 

type QEMUMigrationCapabilities struct {
	HasDbusVMState bool `json:"has-dbus-vmstate"`
}

QEMUMigrationCapabilities reports node-specific live-migration support.

type RRDData 

type RRDData struct {
	Time      uint64
	CPU       float64
	MaxCPU    int
	Mem       float64
	MaxMem    uint64
	Disk      int
	MaxDisk   uint64
	DiskRead  float64
	DiskWrite float64
	NetIn     float64
	NetOut    float64
}

type ReplicationJob added in v0.7.0 

type ReplicationJob struct {
	ID        string           `json:"id"`
	Target    string           `json:"target,omitempty"`
	Type      string           `json:"type,omitempty"`
	Schedule  *string          `json:"schedule,omitempty"`
	Comment   string           `json:"comment,omitempty"`
	Disable   IntOrBool        `json:"disable,omitempty"`
	Rate      *StringOrFloat64 `json:"rate,omitempty"`
	RemoveJob string           `json:"remove_job,omitempty"`
	Source    string           `json:"source,omitempty"`
	Guest     int              `json:"guest,omitempty"`  // PVE adds on read — VMID
	JobNum    int              `json:"jobnum,omitempty"` // PVE adds on read — job number within guest
}

ReplicationJob is one storage replication job (GET /cluster/replication{,/id}). Schedule defaults to "*/15" (every 15 min) — pointer-typed so an unset Schedule omits and PVE keeps the default. Disable has no schema default; IntOrBool with omitempty is sufficient.

type ReplicationJobOptions added in v0.7.0 

type ReplicationJobOptions struct {
	ID        string           `json:"id"`
	Target    string           `json:"target"`
	Type      string           `json:"type"`
	Schedule  *string          `json:"schedule,omitempty"`
	Comment   string           `json:"comment,omitempty"`
	Disable   IntOrBool        `json:"disable,omitempty"`
	Rate      *StringOrFloat64 `json:"rate,omitempty"`
	RemoveJob string           `json:"remove_job,omitempty"`
	Source    string           `json:"source,omitempty"`
}

ReplicationJobOptions mirrors ReplicationJob for POST; Schedule is a pointer for the same reason — see ReplicationJob.

type ReplicationJobUpdateOption added in v0.7.0 

type ReplicationJobUpdateOption struct {
	Delete    string           `json:"delete,omitempty"`
	Digest    string           `json:"digest,omitempty"`
	Schedule  *string          `json:"schedule,omitempty"`
	Comment   string           `json:"comment,omitempty"`
	Disable   IntOrBool        `json:"disable,omitempty"`
	Rate      *StringOrFloat64 `json:"rate,omitempty"`
	RemoveJob string           `json:"remove_job,omitempty"`
	Source    string           `json:"source,omitempty"`
}

ReplicationJobUpdateOption mirrors ReplicationJob for PUT; Schedule pointer per ReplicationJob. Delete unsets fields server-side.

type RetryOption added in v0.7.0 

type RetryOption func(*retryPolicy)

RetryOption configures the retry behaviour set via WithRetry.

func WithRetryBackoff added in v0.7.0 

func WithRetryBackoff(initial, max time.Duration) RetryOption

WithRetryBackoff overrides the exponential backoff bounds. initial is the first backoff window (full-jitter sampled in [0, initial)); the window doubles per attempt and is capped at max. Defaults: 200ms initial, 5s max.

func WithRetryCondition added in v0.7.0 

func WithRetryCondition(fn func(*http.Response, error) bool) RetryOption

WithRetryCondition replaces the predicate that decides whether a response or error should trigger another attempt. The function is called with the result of the inner RoundTripper; exactly one of res / err is non-nil. The default retries on net errors and HTTP 502, 503, 504, 429.

func WithRetryMax added in v0.7.0 

func WithRetryMax(n int) RetryOption

WithRetryMax sets the maximum number of attempts (including the first). Default 3. Values less than 1 are clamped to 1 (no retry).

type Role 

type Role struct {
	RoleID  string    `json:"roleid,omitempty"`
	Privs   string    `json:"privs,omitempty"`
	Special IntOrBool `json:"special,omitempty"`
	// contains filtered or unexported fields
}

func (*Role) Delete 

func (r *Role) Delete(ctx context.Context) error

func (*Role) Update 

func (r *Role) Update(ctx context.Context) error

type Roles 

type Roles []*Role

type RootFS 

type RootFS struct {
	Avail uint64
	Total uint64
	Free  uint64
	Used  uint64
}

type SDNBridgePort added in v0.6.0 

type SDNBridgePort struct {
	Name        string   `json:"name"`
	Index       string   `json:"index,omitempty"`
	PrimaryVLAN float64  `json:"primary_vlan,omitempty"`
	VLANs       []string `json:"vlans,omitempty"`
	VMID        float64  `json:"vmid,omitempty"`
}

SDNBridgePort is one port attached to a SDN bridge — guest-owned ports carry vmid + index (the guest's net{N} slot).

type SDNController added in v0.7.0 

type SDNController struct {
	Controller          string `json:"controller,omitempty"`
	Type                string `json:"type,omitempty"`
	ASN                 uint32 `json:"asn,omitempty"`
	BGPMode             string `json:"bgp-mode,omitempty"`
	BGPMultipathASRelax bool   `json:"bgp-multipath-as-relax,omitempty"`
	EBGP                bool   `json:"ebgp,omitempty"`
	EBGPMultihop        int    `json:"ebgp-multihop,omitempty"`
	ISISDomain          string `json:"isis-domain,omitempty"`
	ISISIfaces          string `json:"isis-ifaces,omitempty"`
	ISISNet             string `json:"isis-net,omitempty"`
	Loopback            string `json:"loopback,omitempty"`
	Node                string `json:"node,omitempty"`
	Nodes               string `json:"nodes,omitempty"`
	PeerGroupName       string `json:"peer-group-name,omitempty"`
	Peers               string `json:"peers,omitempty"`
	State               string `json:"state,omitempty"` // new | changed | deleted
	Digest              string `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNController represents a configured SDN controller (BGP/EVPN/IS-IS/Faucet). PVE returns a union of plugin-type-specific fields; only the keys relevant to Type will be populated.

func (*SDNController) Delete added in v0.7.0 

func (c *SDNController) Delete(ctx context.Context) error

Delete removes the SDN controller.

DELETE /cluster/sdn/controllers/{controller}

func (*SDNController) Read added in v0.7.0 

func (c *SDNController) Read(ctx context.Context) error

Read populates the receiver with the current configuration of the controller.

GET /cluster/sdn/controllers/{controller}

func (*SDNController) Update added in v0.7.0 

func (c *SDNController) Update(ctx context.Context, opts *SDNControllerOptions) error

Update mutates an existing controller. opts.Delete may be a comma-separated list of keys to reset to PVE defaults.

PUT /cluster/sdn/controllers/{controller}

type SDNControllerOptions added in v0.7.0 

type SDNControllerOptions struct {
	Controller              string `json:"controller,omitempty"`
	Type                    string `json:"type,omitempty"`
	ASN                     uint32 `json:"asn,omitempty"`
	BGPMode                 string `json:"bgp-mode,omitempty"`
	BGPMultipathASPathRelax bool   `json:"bgp-multipath-as-path-relax,omitempty"`
	EBGP                    bool   `json:"ebgp,omitempty"`
	EBGPMultihop            int    `json:"ebgp-multihop,omitempty"`
	Fabric                  string `json:"fabric,omitempty"`
	ISISDomain              string `json:"isis-domain,omitempty"`
	ISISIfaces              string `json:"isis-ifaces,omitempty"`
	ISISNet                 string `json:"isis-net,omitempty"`
	Loopback                string `json:"loopback,omitempty"`
	Node                    string `json:"node,omitempty"`
	Nodes                   string `json:"nodes,omitempty"`
	PeerGroupName           string `json:"peer-group-name,omitempty"`
	Peers                   string `json:"peers,omitempty"`
	RouteMapIn              string `json:"route-map-in,omitempty"`
	RouteMapOut             string `json:"route-map-out,omitempty"`
	LockToken               string `json:"lock-token,omitempty"`
	Digest                  string `json:"digest,omitempty"`
	Delete                  string `json:"delete,omitempty"` // PUT only — comma-list of keys to reset
}

SDNControllerOptions is the request body for creating/updating a controller. Fields are documented per the PVE schema; only those relevant to Type are accepted server-side.

type SDNDNS added in v0.7.0 

type SDNDNS struct {
	DNS           string `json:"dns,omitempty"`
	Type          string `json:"type,omitempty"`
	URL           string `json:"url,omitempty"`
	Key           string `json:"key,omitempty"`
	TTL           int    `json:"ttl,omitempty"`
	ReverseMaskV6 int    `json:"reversemaskv6,omitempty"`
	ReverseV6Mask int    `json:"reversev6mask,omitempty"`
	Fingerprint   string `json:"fingerprint,omitempty"`
	Digest        string `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNDNS represents an SDN DNS plugin configuration (currently PowerDNS only).

func (*SDNDNS) Delete added in v0.7.0 

func (d *SDNDNS) Delete(ctx context.Context) error

Delete removes the SDN DNS plugin.

DELETE /cluster/sdn/dns/{dns}

func (*SDNDNS) Read added in v0.7.0 

func (d *SDNDNS) Read(ctx context.Context) error

Read populates the receiver with the current configuration.

GET /cluster/sdn/dns/{dns}

func (*SDNDNS) Update added in v0.7.0 

func (d *SDNDNS) Update(ctx context.Context, opts *SDNDNSOptions) error

Update mutates an existing SDN DNS plugin configuration.

PUT /cluster/sdn/dns/{dns}

type SDNDNSOptions added in v0.7.0 

type SDNDNSOptions struct {
	DNS           string `json:"dns,omitempty"`
	Type          string `json:"type,omitempty"` // "powerdns"
	URL           string `json:"url,omitempty"`
	Key           string `json:"key,omitempty"`
	TTL           int    `json:"ttl,omitempty"`
	ReverseMaskV6 int    `json:"reversemaskv6,omitempty"`
	ReverseV6Mask int    `json:"reversev6mask,omitempty"`
	Fingerprint   string `json:"fingerprint,omitempty"`
	LockToken     string `json:"lock-token,omitempty"`
	Digest        string `json:"digest,omitempty"`
	Delete        string `json:"delete,omitempty"`
}

SDNDNSOptions is the request body for creating/updating an SDN DNS object.

type SDNDryRun added in v0.7.0 

type SDNDryRun struct {
	FRRDiff        string `json:"frr-diff,omitempty"`
	InterfacesDiff string `json:"interfaces-diff,omitempty"`
}

SDNDryRun is the diff returned by GET /cluster/sdn/dry-run?node=<node>: it shows what changes a SDNApply would push to the node's FRR and ifupdown configuration without actually applying them.

type SDNFabric added in v0.7.0 

type SDNFabric struct {
	ID                  string   `json:"id,omitempty"`
	Protocol            string   `json:"protocol,omitempty"` // openfabric | ospf | wireguard | bgp
	IPPrefix            string   `json:"ip_prefix,omitempty"`
	IP6Prefix           string   `json:"ip6_prefix,omitempty"`
	Area                string   `json:"area,omitempty"`                 // ospf
	HelloInterval       float64  `json:"hello_interval,omitempty"`       // openfabric
	CSNPInterval        float64  `json:"csnp_interval,omitempty"`        // openfabric
	PersistentKeepalive int      `json:"persistent_keepalive,omitempty"` // wireguard
	Redistribute        []string `json:"redistribute,omitempty"`         // ospf | bgp
	RouteFilter         string   `json:"route_filter,omitempty"`         // ospf | openfabric
	Digest              string   `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNFabric represents an SDN fabric (underlay routing protocol configuration). The schema is plugin-type-tagged on Protocol; many fields are protocol-specific.

func (*SDNFabric) AddNode added in v0.7.0 

func (f *SDNFabric) AddNode(ctx context.Context, opts *SDNFabricNodeOptions) error

AddNode adds a node to this fabric. opts.NodeID is required.

POST /cluster/sdn/fabrics/node/{fabric_id}

func (*SDNFabric) Delete added in v0.7.0 

func (f *SDNFabric) Delete(ctx context.Context) error

Delete removes the fabric.

DELETE /cluster/sdn/fabrics/fabric/{id}

func (*SDNFabric) Node added in v0.7.0 

func (f *SDNFabric) Node(nodeID string) *SDNFabricNode

Node returns a handle for a single node in this fabric. No API call is made.

GET /cluster/sdn/fabrics/node/{fabric_id}/{node_id}

func (*SDNFabric) Nodes added in v0.7.0 

func (f *SDNFabric) Nodes(ctx context.Context) (nodes []*SDNFabricNode, err error)

Nodes lists nodes participating in this fabric.

GET /cluster/sdn/fabrics/node/{fabric_id}

func (*SDNFabric) Read added in v0.7.0 

func (f *SDNFabric) Read(ctx context.Context) error

Read populates the receiver with the current fabric configuration.

GET /cluster/sdn/fabrics/fabric/{id}

func (*SDNFabric) Update added in v0.7.0 

func (f *SDNFabric) Update(ctx context.Context, opts *SDNFabricOptions) error

Update mutates a fabric configuration.

PUT /cluster/sdn/fabrics/fabric/{id}

type SDNFabricInterface added in v0.6.0 

type SDNFabricInterface struct {
	Name  string `json:"name"`
	State string `json:"state,omitempty"`
	Type  string `json:"type,omitempty"`
}

SDNFabricInterface is one interface participating in a fabric.

type SDNFabricNeighbor added in v0.6.0 

type SDNFabricNeighbor struct {
	Neighbor string `json:"neighbor"`
	Status   string `json:"status,omitempty"`
	Uptime   string `json:"uptime,omitempty"` // FRR duration string (e.g. "8h24m12s")
}

SDNFabricNeighbor is one FRR neighbor entry for a fabric.

type SDNFabricNode added in v0.7.0 

type SDNFabricNode struct {
	FabricID   string   `json:"fabric_id,omitempty"`
	NodeID     string   `json:"node_id,omitempty"`
	IP         string   `json:"ip,omitempty"`
	IP6        string   `json:"ip6,omitempty"`
	Interfaces []string `json:"interfaces,omitempty"`
	AllowedIPs []string `json:"allowed_ips,omitempty"` // wireguard
	Endpoint   string   `json:"endpoint,omitempty"`    // wireguard
	Peers      []string `json:"peers,omitempty"`       // wireguard
	Digest     string   `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNFabricNode represents a node participating in an SDN fabric, including its protocol-specific interfaces and (for WireGuard) peers.

func (*SDNFabricNode) Delete added in v0.7.0 

func (n *SDNFabricNode) Delete(ctx context.Context) error

Delete removes the node from the fabric.

DELETE /cluster/sdn/fabrics/node/{fabric_id}/{node_id}

func (*SDNFabricNode) Read added in v0.7.0 

func (n *SDNFabricNode) Read(ctx context.Context) error

Read populates the receiver with the current fabric-node configuration.

GET /cluster/sdn/fabrics/node/{fabric_id}/{node_id}

func (*SDNFabricNode) Update added in v0.7.0 

func (n *SDNFabricNode) Update(ctx context.Context, opts *SDNFabricNodeOptions) error

Update mutates a fabric-node configuration.

PUT /cluster/sdn/fabrics/node/{fabric_id}/{node_id}

type SDNFabricNodeOptions added in v0.7.0 

type SDNFabricNodeOptions struct {
	FabricID   string   `json:"fabric_id,omitempty"`
	NodeID     string   `json:"node_id,omitempty"`
	IP         string   `json:"ip,omitempty"`
	IP6        string   `json:"ip6,omitempty"`
	Interfaces []string `json:"interfaces,omitempty"`
	AllowedIPs []string `json:"allowed_ips,omitempty"`
	Endpoint   string   `json:"endpoint,omitempty"`
	Peers      []string `json:"peers,omitempty"`
	LockToken  string   `json:"lock-token,omitempty"`
	Digest     string   `json:"digest,omitempty"`
	Delete     []string `json:"delete,omitempty"`
}

SDNFabricNodeOptions is the request body for adding/updating a fabric node.

type SDNFabricOptions added in v0.7.0 

type SDNFabricOptions struct {
	ID                  string   `json:"id,omitempty"`
	Protocol            string   `json:"protocol,omitempty"`
	IPPrefix            string   `json:"ip_prefix,omitempty"`
	IP6Prefix           string   `json:"ip6_prefix,omitempty"`
	Area                string   `json:"area,omitempty"`
	HelloInterval       float64  `json:"hello_interval,omitempty"`
	CSNPInterval        float64  `json:"csnp_interval,omitempty"`
	PersistentKeepalive int      `json:"persistent_keepalive,omitempty"`
	Redistribute        []string `json:"redistribute,omitempty"`
	RouteFilter         string   `json:"route_filter,omitempty"`
	LockToken           string   `json:"lock-token,omitempty"`
	Digest              string   `json:"digest,omitempty"`
	Delete              []string `json:"delete,omitempty"`
}

SDNFabricOptions is the request body for creating/updating a fabric.

type SDNFabricRoute added in v0.6.0 

type SDNFabricRoute struct {
	Route string   `json:"route"`
	Via   []string `json:"via,omitempty"`
}

SDNFabricRoute is one route entry for a fabric.

type SDNFabricsAll added in v0.7.0 

type SDNFabricsAll struct {
	Fabrics []*SDNFabric     `json:"fabrics,omitempty"`
	Nodes   []*SDNFabricNode `json:"nodes,omitempty"`
}

SDNFabricsAll is the combined fabric+node listing returned by GET /cluster/sdn/fabrics/all.

type SDNIPAM added in v0.7.0 

type SDNIPAM struct {
	IPAM        string `json:"ipam,omitempty"`
	Type        string `json:"type,omitempty"`
	URL         string `json:"url,omitempty"`
	Token       string `json:"token,omitempty"`
	Section     int    `json:"section,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`
	Digest      string `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNIPAM represents an IPAM (IP Address Management) backend configuration. PVE supports netbox, phpipam, and pve (built-in) backends.

func (*SDNIPAM) Delete added in v0.7.0 

func (i *SDNIPAM) Delete(ctx context.Context) error

Delete removes the IPAM backend.

DELETE /cluster/sdn/ipams/{ipam}

func (*SDNIPAM) Read added in v0.7.0 

func (i *SDNIPAM) Read(ctx context.Context) error

Read populates the receiver with the current configuration.

GET /cluster/sdn/ipams/{ipam}

func (*SDNIPAM) Status added in v0.7.0 

func (i *SDNIPAM) Status(ctx context.Context) (entries []map[string]any, err error)

Status returns the list of IP entries from this IPAM. The shape of each entry is plugin-specific so it's returned as a free-form slice of maps; use the typed IPAM struct (cluster/sdn types) for known fields.

GET /cluster/sdn/ipams/{ipam}/status

func (*SDNIPAM) Update added in v0.7.0 

func (i *SDNIPAM) Update(ctx context.Context, opts *SDNIPAMOptions) error

Update mutates an existing IPAM backend configuration.

PUT /cluster/sdn/ipams/{ipam}

type SDNIPAMOptions added in v0.7.0 

type SDNIPAMOptions struct {
	IPAM        string `json:"ipam,omitempty"`
	Type        string `json:"type,omitempty"` // "netbox" | "phpipam" | "pve"
	URL         string `json:"url,omitempty"`
	Token       string `json:"token,omitempty"`
	Section     int    `json:"section,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`
	LockToken   string `json:"lock-token,omitempty"`
	Digest      string `json:"digest,omitempty"`
	Delete      string `json:"delete,omitempty"`
}

SDNIPAMOptions is the request body for creating/updating an SDN IPAM.

type SDNIPVRFEntry added in v0.6.0 

type SDNIPVRFEntry struct {
	IP       string   `json:"ip"`
	Metric   int      `json:"metric,omitempty"`
	Nexthops []string `json:"nexthops,omitempty"`
	Protocol string   `json:"protocol,omitempty"`
}

SDNIPVRFEntry is one route in an EVPN zone's IP VRF table.

type SDNLockToken added in v0.7.0 

type SDNLockToken string

SDNLockToken is the opaque token returned by acquiring the SDN config lock (POST /cluster/sdn/lock). Pass it to mutating endpoints via their LockToken option and to Release/Rollback to surrender the lock.

type SDNMACVRFEntry added in v0.6.0 

type SDNMACVRFEntry struct {
	IP      string `json:"ip,omitempty"`
	MAC     string `json:"mac,omitempty"`
	NextHop string `json:"nexthop,omitempty"`
}

SDNMACVRFEntry is one entry in an EVPN VNet's MAC VRF.

type SDNPrefixList added in v0.7.0 

type SDNPrefixList struct {
	ID      string                `json:"id,omitempty"`
	Entries []*SDNPrefixListEntry `json:"entries,omitempty"`
	Digest  string                `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNPrefixList represents a named SDN prefix list. List GETs return only the id; the detail GET returns the full entries array.

func (*SDNPrefixList) AddEntry added in v0.7.0 

func (l *SDNPrefixList) AddEntry(ctx context.Context, opts *SDNPrefixListEntryOptions) error

AddEntry creates a new entry in this prefix-list. opts.Action and opts.Prefix are required.

POST /cluster/sdn/prefix-lists/{id}/entries

func (*SDNPrefixList) Delete added in v0.7.0 

func (l *SDNPrefixList) Delete(ctx context.Context) error

Delete removes the prefix-list.

DELETE /cluster/sdn/prefix-lists/{id}

func (*SDNPrefixList) Entry added in v0.7.0 

func (l *SDNPrefixList) Entry(seq uint32) *SDNPrefixListEntry

Entry returns a handle for a single entry in this prefix-list keyed by seq. No API call is made.

GET /cluster/sdn/prefix-lists/{id}/entries/{url_seq}

func (*SDNPrefixList) ListEntries added in v0.7.0 

func (l *SDNPrefixList) ListEntries(ctx context.Context) (entries []*SDNPrefixListEntry, err error)

ListEntries lists the entries within this prefix-list.

GET /cluster/sdn/prefix-lists/{id}/entries

func (*SDNPrefixList) Read added in v0.7.0 

func (l *SDNPrefixList) Read(ctx context.Context) error

Read populates the receiver with the prefix-list configuration including entries.

GET /cluster/sdn/prefix-lists/{id}

func (*SDNPrefixList) Update added in v0.7.0 

func (l *SDNPrefixList) Update(ctx context.Context, opts *SDNPrefixListOptions) error

Update mutates the prefix-list. Pass a fresh Entries slice to replace the current set.

PUT /cluster/sdn/prefix-lists/{id}

type SDNPrefixListEntry added in v0.7.0 

type SDNPrefixListEntry struct {
	ID     string `json:"-"` // parent prefix-list id (path-only)
	Seq    uint32 `json:"seq,omitempty"`
	Action string `json:"action,omitempty"` // permit | deny
	Prefix string `json:"prefix,omitempty"`
	GE     int    `json:"ge,omitempty"`
	LE     int    `json:"le,omitempty"`
	Digest string `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNPrefixListEntry is one rule inside a prefix-list.

func (*SDNPrefixListEntry) Delete added in v0.7.0 

func (e *SDNPrefixListEntry) Delete(ctx context.Context) error

Delete removes the prefix-list entry.

DELETE /cluster/sdn/prefix-lists/{id}/entries/{url_seq}

func (*SDNPrefixListEntry) Read added in v0.7.0 

func (e *SDNPrefixListEntry) Read(ctx context.Context) error

Read populates the receiver with the entry configuration.

GET /cluster/sdn/prefix-lists/{id}/entries/{url_seq}

func (*SDNPrefixListEntry) Update added in v0.7.0 

func (e *SDNPrefixListEntry) Update(ctx context.Context, opts *SDNPrefixListEntryOptions) error

Update mutates the prefix-list entry.

PUT /cluster/sdn/prefix-lists/{id}/entries/{url_seq}

type SDNPrefixListEntryOptions added in v0.7.0 

type SDNPrefixListEntryOptions struct {
	Seq       uint32   `json:"seq,omitempty"`
	Action    string   `json:"action,omitempty"`
	Prefix    string   `json:"prefix,omitempty"`
	GE        int      `json:"ge,omitempty"`
	LE        int      `json:"le,omitempty"`
	LockToken string   `json:"lock-token,omitempty"`
	Digest    string   `json:"digest,omitempty"`
	Delete    []string `json:"delete,omitempty"`
}

SDNPrefixListEntryOptions is the request body for creating/updating one entry in a prefix-list.

type SDNPrefixListOptions added in v0.7.0 

type SDNPrefixListOptions struct {
	ID        string                `json:"id,omitempty"`
	Entries   []*SDNPrefixListEntry `json:"entries,omitempty"`
	LockToken string                `json:"lock-token,omitempty"`
	Digest    string                `json:"digest,omitempty"`
	Delete    []string              `json:"delete,omitempty"`
}

SDNPrefixListOptions is the request body for creating/updating a prefix-list.

type SDNRouteMapEntry added in v0.7.0 

type SDNRouteMapEntry struct {
	RouteMapID string   `json:"route-map-id,omitempty"`
	Order      uint16   `json:"order,omitempty"`
	Action     string   `json:"action,omitempty"` // permit | deny
	Match      []string `json:"match,omitempty"`
	Set        []string `json:"set,omitempty"`
	Call       string   `json:"call,omitempty"`
	ExitAction string   `json:"exit-action,omitempty"`
	Digest     string   `json:"digest,omitempty"`
	// contains filtered or unexported fields
}

SDNRouteMapEntry is one ordered entry in a named route-map. The PVE schema encodes match/set as arrays of pve-property-string formatted "key=...,value=..." so the wire form is `[]string`.

func (*SDNRouteMapEntry) Delete added in v0.7.0 

func (e *SDNRouteMapEntry) Delete(ctx context.Context) error

Delete removes the route-map entry.

DELETE /cluster/sdn/route-maps/entries/{route-map-id}/entry/{order}

func (*SDNRouteMapEntry) Read added in v0.7.0 

func (e *SDNRouteMapEntry) Read(ctx context.Context) error

Read populates the receiver with the route-map entry configuration.

GET /cluster/sdn/route-maps/entries/{route-map-id}/entry/{order}

func (*SDNRouteMapEntry) Update added in v0.7.0 

func (e *SDNRouteMapEntry) Update(ctx context.Context, opts *SDNRouteMapEntryOptions) error

Update mutates the route-map entry.

PUT /cluster/sdn/route-maps/entries/{route-map-id}/entry/{order}

type SDNRouteMapEntryOptions added in v0.7.0 

type SDNRouteMapEntryOptions struct {
	RouteMapID string   `json:"route-map-id,omitempty"`
	Order      uint16   `json:"order,omitempty"`
	Action     string   `json:"action,omitempty"`
	Match      []string `json:"match,omitempty"`
	Set        []string `json:"set,omitempty"`
	Call       string   `json:"call,omitempty"`
	ExitAction string   `json:"exit-action,omitempty"`
	LockToken  string   `json:"lock-token,omitempty"`
	Digest     string   `json:"digest,omitempty"`
	Delete     []string `json:"delete,omitempty"`
}

SDNRouteMapEntryOptions is the request body for creating/updating a route-map entry.

type SDNRouteMapID added in v0.7.0 

type SDNRouteMapID struct {
	ID string `json:"id,omitempty"`
}

SDNRouteMapID is the listing entry under /cluster/sdn/route-maps.

type SDNSubnetOptions added in v0.7.0 

type SDNSubnetOptions struct {
	Subnet        string    `json:"subnet,omitempty"`
	Type          string    `json:"type,omitempty"` // "subnet" — only valid value on POST
	VNet          string    `json:"vnet,omitempty"`
	Gateway       string    `json:"gateway,omitempty"`
	DHCPDNSServer string    `json:"dhcp-dns-server,omitempty"`
	DHCPRange     []string  `json:"dhcp-range,omitempty"`
	DNSZonePrefix string    `json:"dnszoneprefix,omitempty"`
	SNAT          IntOrBool `json:"snat,omitempty"`
	LockToken     string    `json:"lock-token,omitempty"`
	Digest        string    `json:"digest,omitempty"`
	Delete        string    `json:"delete,omitempty"`
}

SDNSubnetOptions is the create/update body for an SDN subnet under a VNet.

type SDNVNetFirewallOptions added in v0.7.0 

type SDNVNetFirewallOptions struct {
	Enable          IntOrBool `json:"enable,omitempty"`
	PolicyForward   string    `json:"policy_forward,omitempty"` // ACCEPT | DROP
	LogLevelForward string    `json:"log_level_forward,omitempty"`
	Digest          string    `json:"digest,omitempty"`
}

SDNVNetFirewallOptions represents the per-VNet firewall toggles returned by GET /cluster/sdn/vnets/{vnet}/firewall/options.

Enable: PVE schema marks the type as boolean but the default is `0`. Go's zero value (false) matches the default, so plain bool with omitempty is safe and the wire form stays `0`/`1` thanks to IntOrBool.

type SDNVNetFirewallOptionsUpdate added in v0.7.0 

type SDNVNetFirewallOptionsUpdate struct {
	Enable          *IntOrBool `json:"enable,omitempty"`
	PolicyForward   string     `json:"policy_forward,omitempty"`
	LogLevelForward string     `json:"log_level_forward,omitempty"`
	Digest          string     `json:"digest,omitempty"`
	Delete          string     `json:"delete,omitempty"`
}

SDNVNetFirewallOptionsUpdate is the PUT body for vnet firewall options.

type SDNVNetFirewallRule added in v0.7.0 

type SDNVNetFirewallRule struct {
	Pos       int    `json:"pos,omitempty"`
	Type      string `json:"type,omitempty"` // in | out | forward | group
	Action    string `json:"action,omitempty"`
	Enable    int    `json:"enable,omitempty"`
	Comment   string `json:"comment,omitempty"`
	Source    string `json:"source,omitempty"`
	Dest      string `json:"dest,omitempty"`
	Proto     string `json:"proto,omitempty"`
	SPort     string `json:"sport,omitempty"`
	DPort     string `json:"dport,omitempty"`
	IFace     string `json:"iface,omitempty"`
	Log       string `json:"log,omitempty"`
	Macro     string `json:"macro,omitempty"`
	IPVersion int    `json:"ipversion,omitempty"`
	ICMPType  string `json:"icmp-type,omitempty"`
}

SDNVNetFirewallRule is one firewall rule on a VNet. Mirrors the cluster firewall rule shape but scoped to a single VNet.

type SDNVNetFirewallRuleOptions added in v0.7.0 

type SDNVNetFirewallRuleOptions struct {
	Pos      int    `json:"pos,omitempty"`
	Type     string `json:"type,omitempty"`
	Action   string `json:"action,omitempty"`
	Enable   int    `json:"enable,omitempty"`
	Comment  string `json:"comment,omitempty"`
	Source   string `json:"source,omitempty"`
	Dest     string `json:"dest,omitempty"`
	Proto    string `json:"proto,omitempty"`
	SPort    string `json:"sport,omitempty"`
	DPort    string `json:"dport,omitempty"`
	IFace    string `json:"iface,omitempty"`
	Log      string `json:"log,omitempty"`
	Macro    string `json:"macro,omitempty"`
	ICMPType string `json:"icmp-type,omitempty"`
	MoveTo   int    `json:"moveto,omitempty"`
	Digest   string `json:"digest,omitempty"`
	Delete   string `json:"delete,omitempty"`
}

SDNVNetFirewallRuleOptions is the create/update body for VNet firewall rules.

type SDNVNetIPOptions added in v0.7.0 

type SDNVNetIPOptions struct {
	Zone string `json:"zone,omitempty"`
	IP   string `json:"ip,omitempty"`
	MAC  string `json:"mac,omitempty"`
	VMID int    `json:"vmid,omitempty"` // PUT only
}

SDNVNetIPOptions is the request body for POST/PUT/DELETE /cluster/sdn/vnets/ {vnet}/ips. The endpoint manages MAC/IP/VMID mappings inside the configured IPAM for a VNet.

type SDNZone added in v0.2.3 

type SDNZone struct {
	Name       string `json:"zone"`
	Type       string `json:"type"`
	DHCP       string `json:"dhcp,omitempty"`
	DNS        string `json:"dns,omitempty"`
	DNSZone    string `json:"dnszone,omitempty"`
	IPAM       string `json:"ipam,omitempty"`
	MTU        int    `json:"mtu,omitempty"`
	Nodes      CSV    `json:"nodes,omitempty"`
	Peers      CSV    `json:"peers,omitempty"`
	Pending    bool   `json:"pending,omitempty"`
	ReverseDNS string `json:"reversedns,omitempty"`
	State      string `json:"state,omitempty"`
}

type SDNZoneBridge added in v0.6.0 

type SDNZoneBridge struct {
	Name          string           `json:"name"`
	Ports         []*SDNBridgePort `json:"ports,omitempty"`
	VLANFiltering string           `json:"vlan_filtering,omitempty"`
}

SDNZoneBridge is one bridge (vnet) deployed in the zone, with its member ports. VLAN-aware bridges carry primary_vlan + vlans on each port.

type SDNZoneContent added in v0.6.0 

type SDNZoneContent struct {
	VNet      string `json:"vnet"`
	Status    string `json:"status,omitempty"`
	StatusMsg string `json:"statusmsg,omitempty"`
}

SDNZoneContent is one VNet's status within a zone, per node.

type SDNZoneOptions added in v0.2.3 

type SDNZoneOptions struct {
	Name                     string    `json:"zone"`
	Type                     string    `json:"type"`
	AdvertiseSubnets         IntOrBool `json:"advertise-subnets,omitempty"`
	Bridge                   string    `json:"bridge,omitempty"`
	BridgeDisableMACLearning IntOrBool `json:"bridge-disable-mac-learning,omitempty"`
	Controller               string    `json:"controller,omitempty"`
	DHCP                     string    `json:"dhcp,omitempty"`
	DisableARPNDSuppression  IntOrBool `json:"disable-arp-nd-suppression,omitempty"`
	DNS                      string    `json:"dns,omitempty"`
	DNSZone                  string    `json:"dnszone,omitempty"`
	DPID                     int       `json:"dpid,omitempty"`
	ExitNodes                string    `json:"exit-nodes,omitempty"`
	ExitNodesLocalRouting    bool      `json:"exit-nodes-local-routing,omitempty"`
	ExitNodesPrimary         string    `json:"exit-nodes-primary,omitempty"`
	Fabric                   string    `json:"fabric,omitempty"`
	IPAM                     string    `json:"ipam,omitempty"`
	MAC                      string    `json:"mac,omitempty"`
	MTU                      int       `json:"mtu,omitempty"`
	Nodes                    string    `json:"nodes,omitempty"`
	Peers                    string    `json:"peers,omitempty"`
	ReverseDNS               string    `json:"reversedns,omitempty"`
	RTImport                 string    `json:"rt-import,omitempty"`
	Tag                      uint      `json:"tag,omitempty"`
	// VLANProtocol — PVE default "802.1q". An empty-string override would
	// drop 802.1ad zones; pointer keeps the server default. See #199.
	VLANProtocol *string `json:"vlan-protocol,omitempty"`
	VRFVXLAN     int     `json:"vrf-vxlan,omitempty"`
	// VXLANPort — PVE default 4789 (IANA-assigned VXLAN UDP port). A
	// uint16 zero would attempt to bind port 0; pointer keeps the default
	// when nil. See #199.
	VXLANPort *uint16 `json:"vxlan-port,omitempty"`
}

type SDNZoneStatus added in v0.6.0 

type SDNZoneStatus struct {
	Zone   string `json:"zone"`
	Status string `json:"status,omitempty"` // available | pending | error
}

SDNZoneStatus is one entry of the per-node SDN zone status index — distinct from the cluster-level SDNZone config object.

type ScanCIFSOptions added in v0.6.0 

type ScanCIFSOptions struct {
	Server   string `url:"server"`
	Username string `url:"username,omitempty"`
	Password string `url:"password,omitempty"`
	Domain   string `url:"domain,omitempty"`
}

ScanCIFSOptions is the query payload for ScanCIFS. Server is required; username/password/domain are needed only for non-anonymous shares.

type ScanCIFSShare added in v0.6.0 

type ScanCIFSShare struct {
	Share       string `json:"share"`
	Description string `json:"description,omitempty"`
}

ScanCIFSShare is one share advertised by a remote SMB/CIFS server.

type ScanISCSITarget added in v0.6.0 

type ScanISCSITarget struct {
	Target string `json:"target"`
	Portal string `json:"portal,omitempty"`
}

ScanISCSITarget is one iSCSI target advertised by a portal.

type ScanLVMThinPool added in v0.6.0 

type ScanLVMThinPool struct {
	LV string `json:"lv"`
}

ScanLVMThinPool is one thin pool inside an LVM volume group.

type ScanLVMVG added in v0.6.0 

type ScanLVMVG struct {
	VG string `json:"vg"`
}

ScanLVMVG is one entry from the local LVM volume-group probe.

type ScanNFSExport added in v0.6.0 

type ScanNFSExport struct {
	Path    string `json:"path"`
	Options string `json:"options,omitempty"`
}

ScanNFSExport is one export advertised by a remote NFS server.

type ScanPBSOptions added in v0.6.0 

type ScanPBSOptions struct {
	Server      string
	Username    string
	Password    string
	Fingerprint string
	Port        int
}

ScanPBSOptions is the query payload for ScanPBS. Server, Username, and Password are required; Fingerprint is needed when PBS uses a self-signed cert; Port defaults to 8007 server-side.

type ScanPBSStore added in v0.6.0 

type ScanPBSStore struct {
	Store   string `json:"store"`
	Comment string `json:"comment,omitempty"`
}

ScanPBSStore is one datastore on a remote Proxmox Backup Server.

type ScanZFSPool added in v0.6.0 

type ScanZFSPool struct {
	Pool string `json:"pool"`
}

ScanZFSPool is one entry from the local ZFS pool probe.

type Separator 

type Separator = string

type Session 

type Session struct {
	Username            string `json:"username"`
	CSRFPreventionToken string `json:"CSRFPreventionToken,omitempty"`

	// Cap is being returned but not documented in the API docs, likely will get rewritten later with better types
	Cap         map[string]map[string]int `json:"cap,omitempty"`
	ClusterName string                    `json:"clustername,omitempty"`
	Ticket      string                    `json:"ticket,omitempty"`
}

type SpiceProxy added in v0.6.0 

type SpiceProxy struct {
	Type             string `json:"type"`
	Host             string `json:"host"`
	Port             string `json:"port,omitempty"`
	Password         string `json:"password,omitempty"`
	Proxy            string `json:"proxy,omitempty"`
	Title            string `json:"title,omitempty"`
	TLSPort          string `json:"tls-port,omitempty"`
	CA               string `json:"ca,omitempty"`
	HostSubject      string `json:"host-subject,omitempty"`
	DeleteThisFile   string `json:"delete-this-file,omitempty"`
	SecureAttention  string `json:"secure-attention,omitempty"`
	ReleaseCursor    string `json:"release-cursor,omitempty"`
	ToggleFullscreen string `json:"toggle-fullscreen,omitempty"`
}

SpiceProxy carries the SPICE connection info returned by /spiceproxy. The field names match the keys remote-viewer expects in its .vv config.

type Storage 

type Storage struct {
	Node         string
	Name         string `json:"storage"`
	Enabled      int
	UsedFraction float64 `json:"used_fraction"`
	Active       int
	Content      string
	Shared       int
	Avail        uint64
	Type         string
	Used         uint64
	Total        uint64
	Storage      string `json:"-"` // Deprecated: Use Name instead. Excluded from JSON to prevent marshal/unmarshal issues.
	// contains filtered or unexported fields
}

func (*Storage) AllocContent added in v0.6.0 

func (s *Storage) AllocContent(ctx context.Context, opts *StorageContentAllocOptions) (volid string, err error)

AllocContent creates a new image volume on the storage. Returns the new volid (e.g. "local-lvm:vm-100-disk-1"). Synchronous — most LVM/ZFS-backed allocations finish quickly enough that PVE returns the volid directly.

func (*Storage) Backup 

func (s *Storage) Backup(ctx context.Context, name string) (backup *Backup, err error)

func (*Storage) CopyContent added in v0.6.0 

func (s *Storage) CopyContent(ctx context.Context, sourceVolume, targetVolume, targetNode string) (*Task, error)

CopyContent clones a source volume to a target volid, optionally on a different node. Returns a Task — copying multi-GB images takes a while.

func (*Storage) DeleteContent 

func (s *Storage) DeleteContent(ctx context.Context, content string) (*Task, error)

func (*Storage) DownloadURL 

func (s *Storage) DownloadURL(ctx context.Context, content, filename, url string) (*Task, error)

func (*Storage) DownloadURLWithHash 

func (s *Storage) DownloadURLWithHash(ctx context.Context, content, filename, url string, checksum, checksumAlgorithm string) (*Task, error)

func (*Storage) FileRestoreList added in v0.6.0 

func (s *Storage) FileRestoreList(ctx context.Context, volume, filepath string) (entries []*StorageFileRestoreEntry, err error)

FileRestoreList lists entries inside a PBS-backed backup volume at the given filesystem path. Pass filepath="/" for the root. PVE only supports this on PBS storages.

func (*Storage) GetContent 

func (s *Storage) GetContent(ctx context.Context) (content []*StorageContent, err error)

func (*Storage) ISO 

func (s *Storage) ISO(ctx context.Context, name string) (iso *ISO, err error)

func (*Storage) Identity added in v0.6.0 

func (s *Storage) Identity(ctx context.Context) (id *StorageIdentity, err error)

Identity returns the storage's stable id + plugin type. PBS storages surface a content-addressed datastore id here for namespace tracking; other plugins typically return the storage name as the id.

func (*Storage) Import added in v0.3.2 

func (s *Storage) Import(ctx context.Context, name string) (imp *Import, err error)

func (*Storage) ImportMetadata added in v0.6.0 

func (s *Storage) ImportMetadata(ctx context.Context, volume string) (*ImportMetadata, error)

ImportMetadata fetches the metadata Proxmox extracts from an importable guest volume — currently ESXi-sourced VM disks on an "import"-capable storage. Use this as a pre-flight before constructing a VM with the "import-from=" disk option to see the disks/network mapping PVE detected and any warnings about unsupported fields.

volume is the standard PVE volume identifier, e.g. "esxi-store:ha-datacenter/MyVM/MyVM.vmx".

func (*Storage) OCIRegistryPull added in v0.6.0 

func (s *Storage) OCIRegistryPull(ctx context.Context, reference, filename string) (*Task, error)

OCIRegistryPull downloads an OCI image from a registry into the storage. reference is the OCI image ref (e.g. "docker.io/library/alpine:latest"). filename is optional — PVE will derive one from the reference when unset. Returns a Task.

func (*Storage) PreviewPruneBackups added in v0.6.0 

func (s *Storage) PreviewPruneBackups(ctx context.Context, opts *StoragePruneBackupsOptions) ([]*PruneBackupItem, error)

PreviewPruneBackups returns the list of backup volumes the prune call would keep, remove, retain by protection flag, or skip due to non-standard naming. Pass nil opts to use the storage's configured retention spec across every guest. This is a dryrun — nothing on disk changes.

func (*Storage) PruneBackups added in v0.6.0 

func (s *Storage) PruneBackups(ctx context.Context, opts *StoragePruneBackupsOptions) (*Task, error)

PruneBackups deletes the backup volumes a PreviewPruneBackups call with the same opts would mark "remove". Returns the task so callers can Wait on it. Note that backups added/removed between preview and prune may shift which volumes get deleted; the preview is informational, not a transaction.

func (*Storage) RRD added in v0.6.0 

func (s *Storage) RRD(ctx context.Context, ds string, timeframe Timeframe, cf ConsolidationFunction) (rrd *NodeRRDImage, err error)

RRD asks PVE to render a storage-utilization PNG and returns its on-disk filename. ds is a comma-separated list of datasources ("total,used"); timeframe is hour/day/week/month/year (no decade for storage).

func (*Storage) RRDData added in v0.6.0 

func (s *Storage) RRDData(ctx context.Context, timeframe Timeframe, cf ConsolidationFunction) (data []*RRDData, err error)

RRDData returns the storage's historical IO/usage timeseries. timeframe is one of hour/day/week/month/year; cf is the consolidation function (AVERAGE | MAX) — empty defaults to AVERAGE server-side.

func (*Storage) Status added in v0.7.0 

func (s *Storage) Status(ctx context.Context) (status *StorageStatus, err error)

Status returns the storage's status / capability object from GET /nodes/{node}/storage/{storage}. Despite living at the directory-index path, PVE publishes the storage's status payload here (Active, Content types, Type, Enabled, capacity counters), not the usual `[{"subdir":...}]` envelope — see StorageStatus.

func (*Storage) UnmarshalJSON added in v0.4.0 

func (s *Storage) UnmarshalJSON(b []byte) error

UnmarshalJSON implements custom unmarshaling for Storage to handle large values that may be returned as floats in scientific notation (e.g., values > 1PB)

func (*Storage) UpdateContent added in v0.6.0 

func (s *Storage) UpdateContent(ctx context.Context, volume string, opts *StorageContentUpdateOptions) error

UpdateContent mutates a volume's metadata (currently: notes + protected flag on backups). Pass volume as the full PVE volid (e.g. "local:backup/vzdump-qemu-100-2026_01_01-12_00_00.vma.zst").

func (*Storage) Upload 

func (s *Storage) Upload(content, file string) (*Task, error)

func (*Storage) UploadString added in v0.6.0 

func (s *Storage) UploadString(content, storageFilename, contents string) (*Task, error)

UploadString uploads contents directly as a file with the given storage filename without writing to a temporary file. Useful when the payload is already in memory. content must be one of the values accepted by the Proxmox upload endpoint (iso, vztmpl, import).

func (*Storage) UploadWithHash 

func (s *Storage) UploadWithHash(content, file string, storageFilename *string, checksum, checksumAlgorithm string) (*Task, error)

func (*Storage) UploadWithName 

func (s *Storage) UploadWithName(content, file string, storageFilename string) (*Task, error)

func (*Storage) VzTmpl 

func (s *Storage) VzTmpl(ctx context.Context, name string) (vztmpl *VzTmpl, err error)

type StorageContent 

type StorageContent struct {
	Format string         `json:"format,omitempty"`
	Size   uint64         `json:"size,omitempty"`
	Volid  string         `json:"volid,omitempty"`
	Ctime  StringOrUint64 `json:"ctime,omitempty"`
	// Encrypted is the PBS encryption fingerprint, or "1" if the backup is
	// encrypted without a known fingerprint. PBS-only; empty for other
	// storage types. (The upstream field is `encrypted`, not `encryption`
	// — the latter tag was a typo on this struct prior to v0.7.1.)
	Encrypted  string    `json:"encrypted,omitempty"`
	Notes      string    `json:"notes,omitempty"`
	Parent     string    `json:"parent,omitempty"`
	Protection IntOrBool `json:"protection,omitempty"`
	Used       uint64    `json:"used,omitempty"`
	// Verification is the last PBS verification result for this backup
	// (PBS-only; nil for other storage types). Upstream returns a nested
	// object {state, upid}; prior to v0.7.1 this field was typed as a
	// plain string and never unmarshalled.
	Verification *StorageContentVerification `json:"verification,omitempty"`
	VMID         uint64                      `json:"vmid,omitempty"`
}

type StorageContentAllocOptions added in v0.6.0 

type StorageContentAllocOptions struct {
	Filename string `json:"filename"`
	Size     string `json:"size"` // e.g. "1024" (KB) or "4G"
	VMID     uint64 `json:"vmid"`
	Format   string `json:"format,omitempty"`
}

StorageContentAllocOptions is the body for POST /content — allocate a new disk image on the storage. Filename and Size are required; PVE picks Format based on the storage type when unset.

type StorageContentUpdateOptions added in v0.6.0 

type StorageContentUpdateOptions struct {
	Notes     string `json:"notes,omitempty"`
	Protected *bool  `json:"protected,omitempty"`
}

StorageContentUpdateOptions is the PUT body for /content/{volume}. Protected currently only applies to backup volumes.

type StorageContentVerification added in v0.7.1 

type StorageContentVerification struct {
	State string `json:"state,omitempty"`
	UPID  string `json:"upid,omitempty"`
}

StorageContentVerification is the last verification result for a PBS-backed backup entry as returned by /nodes/{node}/storage/{storage}/content. UPID points at the verify task; State is the textual outcome (e.g. "ok", "failed").

type StorageDownloadURLOptions 

type StorageDownloadURLOptions struct {
	Content           string `json:"content,omitempty"`
	Filename          string `json:"filename,omitempty"`
	Node              string `json:"node,omitempty"`
	Storage           string `json:"storage,omitempty"`
	URL               string `json:"url,omitempty"`
	Checksum          string `json:"checksum,omitempty"`
	ChecksumAlgorithm string `json:"checksum-algorithm,omitempty"`
	Compression       string `json:"compression,omitempty"`
	// VerifyCertificates — PVE default 1 (verify TLS certs on remote
	// metrics push). Unset on partial updates would silently disable cert
	// verification. See #178 + #199.
	VerifyCertificates *IntOrBool `json:"verify-certificates,omitempty"`
}

type StorageFileRestoreEntry added in v0.6.0 

type StorageFileRestoreEntry struct {
	Filepath string    `json:"filepath,omitempty"`
	Type     string    `json:"type,omitempty"` // "f" (file), "d" (directory), "l" (link)
	Text     string    `json:"text,omitempty"`
	Size     uint64    `json:"size,omitempty"`
	Mtime    int64     `json:"mtime,omitempty"`
	Leaf     IntOrBool `json:"leaf,omitempty"`
}

StorageFileRestoreEntry is one row from GET /file-restore/list.

type StorageIdentity added in v0.6.0 

type StorageIdentity struct {
	ID   string `json:"id"`
	Type string `json:"type"`
}

StorageIdentity is the response shape of GET /nodes/{node}/storage/{storage}/identity. ID is content-addressed for plugins that support it (e.g. PBS datastore fingerprint), else the storage name. Type is the plugin kind.

type StoragePruneBackupsOptions added in v0.6.0 

type StoragePruneBackupsOptions struct {
	// PruneBackups overrides the storage's configured retention spec for this
	// call only. Example: "keep-last=3,keep-monthly=4". Empty uses the storage default.
	PruneBackups string
	// Type filters by guest type: "qemu" or "lxc". Empty considers both.
	Type string
	// VMID filters to a single guest. Zero considers all guests.
	VMID uint64
}

StoragePruneBackupsOptions filters which backups PreviewPruneBackups and PruneBackups operate on. The zero value means "use the storage's configured retention spec and apply to every backup".

type StorageStatus added in v0.7.0 

type StorageStatus struct {
	// Type is the storage plugin ("dir", "lvm", "lvmthin", "zfs", "nfs",
	// "cifs", "pbs", "rbd", "cephfs", …).
	Type string `json:"type,omitempty"`
	// Content is the comma-joined list of content types the storage holds
	// ("images,rootdir,iso,vztmpl,backup,snippets,import").
	Content string `json:"content,omitempty"`
	// Active is 1 when the storage is currently mounted/reachable on this
	// node, 0 otherwise (e.g. unreachable NFS, disabled storage). Capacity
	// fields are only populated when Active=1.
	Active int `json:"active,omitempty"`
	// Enabled is 1 when the storage is administratively enabled on this
	// node (it may still be Active=0 if the underlying transport is down).
	Enabled int `json:"enabled,omitempty"`
	// Shared is 1 when PVE treats this storage as shared across the
	// cluster (NFS, CIFS, Ceph, …) and 0 for node-local plugins.
	Shared int `json:"shared,omitempty"`
	// Total is the storage's total capacity in bytes; 0 when inactive.
	Total uint64 `json:"total,omitempty"`
	// Used is bytes currently used; 0 when inactive.
	Used uint64 `json:"used,omitempty"`
	// Avail is bytes available; 0 when inactive.
	Avail uint64 `json:"avail,omitempty"`
	// UsedFraction is Used/Total as a float in [0,1]; 0 when inactive.
	UsedFraction float64 `json:"used_fraction,omitempty"`
}

StorageStatus is the response of GET /nodes/{node}/storage/{storage}. Despite its path being a diridx, PVE returns the storage's capability / status object directly: type + plugin metadata (Active, Enabled, Shared), declared Content types, and (when active) capacity counters. Numeric fields are int/uint64 to match what the JSON envelope unmarshals into.

type Storages 

type Storages []*Storage

func (*Storages) UnmarshalJSON added in v0.4.0 

func (storages *Storages) UnmarshalJSON(b []byte) error

UnmarshalJSON implements custom unmarshaling for Storages slice

type StringOrFloat64 

type StringOrFloat64 float64

func (*StringOrFloat64) UnmarshalJSON 

func (d *StringOrFloat64) UnmarshalJSON(b []byte) error

type StringOrInt 

type StringOrInt int

func (*StringOrInt) UnmarshalJSON 

func (d *StringOrInt) UnmarshalJSON(b []byte) error

type StringOrUint64 

type StringOrUint64 uint64

func (*StringOrUint64) UnmarshalJSON 

func (d *StringOrUint64) UnmarshalJSON(b []byte) error

type Subscription added in v0.6.0 

type Subscription struct {
	Status         string `json:"status,omitempty"` // active / inactive / notfound / expired / suspended / new
	Key            string `json:"key,omitempty"`
	Level          string `json:"level,omitempty"` // c=community, b=basic, s=standard, p=premium
	ProductName    string `json:"productname,omitempty"`
	RegDate        string `json:"regdate,omitempty"`     // YYYY-MM-DD HH:MM:SS
	NextDueDate    string `json:"nextduedate,omitempty"` // YYYY-MM-DD
	Validdirectory string `json:"validdirectory,omitempty"`
	Sockets        int    `json:"sockets,omitempty"`
	Checktime      int64  `json:"checktime,omitempty"` // epoch
	ServerID       string `json:"serverid,omitempty"`
	URL            string `json:"url,omitempty"`
	Message        string `json:"message,omitempty"`
	Signature      string `json:"signature,omitempty"`
}

Subscription mirrors GET /nodes/{node}/subscription. Fields are loosely typed because PVE's response varies between license levels (community, basic, standard, premium) and between current-vs-expired states.

type TFA 

type TFA struct {
	Realm string   `json:"realm,omitempty"`
	Types []string `json:"types,omitempty"`
	User  string   `json:"user,omitempty"`
}

type TFAEntryInfo added in v0.6.0 

type TFAEntryInfo struct {
	ID          string    `json:"id,omitempty"`
	Type        string    `json:"type,omitempty"` // totp | webauthn | u2f | yubico | recovery
	Description string    `json:"description,omitempty"`
	Created     int64     `json:"created,omitempty"`
	Enable      IntOrBool `json:"enable,omitempty"`
}

TFAEntryInfo is the read shape of a single TFA entry.

type TFAEntryOptions added in v0.6.0 

type TFAEntryOptions struct {
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
	TOTP        string `json:"totp,omitempty"`
	Value       string `json:"value,omitempty"`
	Challenge   string `json:"challenge,omitempty"`
	Password    string `json:"password,omitempty"`
}

TFAEntryOptions is the POST body for adding a TFA entry.

  • Type is required ("totp" | "webauthn" | "u2f" | "yubico" | "recovery").
  • For TOTP: set TOTP (the otpauth:// URI) and Value (the current OTP to prove enrollment).
  • For Webauthn/U2F: set Challenge / Value with the client's signed assertion.
  • Password is the requesting user's current password (required when changing another user's TFA).

type TFAEntryUpdateOptions added in v0.6.0 

type TFAEntryUpdateOptions struct {
	Enable      *bool  `json:"enable,omitempty"`
	Description string `json:"description,omitempty"`
	Password    string `json:"password,omitempty"`
}

TFAEntryUpdateOptions is the PUT body for updating an existing entry. Only Enable / Description are settable.

type TFAUserEntry added in v0.6.0 

type TFAUserEntry struct {
	UserID    string         `json:"userid,omitempty"`
	Entries   []TFAEntryInfo `json:"entries,omitempty"`
	TOTP      bool           `json:"totp,omitempty"`
	YubicoOTP bool           `json:"yubico,omitempty"`
	U2F       bool           `json:"u2f,omitempty"`
	Webauthn  bool           `json:"webauthn,omitempty"`
	Recovery  []int          `json:"recovery,omitempty"`
}

TFAUserEntry is one row in GET /access/tfa — a user that has at least one TFA entry configured.

type Task 

type Task struct {
	UPID         UPID
	ID           string
	Type         string
	User         string
	Status       string
	Node         string
	PID          uint64 `json:",omitempty"`
	PStart       uint64 `json:",omitempty"`
	Saved        string `json:",omitempty"`
	ExitStatus   string `json:",omitempty"`
	IsCompleted  bool
	IsRunning    bool
	IsFailed     bool
	IsSuccessful bool
	StartTime    time.Time     `json:"-"`
	EndTime      time.Time     `json:"-"`
	Duration     time.Duration `json:"-"`
	// contains filtered or unexported fields
}

func NewTask 

func NewTask(upid UPID, client *Client) *Task

func (*Task) Log 

func (t *Task) Log(ctx context.Context, start, limit int) (l Log, err error)

func (*Task) Ping 

func (t *Task) Ping(ctx context.Context) error

func (*Task) Stop 

func (t *Task) Stop(ctx context.Context) error

func (*Task) Subdirs added in v0.7.0 

func (t *Task) Subdirs(ctx context.Context) ([]string, error)

Subdirs enumerates the children of /nodes/{node}/tasks/{upid} ("log", "status"). Use as a permission probe before calling Log/Ping.

func (*Task) UnmarshalJSON 

func (t *Task) UnmarshalJSON(b []byte) error

func (*Task) Wait 

func (t *Task) Wait(ctx context.Context, interval, max time.Duration) error

func (*Task) WaitFor 

func (t *Task) WaitFor(ctx context.Context, seconds int) error

func (*Task) WaitForCompleteStatus 

func (t *Task) WaitForCompleteStatus(ctx context.Context, timesNum int, steps ...int) (status bool, completed bool, err error)

func (*Task) Watch 

func (t *Task) Watch(ctx context.Context, start int) (chan string, error)

type Tasks 

type Tasks []*Task

type Term added in v0.1.2 

type Term struct {
	Port   StringOrInt
	Ticket string
	UPID   string
	User   string
}

type Time 

type Time struct {
	Timezone  string
	Time      uint64
	Localtime uint64
}

type Timeframe 

type Timeframe string

type Token 

type Token struct {
	TokenID string    `json:"tokenid,omitempty"`
	Comment string    `json:"comment,omitempty"`
	Expire  int       `json:"expire,omitempty"`
	Privsep IntOrBool `json:"privsep"`
}

type Tokens 

type Tokens []*Token

type UPID 

type UPID string

type USBDevice added in v0.6.0 

type USBDevice struct {
	BusNum       int    `json:"busnum"`
	DevNum       int    `json:"devnum"`
	Port         int    `json:"port"`
	Level        int    `json:"level"`
	Class        int    `json:"class"`
	VendID       string `json:"vendid"`
	ProdID       string `json:"prodid"`
	Speed        string `json:"speed"`
	Manufacturer string `json:"manufacturer,omitempty"`
	Product      string `json:"product,omitempty"`
	Serial       string `json:"serial,omitempty"`
	USBPath      string `json:"usbpath,omitempty"`
}

USBDevice is one local USB device.

type User 

type User struct {
	UserID         string           `json:"userid,omitempty"`
	Comment        string           `json:"comment,omitempty"`
	Email          string           `json:"email,omitempty"`
	Enable         IntOrBool        `json:"enable"`
	Expire         int              `json:"expire,omitempty"`
	Firstname      string           `json:"firstname,omitempty"`
	Lastname       string           `json:"lastname,omitempty"`
	Groups         CSV              `json:"groups,omitempty"`
	Keys           string           `json:"keys,omitempty"`
	Tokens         map[string]Token `json:"tokens,omitempty"`
	RealmType      string           `json:"realm-type,omitempty"`
	TFALockedUntil string           `json:"tfa-locked-until,omitempty"`
	TOTPLocked     IntOrBool        `json:"totp-locked,omitempty"`
	// contains filtered or unexported fields
}

func (*User) APIToken 

func (u *User) APIToken(ctx context.Context, tokenid string) (token Token, err error)

func (*User) Delete 

func (u *User) Delete(ctx context.Context) error

func (*User) DeleteAPIToken 

func (u *User) DeleteAPIToken(ctx context.Context, tokenid string) error

func (*User) GetAPITokens 

func (u *User) GetAPITokens(ctx context.Context) (tokens Tokens, err error)

func (*User) GetTFA 

func (u *User) GetTFA(ctx context.Context) (tfa TFA, err error)

func (*User) NewAPIToken 

func (u *User) NewAPIToken(ctx context.Context, token Token) (newtoken NewAPIToken, err error)

func (*User) UnlockTFA 

func (u *User) UnlockTFA(ctx context.Context) error

func (*User) Update 

func (u *User) Update(ctx context.Context, options UserOptions) error

func (*User) UpdateAPIToken 

func (u *User) UpdateAPIToken(ctx context.Context, tokenid string) (token Token, err error)

type UserOptions added in v0.2.4 

type UserOptions struct {
	Append  IntOrBool `json:"append,omitempty"`
	Comment string    `json:"comment,omitempty"`
	Email   string    `json:"email,omitempty"`
	// Enable — PVE default 1 (accounts active). Unset on partial updates
	// would silently disable a user account. See #178 + #199.
	Enable    *IntOrBool `json:"enable,omitempty"`
	Expire    int        `json:"expire,omitempty"`
	Firstname string     `json:"firstname,omitempty"`
	Groups    CSV        `json:"groups,omitempty"`
	Keys      string     `json:"keys,omitempty"`
	Lastname  string     `json:"lastname,omitempty"`
}

type Users 

type Users []*User

type VNC 

type VNC struct {
	Cert     string
	Port     StringOrInt
	Ticket   string
	UPID     string
	User     string
	Password string `json:",omitempty"`
}

type VNCConfig added in v0.1.2 

type VNCConfig struct {
	GeneratePassword bool `json:"generate-password,omitempty"`
	Websocket        bool `json:"websocket,omitempty"`
}

type VNCProxyOptions 

type VNCProxyOptions struct {
	Websocket string `json:"websocket,omitempty"`
	Height    int    `json:"height,omitempty"`
	Width     int    `json:"width,omitempty"`
}

type VNet added in v0.2.3 

type VNet struct {
	Name      string `json:"vnet,omitempty"`
	Type      string `json:"type,omitempty"`
	Zone      string `json:"zone,omitempty"`
	Alias     string `json:"alias,omitempty"`
	VlanAware int    `json:"vlanaware,omitempty"`
	Tag       uint32 `json:"tag,omitempty"`
	// contains filtered or unexported fields
}

func (*VNet) CreateIP added in v0.7.0 

func (v *VNet) CreateIP(ctx context.Context, opts *SDNVNetIPOptions) error

CreateIP creates a MAC/IP mapping in the IPAM for this VNet. opts.Zone and opts.IP are required.

POST /cluster/sdn/vnets/{vnet}/ips

func (*VNet) DeleteIP added in v0.7.0 

func (v *VNet) DeleteIP(ctx context.Context, opts *SDNVNetIPOptions) error

DeleteIP removes an IP mapping from the IPAM for this VNet.

DELETE /cluster/sdn/vnets/{vnet}/ips

func (*VNet) FirewallIndex added in v0.7.0 

func (v *VNet) FirewallIndex(ctx context.Context) (entries []map[string]any, err error)

FirewallIndex returns the per-VNet firewall directory entries ({"options", "rules"}).

GET /cluster/sdn/vnets/{vnet}/firewall

func (*VNet) FirewallOptions added in v0.7.0 

func (v *VNet) FirewallOptions(ctx context.Context) (*SDNVNetFirewallOptions, error)

FirewallOptions reads the per-VNet firewall toggle/policy/log-level.

GET /cluster/sdn/vnets/{vnet}/firewall/options

func (*VNet) FirewallOptionsUpdate added in v0.7.0 

func (v *VNet) FirewallOptionsUpdate(ctx context.Context, opts *SDNVNetFirewallOptionsUpdate) error

FirewallOptionsUpdate mutates the per-VNet firewall options.

PUT /cluster/sdn/vnets/{vnet}/firewall/options

func (*VNet) FirewallRule added in v0.7.0 

func (v *VNet) FirewallRule(ctx context.Context, pos int) (*SDNVNetFirewallRule, error)

FirewallRule reads a single firewall rule on this VNet by position.

GET /cluster/sdn/vnets/{vnet}/firewall/rules/{pos}

func (*VNet) FirewallRuleDelete added in v0.7.0 

func (v *VNet) FirewallRuleDelete(ctx context.Context, pos int) error

FirewallRuleDelete removes a firewall rule by position.

DELETE /cluster/sdn/vnets/{vnet}/firewall/rules/{pos}

func (*VNet) FirewallRuleUpdate added in v0.7.0 

func (v *VNet) FirewallRuleUpdate(ctx context.Context, pos int, opts *SDNVNetFirewallRuleOptions) error

FirewallRuleUpdate mutates an existing firewall rule by position.

PUT /cluster/sdn/vnets/{vnet}/firewall/rules/{pos}

func (*VNet) FirewallRules added in v0.7.0 

func (v *VNet) FirewallRules(ctx context.Context) (rules []*SDNVNetFirewallRule, err error)

FirewallRules lists the firewall rules on this VNet.

GET /cluster/sdn/vnets/{vnet}/firewall/rules

func (*VNet) NewFirewallRule added in v0.7.0 

func (v *VNet) NewFirewallRule(ctx context.Context, opts *SDNVNetFirewallRuleOptions) error

NewFirewallRule creates a new firewall rule on this VNet. opts.Type and opts.Action are required.

POST /cluster/sdn/vnets/{vnet}/firewall/rules

func (*VNet) NewSubnet added in v0.7.0 

func (v *VNet) NewSubnet(ctx context.Context, opts *SDNSubnetOptions) error

NewSubnet creates a new subnet under this VNet. opts.Subnet (CIDR) is required; opts.Type defaults to "subnet" if empty.

POST /cluster/sdn/vnets/{vnet}/subnets

func (*VNet) Subnet added in v0.7.0 

func (v *VNet) Subnet(name string) *VNetSubnet

Subnet returns a handle for a single subnet under this VNet. No API call is made; use the returned handle's Read to populate it.

GET /cluster/sdn/vnets/{vnet}/subnets/{subnet}

func (*VNet) Subnets added in v0.7.0 

func (v *VNet) Subnets(ctx context.Context) (subnets []*VNetSubnet, err error)

Subnets lists the subnets configured under this VNet.

GET /cluster/sdn/vnets/{vnet}/subnets

func (*VNet) UpdateIP added in v0.7.0 

func (v *VNet) UpdateIP(ctx context.Context, opts *SDNVNetIPOptions) error

UpdateIP updates a MAC/IP mapping in the IPAM (e.g. to associate a VMID).

PUT /cluster/sdn/vnets/{vnet}/ips

type VNetOptions added in v0.2.3 

type VNetOptions struct {
	Name         string    `json:"vnet"`
	Zone         string    `json:"zone"`
	Alias        string    `json:"alias,omitempty"`
	IsolatePorts IntOrBool `json:"isolate-ports,omitempty"`
	Tag          uint32    `json:"tag,omitempty"`  // Could be a VLAN or VXLAN tag
	Type         string    `json:"type,omitempty"` // Type must be set to "vnet"
	VlanAware    IntOrBool `json:"vlanaware,omitempty"`
}

type VNetSubnet added in v0.2.3 

type VNetSubnet struct {
	CIDR      string     `json:"cidr,omitempty"`
	Gateway   string     `json:"gateway,omitempty"`
	Netmask   string     `json:"mask,omitempty"`
	Type      string     `json:"type,omitempty"`
	Zone      string     `json:"zone,omitempty"`
	VNet      string     `json:"vnet,omitempty"`
	SNAT      int        `json:"snat,omitempty"`
	Network   string     `json:"network,omitempty"`
	ID        string     `json:"id,omitempty"`
	DhcpRange []NetRange `json:"dhcp-range,omitempty"`
	// contains filtered or unexported fields
}

func (*VNetSubnet) Delete added in v0.7.0 

func (s *VNetSubnet) Delete(ctx context.Context) error

Delete removes the subnet.

DELETE /cluster/sdn/vnets/{vnet}/subnets/{subnet}

func (*VNetSubnet) Read added in v0.7.0 

func (s *VNetSubnet) Read(ctx context.Context) error

Read populates the receiver with the subnet configuration.

GET /cluster/sdn/vnets/{vnet}/subnets/{subnet}

func (*VNetSubnet) Update added in v0.7.0 

func (s *VNetSubnet) Update(ctx context.Context, opts *SDNSubnetOptions) error

Update mutates the subnet configuration.

PUT /cluster/sdn/vnets/{vnet}/subnets/{subnet}

type VerifyVNCTicketOptions added in v0.6.0 

type VerifyVNCTicketOptions struct {
	AuthID    string `json:"authid"`
	Path      string `json:"path"`
	Privs     string `json:"privs"`
	VNCTicket string `json:"vncticket"`
	Port      int    `json:"port,omitempty"`
}

VerifyVNCTicketOptions is the POST body for /access/vncticket. AuthID, Path, and VNCTicket are required; Privs lists privileges to check on Path; Port (optional) binds the verification to a specific VNC port.

type Version 

type Version struct {
	Release string `json:"release"`
	RepoID  string `json:"repoid"`
	Version string `json:"version"`
}

type VirtualMachine 

type VirtualMachine struct {
	VirtualMachineConfig *VirtualMachineConfig

	Name string
	Node string

	Agent          IntOrBool
	Spice          IntOrBool
	NetIn          uint64
	CPUs           int
	DiskWrite      uint64
	Status         string
	Lock           string `json:",omitempty"`
	VMID           StringOrUint64
	PID            StringOrUint64
	Netout         uint64
	Disk           uint64
	Mem            uint64
	CPU            float64
	MaxMem         uint64
	MaxDisk        uint64
	DiskRead       uint64
	QMPStatus      string `json:"qmpstatus,omitempty"`
	RunningMachine string `json:"running-machine,omitempty"`
	RunningQemu    string `json:"running-qemu,omitempty"`
	Tags           string `json:"tags,omitempty"`
	Uptime         uint64
	Template       IsTemplate // empty str if a vm, int 1 if a template
	HA             HA         `json:",omitempty"`
	// contains filtered or unexported fields
}

func (*VirtualMachine) AddTag 

func (v *VirtualMachine) AddTag(ctx context.Context, value string) (*Task, error)

func (*VirtualMachine) AgentCommand added in v0.6.0 

func (v *VirtualMachine) AgentCommand(ctx context.Context, command string) (map[string]interface{}, error)

AgentCommand is the low-level POST /agent helper that runs any QGA command by name. The specific helpers (AgentPing, AgentGetTime, …) are preferable for known commands because they return typed values; this exists for the rare command not otherwise wrapped (or for forward-compat with new QGA verbs PVE adds). PVE constrains the accepted names — see the enum on the API endpoint — but we don't gate that here so callers stay forward-compat. The raw {"result": ...} envelope payload is returned as a JSON map.

func (*VirtualMachine) AgentCommandIndex added in v0.6.0 

func (v *VirtualMachine) AgentCommandIndex(ctx context.Context) ([]*AgentCommandIndexEntry, error)

AgentCommandIndex lists the QEMU guest-agent sub-commands the PVE node exposes for this VM. This is the index served at GET /agent — it surfaces the routing table the proxy itself knows about and is independent of what the in-guest agent actually advertises (see AgentGetInfo for that).

func (*VirtualMachine) AgentExec 

func (v *VirtualMachine) AgentExec(ctx context.Context, command []string, inputData string) (pid int, err error)

func (*VirtualMachine) AgentExecStatus 

func (v *VirtualMachine) AgentExecStatus(ctx context.Context, pid int) (status *AgentExecStatus, err error)

func (*VirtualMachine) AgentFileRead added in v0.6.0 

func (v *VirtualMachine) AgentFileRead(ctx context.Context, file string) (*AgentFileRead, error)

AgentFileRead reads a file from the guest via the guest-agent. The PVE endpoint caps the response at 16 MiB and exposes a Truncated flag so callers can detect partial reads. Note: unlike most agent endpoints, the response is NOT wrapped in a "result" envelope here — content and truncated sit at the top level under "data".

func (*VirtualMachine) AgentFileWrite added in v0.6.0 

func (v *VirtualMachine) AgentFileWrite(ctx context.Context, file string, content []byte) error

AgentFileWrite writes content to a file inside the guest. PVE base64- encodes the payload before handing it to QGA (their `encode` flag), so we do that here unconditionally — the per-call body size cap is ~60 KiB regardless. Pass the raw bytes; this helper handles the encoding.

func (*VirtualMachine) AgentFsfreezeFreeze added in v0.6.0 

func (v *VirtualMachine) AgentFsfreezeFreeze(ctx context.Context) (int, error)

AgentFsfreezeFreeze freezes all guest filesystems; returns the number of filesystems frozen. Pair with AgentFsfreezeThaw — leaving a guest frozen will hang every write inside it.

func (*VirtualMachine) AgentFsfreezeStatus added in v0.6.0 

func (v *VirtualMachine) AgentFsfreezeStatus(ctx context.Context) (AgentFsfreezeStatus, error)

AgentFsfreezeStatus reports whether the guest filesystems are currently frozen ("thawed" or "frozen").

func (*VirtualMachine) AgentFsfreezeThaw added in v0.6.0 

func (v *VirtualMachine) AgentFsfreezeThaw(ctx context.Context) (int, error)

AgentFsfreezeThaw thaws all previously-frozen guest filesystems and returns the count thawed.

func (*VirtualMachine) AgentFstrim added in v0.6.0 

func (v *VirtualMachine) AgentFstrim(ctx context.Context) (map[string]interface{}, error)

AgentFstrim issues fstrim across all mounted guest filesystems. PVE returns a per-mountpoint trim report which we expose as the raw JSON map.

func (*VirtualMachine) AgentGetFsInfo added in v0.6.0 

func (v *VirtualMachine) AgentGetFsInfo(ctx context.Context) ([]*AgentFsInfo, error)

AgentGetFsInfo returns one entry per mounted filesystem in the guest, with disk usage and the underlying block device topology.

func (*VirtualMachine) AgentGetHostName added in v0.5.0 

func (v *VirtualMachine) AgentGetHostName(ctx context.Context) (hostname string, err error)

func (*VirtualMachine) AgentGetInfo added in v0.6.0 

func (v *VirtualMachine) AgentGetInfo(ctx context.Context) (*AgentInfo, error)

AgentGetInfo returns the guest-agent's own version and the list of QGA commands it advertises. Useful to feature-detect before issuing an op the agent may not support.

func (*VirtualMachine) AgentGetMemoryBlockInfo added in v0.6.0 

func (v *VirtualMachine) AgentGetMemoryBlockInfo(ctx context.Context) (*AgentMemoryBlockInfo, error)

AgentGetMemoryBlockInfo returns hot-pluggable memory-block sizing for the guest — the per-block byte size that AgentGetMemoryBlocks's phys-index references. Returns zero on guests without memory-hotplug support.

func (*VirtualMachine) AgentGetMemoryBlocks added in v0.6.0 

func (v *VirtualMachine) AgentGetMemoryBlocks(ctx context.Context) ([]*AgentMemoryBlock, error)

AgentGetMemoryBlocks lists hot-pluggable memory blocks visible to the guest. Older kernels / non-Linux guests return an empty slice.

func (*VirtualMachine) AgentGetNetworkIFaces 

func (v *VirtualMachine) AgentGetNetworkIFaces(ctx context.Context) (iFaces []*AgentNetworkIface, err error)

func (*VirtualMachine) AgentGetTime added in v0.6.0 

func (v *VirtualMachine) AgentGetTime(ctx context.Context) (AgentTime, error)

AgentGetTime returns the guest's wall-clock time in nanoseconds since the Unix epoch.

func (*VirtualMachine) AgentGetTimezone added in v0.6.0 

func (v *VirtualMachine) AgentGetTimezone(ctx context.Context) (string, error)

AgentGetTimezone returns the guest IANA timezone string (e.g. "UTC"). QGA reports both a string zone and a UTC offset; only the zone is exposed here — callers needing the offset can use AgentInfo to fall back.

func (*VirtualMachine) AgentGetUsers added in v0.6.0 

func (v *VirtualMachine) AgentGetUsers(ctx context.Context) ([]*AgentUser, error)

AgentGetUsers lists users currently logged into the guest.

func (*VirtualMachine) AgentGetVCPUs added in v0.6.0 

func (v *VirtualMachine) AgentGetVCPUs(ctx context.Context) ([]*AgentVCPU, error)

AgentGetVCPUs lists the guest's logical CPUs and their online state.

func (*VirtualMachine) AgentOsInfo 

func (v *VirtualMachine) AgentOsInfo(ctx context.Context) (info *AgentOsInfo, err error)

func (*VirtualMachine) AgentPing added in v0.6.0 

func (v *VirtualMachine) AgentPing(ctx context.Context) error

AgentPing is a cheap probe that the guest-agent socket is reachable. PVE returns an empty result on success; any non-nil error means the agent is unreachable or the VM is off.

func (*VirtualMachine) AgentSetUserPassword 

func (v *VirtualMachine) AgentSetUserPassword(ctx context.Context, password string, username string) error

func (*VirtualMachine) AgentShutdown added in v0.6.0 

func (v *VirtualMachine) AgentShutdown(ctx context.Context) error

AgentShutdown asks the guest-agent to shut the guest down cleanly. Unlike VirtualMachine.Shutdown (which goes through QEMU and returns a Task), this is a synchronous QGA call — the guest may take many seconds to actually halt after this returns.

func (*VirtualMachine) AgentSuspendDisk added in v0.6.0 

func (v *VirtualMachine) AgentSuspendDisk(ctx context.Context) error

AgentSuspendDisk suspends the guest to disk (S4 / hibernation).

func (*VirtualMachine) AgentSuspendHybrid added in v0.6.0 

func (v *VirtualMachine) AgentSuspendHybrid(ctx context.Context) error

AgentSuspendHybrid suspends the guest to a hybrid sleep state (RAM + disk).

func (*VirtualMachine) AgentSuspendRAM added in v0.6.0 

func (v *VirtualMachine) AgentSuspendRAM(ctx context.Context) error

AgentSuspendRAM suspends the guest to RAM (S3).

func (*VirtualMachine) Clone 

func (v *VirtualMachine) Clone(ctx context.Context, params *VirtualMachineCloneOptions) (newid int, task *Task, err error)

func (*VirtualMachine) CloudInit 

func (v *VirtualMachine) CloudInit(ctx context.Context, device, userdata, metadata, vendordata, networkconfig string, opts ...CloudInitOption) error

CloudInit takes four yaml docs as a string and make an ISO, upload it to the data store as <vmid>-user-data.iso and will mount it as a CD-ROM to be used with nocloud cloud-init. This is NOT how proxmox expects a user to do cloud-init which can be found here: https://pve.proxmox.com/wiki/Cloud-Init_Support#:~:text=and%20meta.-,Cloud%2DInit%20specific%20Options,-cicustom%3A%20%5Bmeta If you want to use the proxmox implementation you'll need to use the cloudinit APIs https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/qemu/{vmid}/cloudinit

Pass WithCloudInitStorage("name") to control which storage receives the ISO. Without it, the first enabled iso-capable storage returned by the node is used.

func (*VirtualMachine) CloudInitDump added in v0.6.0 

func (v *VirtualMachine) CloudInitDump(ctx context.Context, kind string) (string, error)

CloudInitDump returns the rendered cloud-init configuration document of a given kind. kind must be one of "user", "meta", "network".

func (*VirtualMachine) CloudInitPending added in v0.6.0 

func (v *VirtualMachine) CloudInitPending(ctx context.Context) (pending []*VirtualMachineCloudInitPending, err error)

CloudInitPending lists per-VM cloud-init config differences between the applied image and the current VM config. Empty list means the image is in sync with the config.

func (*VirtualMachine) CloudInitRegenerate added in v0.6.0 

func (v *VirtualMachine) CloudInitRegenerate(ctx context.Context) error

CloudInitRegenerate rewrites the cloud-init ISO/cd-rom so the next guest boot picks up pending changes. Synchronous — PVE returns null on success.

func (*VirtualMachine) Config 

func (v *VirtualMachine) Config(ctx context.Context, options ...VirtualMachineOption) (*Task, error)

func (*VirtualMachine) ConfigSync added in v0.6.0 

func (v *VirtualMachine) ConfigSync(ctx context.Context, options ...VirtualMachineOption) error

ConfigSync sets virtual machine options using the synchronous API (PUT /nodes/{node}/qemu/{vmid}/config). It blocks until the change is applied and does not return a task. Per the upstream docs, prefer the asynchronous variant (Config) for any actions involving hotplug or storage allocation.

func (*VirtualMachine) ConvertToTemplate 

func (v *VirtualMachine) ConvertToTemplate(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) DBusVMState added in v0.6.0 

func (v *VirtualMachine) DBusVMState(ctx context.Context, action string) error

DBusVMState controls the dbus-vmstate helper for a running VM. Valid actions are "start" and "stop". This is a niche endpoint used to migrate additional VM state via the dbus-vmstate helper.

func (*VirtualMachine) Delete 

func (v *VirtualMachine) Delete(ctx context.Context, options *VirtualMachineDeleteOptions) (task *Task, err error)

func (*VirtualMachine) DeleteFirewallAlias added in v0.6.0 

func (v *VirtualMachine) DeleteFirewallAlias(ctx context.Context, name string) error

DeleteFirewallAlias removes a per-VM firewall alias.

func (*VirtualMachine) DeleteFirewallIPSet added in v0.2.3 

func (v *VirtualMachine) DeleteFirewallIPSet(ctx context.Context, name string, force bool) error

func (*VirtualMachine) DeleteFirewallIPSetEntry added in v0.2.3 

func (v *VirtualMachine) DeleteFirewallIPSetEntry(ctx context.Context, name string, cidr string, digest string) error

func (*VirtualMachine) DirIndex added in v0.6.0 

func (v *VirtualMachine) DirIndex(ctx context.Context) (entries []*VirtualMachineDirIndexEntry, err error)

DirIndex returns the per-VM directory index (GET /nodes/{node}/qemu/{vmid}) — one entry per child resource (config, status, snapshot, firewall, agent, …). Mostly useful for discovery; the actual resources are wrapped as their own methods on *VirtualMachine.

func (*VirtualMachine) Feature added in v0.6.0 

func (v *VirtualMachine) Feature(ctx context.Context, feature, snapname string) (VirtualMachineFeature, error)

Feature checks whether a given feature (for example "snapshot", "clone", or "copy") is available for this VM. When snapname is non-empty the check is performed against that specific snapshot. The returned VirtualMachineFeature also lists which cluster nodes the feature is available on.

func (*VirtualMachine) Firewall added in v0.6.0 

func (v *VirtualMachine) Firewall(ctx context.Context) (firewall *Firewall, err error)

Firewall fetches the directory-rooted firewall record (aliases + ipset + rules + options) for the VM in one call. Cheaper than four round-trips when you just need a snapshot.

func (*VirtualMachine) FirewallLog added in v0.6.0 

func (v *VirtualMachine) FirewallLog(ctx context.Context, start, limit, since, until int) (entries []*FirewallLogEntry, err error)

FirewallLog returns the per-VM firewall log entries. start/limit page the result; since/until filter by UNIX epoch — pass 0 to omit.

func (*VirtualMachine) FirewallOptionGet 

func (v *VirtualMachine) FirewallOptionGet(ctx context.Context) (firewallOption *FirewallVirtualMachineOption, err error)

func (*VirtualMachine) FirewallOptionSet 

func (v *VirtualMachine) FirewallOptionSet(ctx context.Context, firewallOption *FirewallVirtualMachineOption) error

func (*VirtualMachine) FirewallRefs added in v0.6.0 

func (v *VirtualMachine) FirewallRefs(ctx context.Context, refType string) (refs []*FirewallRef, err error)

FirewallRefs lists IPSets and aliases reachable from this VM's scope — useful when authoring rules that reference cluster/node-level objects alongside VM-local ones. Pass refType ("alias"|"ipset"|"") to filter.

func (*VirtualMachine) FirewallRule added in v0.7.0 

func (v *VirtualMachine) FirewallRule(pos int) *FirewallRule

FirewallRule returns a *FirewallRule wired to the VM's firewall scope at the given position. The returned instance is a lazy handle — call Get(ctx) to populate it from /firewall/rules/{pos}.

func (*VirtualMachine) FirewallRules added in v0.7.0 

func (v *VirtualMachine) FirewallRules(ctx context.Context) (rules []*FirewallRule, err error)

FirewallRules lists firewall rules for the VM. Returned rules carry the parent context required to call (*FirewallRule).Get/Update/Delete.

func (*VirtualMachine) GetFirewallAlias added in v0.6.0 

func (v *VirtualMachine) GetFirewallAlias(ctx context.Context, name string) (alias *FirewallAlias, err error)

GetFirewallAlias reads a single per-VM firewall alias.

func (*VirtualMachine) GetFirewallAliases added in v0.6.0 

func (v *VirtualMachine) GetFirewallAliases(ctx context.Context) (aliases []*FirewallAlias, err error)

GetFirewallAliases lists per-VM firewall aliases.

func (*VirtualMachine) GetFirewallIPSet added in v0.2.3 

func (v *VirtualMachine) GetFirewallIPSet(ctx context.Context) (ipsets []*FirewallIPSet, err error)

func (*VirtualMachine) GetFirewallIPSetEntries added in v0.2.3 

func (v *VirtualMachine) GetFirewallIPSetEntries(ctx context.Context, name string) (entries []*FirewallIPSetEntry, err error)

func (*VirtualMachine) GetFirewallIPSetEntry added in v0.2.3 

func (v *VirtualMachine) GetFirewallIPSetEntry(ctx context.Context, name string, cidr string) (entry *FirewallIPSetEntry, err error)

func (*VirtualMachine) HasTag 

func (v *VirtualMachine) HasTag(value string) bool

func (*VirtualMachine) Hibernate 

func (v *VirtualMachine) Hibernate(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) IsHibernated 

func (v *VirtualMachine) IsHibernated() bool

func (*VirtualMachine) IsPaused 

func (v *VirtualMachine) IsPaused() bool

func (*VirtualMachine) IsRunning 

func (v *VirtualMachine) IsRunning() bool

func (*VirtualMachine) IsStopped 

func (v *VirtualMachine) IsStopped() bool

func (*VirtualMachine) Migrate 

func (v *VirtualMachine) Migrate(
	ctx context.Context,
	params *VirtualMachineMigrateOptions,
) (task *Task, err error)

func (*VirtualMachine) MigratePreconditions added in v0.6.0 

func (v *VirtualMachine) MigratePreconditions(ctx context.Context, target string) (preconditions *VirtualMachineMigratePreconditions, err error)

MigratePreconditions is the pre-flight sibling of Migrate: it returns whether the VM is movable, which target nodes accept it, and what local state (disks, PCI/USB resources, HA dependencies) would have to be moved along with it. target is optional — pass "" to query against every node in the cluster; pass a node name to scope the answer to just that target. No task is created.

func (*VirtualMachine) MigrationTunnel added in v0.6.0 

func (v *VirtualMachine) MigrationTunnel(ctx context.Context, options *VirtualMachineMigrationTunnelOptions) (tunnel *VirtualMachineMigrationTunnel, err error)

MigrationTunnel opens a migration tunnel for this VM (POST /nodes/{node}/qemu/{vmid}/mtunnel) and returns the Unix socket path, authentication ticket, and worker UPID.

PVE marks this endpoint as "for internal use by VM migration" — callers should generally use Migrate or the higher-level migration flow rather than wiring this up directly. It is wrapped here only for full API surface coverage.

func (*VirtualMachine) MigrationTunnelWebSocketPath added in v0.6.0 

func (v *VirtualMachine) MigrationTunnelWebSocketPath(tunnel *VirtualMachineMigrationTunnel) string

MigrationTunnelWebSocketPath returns the path callers can pass to a websocket dialer (or to Client.VNCWebSocket-style helpers) to upgrade the migration tunnel returned by MigrationTunnel (GET /nodes/{node}/qemu/{vmid}/mtunnelwebsocket).

PVE marks this endpoint as "for internal use by VM migration"; this helper just builds the path with the correct query string. There is no generic Client helper for migration-tunnel websockets — the protocol differs from the VNC/term tunnels — so dial it directly with the authenticated cookies/headers if you need to consume it.

func (*VirtualMachine) Monitor added in v0.4.1 

func (v *VirtualMachine) Monitor(ctx context.Context, command string) (s string, err error)

func (*VirtualMachine) MoveDisk 

func (v *VirtualMachine) MoveDisk(ctx context.Context, disk string, params *VirtualMachineMoveDiskOptions) (task *Task, err error)

func (*VirtualMachine) New added in v0.3.0 

func (v *VirtualMachine) New(c *Client, nodeName string, vmid int)

func (*VirtualMachine) NewFirewallAlias added in v0.6.0 

func (v *VirtualMachine) NewFirewallAlias(ctx context.Context, alias *FirewallAlias) error

NewFirewallAlias creates a per-VM firewall alias.

func (*VirtualMachine) NewFirewallIPSet added in v0.2.3 

func (v *VirtualMachine) NewFirewallIPSet(ctx context.Context, ipset FirewallIPSetCreationOption) error

func (*VirtualMachine) NewFirewallIPSetEntry added in v0.2.3 

func (v *VirtualMachine) NewFirewallIPSetEntry(ctx context.Context, name string, entry FirewallIPSetEntryCreationOption) error

func (*VirtualMachine) NewFirewallRule added in v0.7.0 

func (v *VirtualMachine) NewFirewallRule(ctx context.Context, rule *FirewallRule) error

NewFirewallRule creates a firewall rule on the VM. After a successful POST the rule is wired with parent context so subsequent Update/Delete/Get calls route correctly. Note: PVE's POST does not return the assigned position; callers that need it should re-list via FirewallRules.

func (*VirtualMachine) NewSnapshot 

func (v *VirtualMachine) NewSnapshot(ctx context.Context, name string) (task *Task, err error)

NewSnapshot creates a snapshot of the VM and returns the worker task. The returned snapshot's metadata is reachable via v.Snapshot(name) once the task completes.

func (*VirtualMachine) Pause 

func (v *VirtualMachine) Pause(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) Pending added in v0.2.2 

func (v *VirtualMachine) Pending(ctx context.Context) (pending *PendingConfiguration, err error)

func (*VirtualMachine) Ping 

func (v *VirtualMachine) Ping(ctx context.Context) error

func (*VirtualMachine) RRD added in v0.6.0 

func (v *VirtualMachine) RRD(ctx context.Context, ds string, timeframe Timeframe, consolidationFunction ...ConsolidationFunction) (rrd *VirtualMachineRRD, err error)

RRD asks PVE to render a single-datasource PNG on the server and returns its on-disk filename (the file lives in PVE's rrdcached directory). Most callers want RRDData instead for numeric series; this exists for API parity with the web UI's graph rendering.

func (*VirtualMachine) RRDData 

func (v *VirtualMachine) RRDData(ctx context.Context, timeframe Timeframe, consolidationFunction ...ConsolidationFunction) (rrddata []*RRDData, err error)

RRDData takes a timeframe enum and an optional consolidation function usage: vm.RRDData(HOURLY) or vm.RRDData(HOURLY, AVERAGE)

func (*VirtualMachine) Reboot 

func (v *VirtualMachine) Reboot(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) RemoteMigrate added in v0.6.0 

func (v *VirtualMachine) RemoteMigrate(ctx context.Context, params *VirtualMachineRemoteMigrateOptions) (task *Task, err error)

RemoteMigrate triggers a cross-cluster migration of this VM. The target endpoint is an API-token bundle string per PVE's pvesh docs (e.g. "apitoken=PVEAPIToken=user@pam!tok=secret host=target.example.com fingerprint=AA:BB:..."). EXPERIMENTAL upstream — the schema and behavior may change between PVE versions.

func (*VirtualMachine) RemoveTag 

func (v *VirtualMachine) RemoveTag(ctx context.Context, value string) (*Task, error)

func (*VirtualMachine) Reset 

func (v *VirtualMachine) Reset(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) ResizeDisk 

func (v *VirtualMachine) ResizeDisk(ctx context.Context, disk, size string) (*Task, error)

func (*VirtualMachine) Resume 

func (v *VirtualMachine) Resume(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) SendKey added in v0.2.4 

func (v *VirtualMachine) SendKey(ctx context.Context, key string) error

func (*VirtualMachine) Shutdown 

func (v *VirtualMachine) Shutdown(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) Snapshot added in v0.7.0 

func (v *VirtualMachine) Snapshot(name string) *VirtualMachineSnapshot

Snapshot constructs a handle to a single snapshot by name. It performs no API call; the returned *VirtualMachineSnapshot is wired to the VM's client and node/vmid so its instance methods (Rollback, Delete, Config, UpdateConfig, SubResources) target the correct snapshot path.

func (*VirtualMachine) Snapshots 

func (v *VirtualMachine) Snapshots(ctx context.Context) (snapshots []*VirtualMachineSnapshot, err error)

Snapshots lists every snapshot of the VM. Each returned *VirtualMachineSnapshot has its client/Node/VMID pre-populated so callers can invoke instance methods (Rollback, Delete, Config, …) directly.

func (*VirtualMachine) SpiceProxy added in v0.6.0 

func (v *VirtualMachine) SpiceProxy(ctx context.Context) (spice *SpiceProxy, err error)

SpiceProxy returns SPICE proxy connection info for the VM. Mirrors the Container.SpiceProxy surface and serializes the .vv file fields remote-viewer expects.

func (*VirtualMachine) SplitTags 

func (v *VirtualMachine) SplitTags()

func (*VirtualMachine) Start 

func (v *VirtualMachine) Start(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) StatusIndex added in v0.6.0 

func (v *VirtualMachine) StatusIndex(ctx context.Context) (entries []*VirtualMachineStatusIndexEntry, err error)

StatusIndex returns the VM status directory index (GET /nodes/{node}/qemu/{vmid}/status) — one entry per status sub-command (current, start, stop, reboot, …). The actual operations are wrapped as Start/Stop/Reboot/etc. on *VirtualMachine.

func (*VirtualMachine) Stop 

func (v *VirtualMachine) Stop(ctx context.Context) (task *Task, err error)

func (*VirtualMachine) TermProxy 

func (v *VirtualMachine) TermProxy(ctx context.Context) (term *Term, err error)

func (*VirtualMachine) TermWebSocket added in v0.1.2 

func (v *VirtualMachine) TermWebSocket(term *Term) (chan []byte, chan []byte, chan error, func() error, error)

func (*VirtualMachine) UnlinkDisk 

func (v *VirtualMachine) UnlinkDisk(ctx context.Context, diskID string, force bool) (task *Task, err error)

func (*VirtualMachine) UnmountCloudInitISO 

func (v *VirtualMachine) UnmountCloudInitISO(ctx context.Context, device string) error

func (*VirtualMachine) UpdateFirewallAlias added in v0.6.0 

func (v *VirtualMachine) UpdateFirewallAlias(ctx context.Context, name string, alias *FirewallAlias) error

UpdateFirewallAlias mutates an existing per-VM alias.

func (*VirtualMachine) UpdateFirewallIPSetEntry added in v0.2.3 

func (v *VirtualMachine) UpdateFirewallIPSetEntry(ctx context.Context, name string, cidr string, entry *FirewallIPSetEntryUpdateOption) error

func (*VirtualMachine) VNCProxy 

func (v *VirtualMachine) VNCProxy(ctx context.Context, config *VNCConfig) (vnc *VNC, err error)

func (*VirtualMachine) VNCWebSocket 

func (v *VirtualMachine) VNCWebSocket(vnc *VNC) (chan []byte, chan []byte, chan error, func() error, error)

VNCWebSocket copy/paste when calling to get the channel names right send, recv, errors, closer, errors := vm.VNCWebSocket(vnc) for this to work you need to first set up a serial terminal on your vm https://pve.proxmox.com/wiki/Serial_Terminal

func (*VirtualMachine) WaitForAgent 

func (v *VirtualMachine) WaitForAgent(ctx context.Context, seconds int) error

func (*VirtualMachine) WaitForAgentExecExit 

func (v *VirtualMachine) WaitForAgentExecExit(ctx context.Context, pid, seconds int) (*AgentExecStatus, error)

type VirtualMachineBackupCompress 

type VirtualMachineBackupCompress = string

type VirtualMachineBackupMode 

type VirtualMachineBackupMode = string

type VirtualMachineBackupNotificationPolicy 

type VirtualMachineBackupNotificationPolicy = string

type VirtualMachineBackupOptions 

type VirtualMachineBackupOptions struct {
	All         IntOrBool                    `json:"all,omitempty"`
	BwLimit     uint                         `json:"bwlimit,omitempty"`
	Compress    VirtualMachineBackupCompress `json:"compress,omitempty"`
	DumpDir     string                       `json:"dumpDir,omitempty"`
	Exclude     string                       `json:"exclude,omitempty"`
	ExcludePath []string                     `json:"exclude-path,omitempty"`
	// IoNice — PVE default 7 (best-effort scheduler class). A plain uint
	// zero would request realtime priority (class 0) instead of preserving
	// the configured default. See #199.
	IoNice *uint `json:"ionice,omitempty"`
	// LockWait — PVE default 180 (seconds the backup waits for the guest
	// lock). Pointer so unset doesn't drop the wait to 0. See #199.
	LockWait           *uint                                  `json:"lockwait,omitempty"`
	MailTo             string                                 `json:"mailto,omitempty"`
	Mode               VirtualMachineBackupMode               `json:"mode,omitempty"`
	Node               string                                 `json:"node,omitempty"`
	NotesTemplate      string                                 `json:"notes-template,omitempty"`
	NotificationPolicy VirtualMachineBackupNotificationPolicy `json:"notification-policy,omitempty"`
	NotificationTarget string                                 `json:"notification-target,omitempty"`
	Performance        string                                 `json:"performance,omitempty"`
	Pigz               int                                    `json:"pigz,omitempty"`
	Pool               string                                 `json:"pool,omitempty"`
	Protected          string                                 `json:"protected,omitempty"`
	// PruneBackups — PVE default "keep-all=1". Empty string would skip
	// retention entirely; pointer keeps the server policy when nil. See #199.
	PruneBackups *string   `json:"prune-backups,omitempty"`
	Quiet        IntOrBool `json:"quiet,omitempty"`
	// Remove — PVE default 1 (remove old backups per retention policy).
	// Schema is boolean; unset on the wire keeps pruning enabled. See #178 + #199.
	Remove *IntOrBool `json:"remove,omitempty"`
	Script string     `json:"script,omitempty"`
	// StdExcludes — PVE default 1 (skip /tmp, /var/log, etc.). Unset on
	// the wire keeps those default exclusions. See #178 + #199.
	StdExcludes *IntOrBool `json:"stdexcludes,omitempty"`
	StdOut      IntOrBool  `json:"stdout,omitempty"`
	Stop        IntOrBool  `json:"stop,omitempty"`
	// StopWait — PVE default 10 (minutes to wait for a guest shutdown in
	// "stop" mode). Pointer so unset doesn't drop the wait to 0. See #199.
	StopWait *uint  `json:"stopwait,omitempty"`
	Storage  string `json:"storage,omitempty"`
	TmpDir   string `json:"tmpdir,omitempty"`
	VMID     uint64 `json:"vmid,omitempty"`
	// Zstd — PVE default 1 (zstd worker thread count). Pointer so unset
	// doesn't disable parallel compression. See #199.
	Zstd *uint `json:"zstd,omitempty"`
}

type VirtualMachineCloneOptions 

type VirtualMachineCloneOptions struct {
	NewID int `json:"newid"`
	// BWLimit — PVE default is the datacenter/storage clone limit. Pointer
	// keeps the configured default when nil. See #199.
	BWLimit     *uint64   `json:"bwlimit,omitempty"`
	Description string    `json:"description,omitempty"`
	Format      string    `json:"format,omitempty"`
	Full        IntOrBool `json:"full,omitempty"`
	Name        string    `json:"name,omitempty"`
	Pool        string    `json:"pool,omitempty"`
	SnapName    string    `json:"snapname,omitempty"`
	Storage     string    `json:"storage,omitempty"`
	Target      string    `json:"target,omitempty"`
}

type VirtualMachineCloudInitPending added in v0.6.0 

type VirtualMachineCloudInitPending struct {
	Delete  IntOrBool `json:"delete,omitempty"`
	Key     string    `json:"key,omitempty"`
	Pending string    `json:"pending,omitempty"`
	Value   string    `json:"value,omitempty"`
}

VirtualMachineCloudInitPending is one row from GET /qemu/{vmid}/cloudinit — a single config key with its currently-applied value and a pending value if a regenerate is needed. Delete=1 means the key is pending removal.

type VirtualMachineConfig 

type VirtualMachineConfig struct {
	// PVE Metadata
	Digest      string `json:"digest"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Meta        string `json:"meta,omitempty"`
	// VMGenID — PVE default "1 (autogenerated)". A non-pointer string would
	// either be silently dropped (omitempty) or, if cleared, change the
	// guest's generation ID. Pointer keeps the server value when nil. See #199.
	VMGenID    *string `json:"vmgenid,omitempty"`
	Hookscript string  `json:"hookscript,omitempty"`
	// Hotplug — PVE default "network,disk,usb". Empty-string overrides would
	// silently disable hotplug subsystems on edit. See #199.
	Hotplug   *string   `json:"hotplug,omitempty"`
	Template  IntOrBool `json:"template,omitempty"`
	Agent     string    `json:"agent,omitempty"`
	Autostart IntOrBool `json:"autostart,omitempty"`
	// Tablet — PVE default 1 (USB tablet enabled for absolute pointer).
	// Schema is boolean; a plain int defaults to 0 and would silently
	// disable the tablet device on partial updates. See #178 + #199.
	Tablet *IntOrBool `json:"tablet,omitempty"`
	// KVM — PVE default 1 (hardware virtualization enabled). Disabling KVM
	// drops performance to TCG emulation; pointer prevents a missing field
	// from forcing that downgrade on edit. See #178 + #199.
	KVM *IntOrBool `json:"kvm,omitempty"`

	Tags      string   `json:"tags,omitempty"`
	TagsSlice []string `json:"-"` // internal helper to manage tags easier

	Protection IntOrBool `json:"protection,omitempty"`
	Lock       string    `json:"lock,omitempty"`

	// Boot configuration
	Boot   string    `json:"boot,omitempty"`
	OnBoot IntOrBool `json:"onboot,omitempty"`

	// Qemu general specs
	// OSType — PVE default "other". The OS type drives default device
	// choices (BIOS, NIC model, machine type); pointer keeps the server's
	// value when the caller hasn't explicitly set one. See #199.
	OSType  *string `json:"ostype,omitempty"`
	Machine string  `json:"machine,omitempty"`
	Args    string  `json:"args,omitempty"`

	// Qemu firmware specs
	// Bios — PVE default "seabios". Switching to/from OVMF requires an
	// EFIDisk so accidentally clearing this on edit can leave a VM
	// unbootable. Pointer keeps the server default when nil. See #199.
	Bios     *string `json:"bios,omitempty"`
	EFIDisk0 string  `json:"efidisk0,omitempty"`
	SMBios1  string  `json:"smbios1,omitempty"`
	// Acpi — PVE default 1 (ACPI enabled). Without ACPI most guests can't
	// receive shutdown signals; pointer prevents an unset field from
	// disabling ACPI on edit. See #178 + #199.
	Acpi *IntOrBool `json:"acpi,omitempty"`

	// Qemu CPU specs
	// Sockets — PVE default 1. A plain int zero would attempt to set 0
	// sockets, which the API rejects; pointer keeps the server default. See #199.
	Sockets *int `json:"sockets,omitempty"`
	// Cores — PVE default 1. Same trap as Sockets. See #199.
	Cores    *int             `json:"cores,omitempty"`
	CPU      string           `json:"cpu,omitempty"`
	CPULimit *StringOrFloat64 `json:"cpulimit,omitempty"`
	// CPUUnits — PVE default 1024 (cgroup v1) / 100 (cgroup v2). Plain int
	// would default to 0 and override the server's CPU weight on edit. See #199.
	CPUUnits *int   `json:"cpuunits,omitempty"`
	Vcpus    int    `json:"vcpus,omitempty"`
	Affinity string `json:"affinity,omitempty"`

	// Qemu memory specs
	Numa      IntOrBool   `json:"numa,omitempty"`
	Memory    StringOrInt `json:"memory,omitempty"` // See commit 7f8c808772979f274cdfac1dc7264771a3b7a7ae on qemu-server
	Hugepages string      `json:"hugepages,omitempty"`
	Balloon   int         `json:"balloon,omitempty"`

	// Other Qemu devices
	VGA string `json:"vga,omitempty"`
	// SCSIHW — PVE default "lsi". Changing the SCSI controller on an
	// existing VM can break disk visibility; pointer keeps the server's
	// controller when nil. See #199.
	SCSIHW    *string `json:"scsihw,omitempty"`
	TPMState0 string  `json:"tpmstate0,omitempty"`
	Rng0      string  `json:"rng0,omitempty"`
	Audio0    string  `json:"audio0,omitempty"`

	// Indexed devices. Populated by UnmarshalJSON from the raw JSON object;
	// keys are the on-the-wire form ("net0", "scsi30", "ipconfig20", ...).
	// See indexedDeviceMaps below for the full list of routed prefixes and
	// indexedDeviceKey for the prefix-then-pure-digits matching rule that
	// keeps "scsihw" out of SCSIs and the bare "numa" scalar out of Numas.
	IDEs      map[string]string `json:"-"`
	SCSIs     map[string]string `json:"-"`
	SATAs     map[string]string `json:"-"`
	VirtIOs   map[string]string `json:"-"`
	Unuseds   map[string]string `json:"-"`
	Nets      map[string]string `json:"-"`
	Numas     map[string]string `json:"-"`
	HostPCIs  map[string]string `json:"-"`
	Serials   map[string]string `json:"-"`
	USBs      map[string]string `json:"-"`
	Parallels map[string]string `json:"-"`
	IPConfigs map[string]string `json:"-"`

	// Cloud-init
	CIType       string `json:"citype,omitempty"`
	CIUser       string `json:"ciuser,omitempty"`
	CIPassword   string `json:"cipassword,omitempty"`
	Nameserver   string `json:"nameserver,omitempty"`
	Searchdomain string `json:"searchdomain,omitempty"`
	// SSHKeys must be encoded with EncodeSSHKeys — PVE's API validator
	// rejects loose url-encoding (e.g. '+' for spaces). See issue #144.
	SSHKeys  string `json:"sshkeys,omitempty"`
	CICustom string `json:"cicustom,omitempty"`
	// CIUpgrade — PVE wire type is "boolean" with default 1 (upgrade on
	// first boot). A plain int both type-mismatches the schema and silently
	// disables the upgrade whenever the caller didn't set the field. Pointer
	// keeps the server default when nil. See #178 (type) and #199 (default).
	CIUpgrade *IntOrBool `json:"ciupgrade,omitempty"`
}

func (*VirtualMachineConfig) MergeDisks 

func (vmc *VirtualMachineConfig) MergeDisks() map[string]string

MergeDisks returns every disk attached to the VM as a single map keyed by its on-the-wire name (e.g. "ide0", "scsi3", "sata1", "virtio7"), combining IDEs, SCSIs, SATAs, and VirtIOs.

func (*VirtualMachineConfig) UnmarshalJSON added in v0.4.1 

func (vmc *VirtualMachineConfig) UnmarshalJSON(data []byte) error

type VirtualMachineDeleteOptions added in v0.8.0 

type VirtualMachineDeleteOptions struct {
	SkipLock                 IntOrBool `json:"skiplock,omitempty"`
	Purge                    IntOrBool `json:"purge,omitempty"`
	DestroyUnreferencedDisks IntOrBool `json:"destroy-unreferenced-disks,omitempty"`
}

VirtualMachineDeleteOptions maps to the optional query parameters that DELETE /nodes/{node}/qemu/{vmid} accepts. A nil *VirtualMachineDeleteOptions passed to VirtualMachine.Delete is equivalent to all defaults.

type VirtualMachineDirIndexEntry added in v0.6.0 

type VirtualMachineDirIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

VirtualMachineDirIndexEntry is one row in the per-VM directory index (GET /nodes/{node}/qemu/{vmid}) — each entry names a child resource (config, status, snapshot, firewall, agent, …).

type VirtualMachineFeature added in v0.6.0 

type VirtualMachineFeature struct {
	HasFeature bool     `json:"hasFeature"`
	Nodes      []string `json:"nodes,omitempty"`
}

VirtualMachineFeature is the response payload of GET /nodes/{node}/qemu/{vmid}/feature. HasFeature reports whether the requested feature is available for the VM (and optional snapshot); Nodes lists the cluster nodes on which the feature is available.

type VirtualMachineMigrateOptions 

type VirtualMachineMigrateOptions struct {
	Target string `json:"target"`
	// BWLimit — PVE default is the datacenter/storage migrate bandwidth
	// limit. A plain uint64 zero would suppress all rate-limiting on this
	// call; pointer keeps the datacenter default when nil. See #199.
	BWLimit          *uint64   `json:"bwlimit,omitempty"`
	Force            IntOrBool `json:"force,omitempty"`
	MigrationNetwork string    `json:"migration_network,omitempty"`
	MigrationType    string    `json:"migration_type,omitempty"`
	Online           IntOrBool `json:"online,omitempty"`
	TargetStorage    string    `json:"targetstorage,omitempty"`
	WithLocalDisks   IntOrBool `json:"with-local-disks,omitempty"`
}

type VirtualMachineMigratePreconditions added in v0.6.0 

type VirtualMachineMigratePreconditions struct {
	Running              bool                                                          `json:"running"`
	HasDBusVMState       bool                                                          `json:"has-dbus-vmstate"`
	AllowedNodes         []string                                                      `json:"allowed_nodes,omitempty"`
	NotAllowedNodes      map[string]*VirtualMachineMigratePreconditionsNotAllowedNodes `json:"not_allowed_nodes,omitempty"`
	LocalDisks           []*VirtualMachineMigratePreconditionsLocalDisk                `json:"local_disks,omitempty"`
	LocalResources       []string                                                      `json:"local_resources,omitempty"`
	MappedResources      []string                                                      `json:"mapped-resources,omitempty"`
	MappedResourceInfo   map[string]interface{}                                        `json:"mapped-resource-info,omitempty"`
	DependentHAResources []string                                                      `json:"dependent-ha-resources,omitempty"`
}

VirtualMachineMigratePreconditions is the response from GET /nodes/{node}/qemu/{vmid}/migrate — a dry-run summary of whether the VM can be migrated, which nodes accept it, and what local state would have to be moved along with it. Pre-flight only; no task is created.

type VirtualMachineMigratePreconditionsBlockingHAResource added in v0.6.0 

type VirtualMachineMigratePreconditionsBlockingHAResource struct {
	SID   string `json:"sid"`
	Cause string `json:"cause"` // "node-affinity" or "resource-affinity"
}

VirtualMachineMigratePreconditionsBlockingHAResource identifies a HA resource preventing the VM from migrating to a particular node.

type VirtualMachineMigratePreconditionsLocalDisk added in v0.6.0 

type VirtualMachineMigratePreconditionsLocalDisk struct {
	VolID    string `json:"volid"`
	Size     uint64 `json:"size,omitempty"`
	CDROM    bool   `json:"cdrom,omitempty"`
	IsUnused bool   `json:"is_unused,omitempty"`
}

VirtualMachineMigratePreconditionsLocalDisk describes one local disk surfaced by GET /nodes/{node}/qemu/{vmid}/migrate. Local disks block live migration unless WithLocalDisks is enabled on Migrate.

type VirtualMachineMigratePreconditionsNotAllowedNodes added in v0.6.0 

type VirtualMachineMigratePreconditionsNotAllowedNodes struct {
	UnavailableStorages []string                                                `json:"unavailable_storages,omitempty"`
	BlockingHAResources []*VirtualMachineMigratePreconditionsBlockingHAResource `json:"blocking-ha-resources,omitempty"`
}

VirtualMachineMigratePreconditionsNotAllowedNodes carries the per-node reasons a target node is rejected for migration.

type VirtualMachineMigrationTunnel added in v0.6.0 

type VirtualMachineMigrationTunnel struct {
	Socket string `json:"socket,omitempty"`
	Ticket string `json:"ticket,omitempty"`
	UPID   string `json:"upid,omitempty"`
}

VirtualMachineMigrationTunnel is the response from POST /nodes/{node}/qemu/{vmid}/mtunnel — a Unix socket path plus an authentication ticket the caller can use with the mtunnelwebsocket endpoint. PVE marks this endpoint as "for internal use by VM migration".

type VirtualMachineMigrationTunnelOptions added in v0.6.0 

type VirtualMachineMigrationTunnelOptions struct {
	// Bridges is a comma-separated list of network bridges to check
	// availability for. Optional.
	Bridges string `json:"bridges,omitempty"`
	// Storages is a comma-separated list of storages to check permission
	// and availability for. Optional.
	Storages string `json:"storages,omitempty"`
}

VirtualMachineMigrationTunnelOptions is the request body for POST /nodes/{node}/qemu/{vmid}/mtunnel.

type VirtualMachineMoveDiskOptions 

type VirtualMachineMoveDiskOptions struct {
	Disk string `json:"disk"`
	// BWLimit — PVE default is the datacenter/storage move limit. Pointer
	// keeps the configured default when nil. See #199.
	BWLimit      *uint64   `json:"bwlimit,omitempty"`
	Delete       IntOrBool `json:"delete,omitempty"`
	Digest       string    `json:"digest,omitempty"`
	Format       string    `json:"format,omitempty"`
	Storage      string    `json:"storage,omitempty"`
	TargetDigest string    `json:"target-digest,omitempty"`
	TargetDisk   string    `json:"target-disk,omitempty"`
	TargetVMID   int       `json:"target-vmid,omitempty"`
}

type VirtualMachineOption 

type VirtualMachineOption struct {
	Name  string
	Value interface{}
}

type VirtualMachineOptions 

type VirtualMachineOptions []*VirtualMachineOption

VirtualMachineOptions A key/value pair used to modify a virtual machine config Refer to https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/qemu/{vmid}/config for a list of valid values

type VirtualMachineRRD added in v0.6.0 

type VirtualMachineRRD struct {
	Filename string `json:"filename"`
}

VirtualMachineRRD is the response from GET /nodes/{node}/qemu/{vmid}/rrd. PVE renders a single PNG on the server (one datasource per call) and returns its on-disk filename; callers typically want RRDData instead for usable numeric series.

type VirtualMachineRemoteMigrateOptions added in v0.6.0 

type VirtualMachineRemoteMigrateOptions struct {
	TargetEndpoint string    `json:"target-endpoint"`
	TargetBridge   string    `json:"target-bridge"`
	TargetStorage  string    `json:"target-storage"`
	TargetVMID     int       `json:"target-vmid,omitempty"`
	BWLimit        uint64    `json:"bwlimit,omitempty"`
	Delete         IntOrBool `json:"delete,omitempty"`
	Online         IntOrBool `json:"online,omitempty"`
}

VirtualMachineRemoteMigrateOptions configures POST /nodes/{node}/qemu/{vmid}/remote_migrate (cross-cluster VM migration — flagged EXPERIMENTAL upstream). TargetEndpoint is the API-token bundle string PVE accepts ("apitoken=PVEAPIToken=... host=... fingerprint=..."); see the pvesh docs for the exact shape. TargetBridge and TargetStorage are "src=tgt,src2=tgt2" pair-list maps; the special value "1" maps each source to itself.

type VirtualMachineSnapshot added in v0.7.0 

type VirtualMachineSnapshot struct {

	// Node is the cluster node that hosts the parent VM. Populated by the
	// getter and not part of the upstream JSON payload.
	Node string `json:"-"`
	// VMID is the parent VM's numeric id. Populated by the getter and not
	// part of the upstream JSON payload.
	VMID int `json:"-"`

	Name        string
	Vmstate     int
	Description string
	Snaptime    int64
	Parent      string
	Snapstate   string
	// contains filtered or unexported fields
}

VirtualMachineSnapshot is one entry from GET /nodes/{node}/qemu/{vmid}/snapshot. The unexported client and the parent-identifying Node/VMID fields are populated by (*VirtualMachine).Snapshots and (*VirtualMachine).Snapshot so callers can invoke instance methods (Rollback, Delete, Config, UpdateConfig, SubResources) without re-threading those identifiers.

func (*VirtualMachineSnapshot) Config added in v0.7.0 

func (s *VirtualMachineSnapshot) Config(ctx context.Context) (config map[string]interface{}, err error)

Config reads this snapshot's metadata (description, parent, etc.). PVE returns a free-form map since snapshot configs include arbitrary device keys snapshotted at the time of creation.

func (*VirtualMachineSnapshot) Delete added in v0.7.0 

func (s *VirtualMachineSnapshot) Delete(ctx context.Context) (task *Task, err error)

Delete removes this snapshot from the VM. Returns the worker task.

func (*VirtualMachineSnapshot) Rollback added in v0.7.0 

func (s *VirtualMachineSnapshot) Rollback(ctx context.Context) (task *Task, err error)

Rollback rolls the VM back to this snapshot. Returns the worker task.

func (*VirtualMachineSnapshot) SubResources added in v0.7.0 

func (s *VirtualMachineSnapshot) SubResources(ctx context.Context) (entries []*VirtualMachineSnapshotIndexEntry, err error)

SubResources returns the per-snapshot directory index (GET /nodes/{node}/qemu/{vmid}/snapshot/{snapname}) — one entry per sub-resource (config, rollback) on this snapshot.

func (*VirtualMachineSnapshot) UpdateConfig added in v0.7.0 

func (s *VirtualMachineSnapshot) UpdateConfig(ctx context.Context, options *VirtualMachineSnapshotUpdateOptions) error

UpdateConfig updates this snapshot's metadata. PVE only allows changing the description on this endpoint; pass nil options to clear it.

type VirtualMachineSnapshotIndexEntry added in v0.6.0 

type VirtualMachineSnapshotIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

VirtualMachineSnapshotIndexEntry is one row in the per-snapshot directory index (GET /nodes/{node}/qemu/{vmid}/snapshot/{snapname}) — each entry names a sub-resource on the snapshot (config, rollback).

type VirtualMachineSnapshotUpdateOptions added in v0.6.0 

type VirtualMachineSnapshotUpdateOptions struct {
	Description string `json:"description,omitempty"`
}

VirtualMachineSnapshotUpdateOptions is the body for PUT /qemu/{vmid}/snapshot/{name}/config. PVE only lets you change the description through this endpoint.

type VirtualMachineStatusIndexEntry added in v0.6.0 

type VirtualMachineStatusIndexEntry struct {
	Subdir string `json:"subdir,omitempty"`
}

VirtualMachineStatusIndexEntry is one row in the VM status directory index (GET /nodes/{node}/qemu/{vmid}/status) — each entry names a status sub-command (current, start, stop, reboot, …).

type VirtualMachines 

type VirtualMachines []*VirtualMachine

type Volume 

type Volume interface {
	Delete() error
}

type VzTmpl 

type VzTmpl struct{ Content }

func (*VzTmpl) Delete 

func (v *VzTmpl) Delete(ctx context.Context) (*Task, error)

type VzTmpls 

type VzTmpls []*VzTmpl

type VzdumpConfig 

type VzdumpConfig struct {
	Boot       string `json:"boot"`
	CiPassword string `json:"cipassword"`
	CiUser     string `json:"ciuser"`
	Cores      uint64 `json:"cores,string"`
	Memory     uint64 `json:"memory,string"`
	Meta       string `json:"meta"`
	Numa       string `json:"numa"`
	OsType     string `json:"ostype"`
	Scsihw     string `json:"scsihw"`
	Sockets    uint64 `json:"sockets,string"`
	// SSHKeys is reflected back from VzDump's recorded VM config; if you
	// round-trip this into a VirtualMachineConfig.SSHKeys, the value is
	// already PVE-encoded — re-encoding it would double-encode. See #144.
	SSHKeys string `json:"sshkeys"`
	VmgenID string `json:"vmgenid"`

	IDE0 string `json:"ide0,omitempty"`
	IDE1 string `json:"ide1,omitempty"`
	IDE2 string `json:"ide2,omitempty"`
	IDE3 string `json:"ide3,omitempty"`

	SCSI0  string `json:"scsi0,omitempty"`
	SCSI1  string `json:"scsi1,omitempty"`
	SCSI2  string `json:"scsi2,omitempty"`
	SCSI3  string `json:"scsi3,omitempty"`
	SCSI4  string `json:"scsi4,omitempty"`
	SCSI5  string `json:"scsi5,omitempty"`
	SCSI6  string `json:"scsi6,omitempty"`
	SCSI7  string `json:"scsi7,omitempty"`
	SCSI8  string `json:"scsi8,omitempty"`
	SCSI9  string `json:"scsi9,omitempty"`
	SCSI10 string `json:"scsi10,omitempty"`
	SCSI11 string `json:"scsi11,omitempty"`
	SCSI12 string `json:"scsi12,omitempty"`
	SCSI13 string `json:"scsi13,omitempty"`
	SCSI14 string `json:"scsi14,omitempty"`
	SCSI15 string `json:"scsi15,omitempty"`
	SCSI16 string `json:"scsi16,omitempty"`
	SCSI17 string `json:"scsi17,omitempty"`
	SCSI18 string `json:"scsi18,omitempty"`
	SCSI19 string `json:"scsi19,omitempty"`
	SCSI20 string `json:"scsi20,omitempty"`
	SCSI21 string `json:"scsi21,omitempty"`
	SCSI22 string `json:"scsi22,omitempty"`
	SCSI23 string `json:"scsi23,omitempty"`
	SCSI24 string `json:"scsi24,omitempty"`
	SCSI25 string `json:"scsi25,omitempty"`
	SCSI26 string `json:"scsi26,omitempty"`
	SCSI27 string `json:"scsi27,omitempty"`
	SCSI28 string `json:"scsi28,omitempty"`
	SCSI29 string `json:"scsi29,omitempty"`
	SCSI30 string `json:"scsi30,omitempty"`

	SATA0 string `json:"sata0,omitempty"`
	SATA1 string `json:"sata1,omitempty"`
	SATA2 string `json:"sata2,omitempty"`
	SATA3 string `json:"sata3,omitempty"`
	SATA4 string `json:"sata4,omitempty"`
	SATA5 string `json:"sata5,omitempty"`

	VirtIO0  string `json:"virtio0,omitempty"`
	VirtIO1  string `json:"virtio1,omitempty"`
	VirtIO2  string `json:"virtio2,omitempty"`
	VirtIO3  string `json:"virtio3,omitempty"`
	VirtIO4  string `json:"virtio4,omitempty"`
	VirtIO5  string `json:"virtio5,omitempty"`
	VirtIO6  string `json:"virtio6,omitempty"`
	VirtIO7  string `json:"virtio7,omitempty"`
	VirtIO8  string `json:"virtio8,omitempty"`
	VirtIO9  string `json:"virtio9,omitempty"`
	VirtIO10 string `json:"virtio10,omitempty"`
	VirtIO11 string `json:"virtio11,omitempty"`
	VirtIO12 string `json:"virtio12,omitempty"`
	VirtIO13 string `json:"virtio13,omitempty"`
	VirtIO14 string `json:"virtio14,omitempty"`
	VirtIO15 string `json:"virtio15,omitempty"`

	Unused0 string `json:"unused0,omitempty"`
	Unused1 string `json:"unused1,omitempty"`
	Unused2 string `json:"unused2,omitempty"`
	Unused3 string `json:"unused3,omitempty"`
	Unused4 string `json:"unused4,omitempty"`
	Unused5 string `json:"unused5,omitempty"`
	Unused6 string `json:"unused6,omitempty"`
	Unused7 string `json:"unused7,omitempty"`
	Unused8 string `json:"unused8,omitempty"`
	Unused9 string `json:"unused9,omitempty"`

	// Network devices
	Net0 string `json:"net0,omitempty"`
	Net1 string `json:"net1,omitempty"`
	Net2 string `json:"net2,omitempty"`
	Net3 string `json:"net3,omitempty"`
	Net4 string `json:"net4,omitempty"`
	Net5 string `json:"net5,omitempty"`
	Net6 string `json:"net6,omitempty"`
	Net7 string `json:"net7,omitempty"`
	Net8 string `json:"net8,omitempty"`
	Net9 string `json:"net9,omitempty"`

	// NUMA topology
	Numa0 string `json:"numa0,omitempty"`
	Numa1 string `json:"numa1,omitempty"`
	Numa2 string `json:"numa2,omitempty"`
	Numa3 string `json:"numa3,omitempty"`
	Numa4 string `json:"numa4,omitempty"`
	Numa5 string `json:"numa5,omitempty"`
	Numa6 string `json:"numa6,omitempty"`
	Numa7 string `json:"numa7,omitempty"`
	Numa8 string `json:"numa8,omitempty"`
	Numa9 string `json:"numa9,omitempty"`

	// Host PCI devices
	HostPCI0 string `json:"hostpci0,omitempty"`
	HostPCI1 string `json:"hostpci1,omitempty"`
	HostPCI2 string `json:"hostpci2,omitempty"`
	HostPCI3 string `json:"hostpci3,omitempty"`
	HostPCI4 string `json:"hostpci4,omitempty"`
	HostPCI5 string `json:"hostpci5,omitempty"`
	HostPCI6 string `json:"hostpci6,omitempty"`
	HostPCI7 string `json:"hostpci7,omitempty"`
	HostPCI8 string `json:"hostpci8,omitempty"`
	HostPCI9 string `json:"hostpci9,omitempty"`

	// Serial devices
	Serial0 string `json:"serial0,omitempty"`
	Serial1 string `json:"serial1,omitempty"`
	Serial2 string `json:"serial2,omitempty"`
	Serial3 string `json:"serial3,omitempty"`

	// USB devices
	USB0  string `json:"usb0,omitempty"`
	USB1  string `json:"usb1,omitempty"`
	USB2  string `json:"usb2,omitempty"`
	USB3  string `json:"usb3,omitempty"`
	USB4  string `json:"usb4,omitempty"`
	USB5  string `json:"usb5,omitempty"`
	USB6  string `json:"usb6,omitempty"`
	USB7  string `json:"usb7,omitempty"`
	USB8  string `json:"usb8,omitempty"`
	USB9  string `json:"usb9,omitempty"`
	USB10 string `json:"usb10,omitempty"`
	USB11 string `json:"usb11,omitempty"`
	USB12 string `json:"usb12,omitempty"`
	USB13 string `json:"usb13,omitempty"`
	USB14 string `json:"usb14,omitempty"`

	Parallel0 string `json:"parallel0,omitempty"`
	Parallel1 string `json:"parallel1,omitempty"`
	Parallel2 string `json:"parallel2,omitempty"`

	// Cloud-init
	IPConfig0 string `json:"ipconfig0,omitempty"`
	IPConfig1 string `json:"ipconfig1,omitempty"`
	IPConfig2 string `json:"ipconfig2,omitempty"`
	IPConfig3 string `json:"ipconfig3,omitempty"`
	IPConfig4 string `json:"ipconfig4,omitempty"`
	IPConfig5 string `json:"ipconfig5,omitempty"`
	IPConfig6 string `json:"ipconfig6,omitempty"`
	IPConfig7 string `json:"ipconfig7,omitempty"`
	IPConfig8 string `json:"ipconfig8,omitempty"`
	IPConfig9 string `json:"ipconfig9,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
mage
endpoints
Package endpoints provides mage targets that snapshot the upstream Proxmox VE REST API surface (apidoc.js) and flatten it into a (method, path) list, so the library's wrapper coverage can be diffed against the canonical schema.
 Package endpoints provides mage targets that snapshot the upstream Proxmox VE REST API surface (apidoc.js) and flatten it into a (method, path) list, so the library's wrapper coverage can be diffed against the canonical schema.
install
test
tests
mocks
mocks/capture
Package capture wires gock matchers that record details of intercepted requests so tests can assert on the body of multipart uploads (which gock can't match natively).
 Package capture wires gock matchers that record details of intercepted requests so tests can assert on the body of multipart uploads (which gock can't match natively).
mocks/config
mocks/pve6x
mocks/pve7x
mocks/pve8x
mocks/pve9x

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.