Skip to content

pve

import "github.com/iolave/go-proxmox/pkg/pve"

Constants

Credentials error messages.

const (
    CREDENTIALS_NOT_DETECTED_ERROR    = "credentials could not be detected from env"
    CREDENTIALS_NOT_SUPPORTED_ERROR   = "credentials type not supported yet"
    CREDENTIALS_MISSING_REQUEST_ERROR = "*http.Request parameter is nil"
)

type Config

type Config struct {
    Host               string
    Port               int
    InsecureSkipVerify bool
    CfServiceToken     *cloudflare.ServiceToken
}

type CreateLxcRequest

type CreateLxcRequest struct {
    Node               string          // The cluster node name.
    OSTemplate         string          // The OS template or backup file (in format "{STORAGE_ID}:{TYPE}/{TEMPLATE_NAME}", i.e. "local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst")
    VMID               *int            // The (unique) ID of the VM.
    Arch               *LxcArch        // OS architecture type.
    BWLimit            *int            // Override I/O bandwidth limit (in KiB/s).
    CMode              *LxcConsoleMode // Console mode. By default, the console command tries to open a connection to one of the available tty devices. By setting cmode to 'console' it tries to attach to /dev/console instead. If you set cmode to 'shell', it simply invokes a shell inside the container (no login).
    Console            *bool           // Attach a console device (/dev/console) to the container.
    Cores              *int            // The number of cores assigned to the container. A container can use all available cores by default.
    CPULimit           *int            // Limit of CPU usage. NOTE: If the computer has 2 CPUs, it has a total of '2' CPU time. Value '0' indicates no CPU limit.
    CPUUnits           *int            // CPU weight for a container. Argument is used in the kernel fair scheduler. The larger the number is, the more CPU time this container gets. Number is relative to the weights of all the other running guests.
    Debug              *bool           // Try to be more verbose. For now this only enables debug log-level on start.
    Desc               *string         // Description for the Container. Shown in the web-interface CT's summary. This is saved as comment inside the configuration file.
    Features           *string         // Allow containers access to advanced features.
    Force              *bool           // Allow to overwrite existing container.
    Hookscript         *string         // Script that will be exectued during various steps in the containers lifetime.
    Hostname           *string         // Set a host name for the container.
    IgnoreUnpackErrors *bool           // Ignore errors when extracting the template.
    Lock               *LxcLock        // Lock/unlock the container.
    Memory             *int            // Amount of RAM for the container in MB.
    Nameserver         *string         // Sets DNS server IP address for a container. Create will automatically use the setting from the host if you neither set searchdomain nor nameserver.
    Net                *[]LxcNet       // Specifies network interfaces for the container.
    OnBoot             *bool           // Specifies whether a container will be started during system bootup.
    OSType             *string         // OS type. This is used to setup configuration inside the container, and corresponds to lxc setup scripts in /usr/share/lxc/config/<ostype>.common.conf. Value 'unmanaged' can be used to skip and OS specific setup. debian | devuan | ubuntu | centos | fedora | opensuse | archlinux | alpine | gentoo | nixos | unmanaged
    Password           *string         // Sets root password inside container.
    Pool               *string         // Add the VM to the specified pool.
    Protection         *bool           // Sets the protection flag of the container. This will prevent the CT or CT's disk remove/update operation.
    Restore            *bool           // Mark this as restore task.
    RootFS             *string         // Use volume as container root (in format "{STORAGE_ID}:{SIZE_IN_GIGS}", i.e. "local-lvm:8", if value not specified it defaults to "local-lvm:8", TODO: make this a struct).
    Searchdomain       *string         // Sets DNS search domains for a container. Create will automatically use the setting from the host if you neither set searchdomain nor nameserver.
    SSHPublicKeys      *string         // Setup public SSH keys (one key per line, OpenSSH format).
    Start              *bool           // Start the CT after its creation finished successfully.
    Startup            *string         // make this a struct Startup and shutdown behavior. Order is a non-negative number defining the general startup order. Shutdown in done with reverse ordering. Additionally you can set the 'up' or 'down' delay in seconds, which specifies a delay to wait before the next VM is started or stopped.
    Storage            *string         // Default Storage.
    Swap               *int            // Amount of SWAP for the container in MB.
    Tags               *string         // Tags of the Container. This is only meta information.
    Template           *bool           // Enable/disable Template.
    Timezone           *string         // Time zone to use in the container. If option isn't set, then nothing will be done. Can be set to 'host' to match the host time zone, or an arbitrary time zone option from /usr/share/zoneinfo/zone.tab
    TTY                *int            // Specify the number of tty available to the container.
    Unique             *bool           // Assign a unique random ethernet address.
    Unprivileged       *bool           // Makes the container run as unprivileged user. (Should not be modified manually.)

}

type CreateLxcResponse

type CreateLxcResponse struct {
    VMID int // LXC container id within proxmox.
}

type CredentialType

Proxmox api client available credential types

type CredentialType int

TODO: Add CREDENTIALS_PASSWORD support

const (
    CREDENTIALS_TOKEN CredentialType = iota
    CREDENTIALS_PASSWORD
)

type Credentials

Credentials store proxmox api credentials.

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

func NewEnvCreds

func NewEnvCreds() (*Credentials, error)

NewEnvCreds get environment variables values and detects the type of credentials based on which envs are configured.

It returns an error when a credential type is not detected.

func NewTokenCreds

func NewTokenCreds(user, tokenName, token string) *Credentials

NewTokenCreds returns a struct containing proxmox token credentials that can be passed to a pve api constructor.

To create a pve token, read the docs.

func (*Credentials) Set

func (c *Credentials) Set(req *http.Request) error

Set adds the corresponding PVE authorization headers to the req parameter.

* It returns an error with the CREDENTIALS\_MISSING\_REQUEST\_ERROR message when nil is passed to the req parameter.

* It returns an error with the CREDENTIALS\_NOT\_SUPPORTED\_ERROR message when CredentialType is not supported.

type FirewallLogEntry

Proxmox firewall log entry.

type FirewallLogEntry struct {
    Id   int    `json:"n"`
    Text string `json:"t"`
}

type FirewallLogLevel

Promox firewall available log levels.

type FirewallLogLevel string


const (
    FIREWALL_LOG_LEVEL_EMERG  FirewallLogLevel = "emerg"
    FIREWALL_LOG_LEVEL_ALERT  FirewallLogLevel = "alert"
    FIREWALL_LOG_LEVEL_CRIT   FirewallLogLevel = "crit"
    FIREWALL_LOG_LEVEL_ERR    FirewallLogLevel = "err"
    FIREWALL_LOG_LEVEL_WARN   FirewallLogLevel = "warning"
    FIREWALL_LOG_LEVEL_NOTICE FirewallLogLevel = "notice"
    FIREWALL_LOG_LEVEL_INFO   FirewallLogLevel = "info"
    FIREWALL_LOG_LEVEL_DEBUG  FirewallLogLevel = "debug"
    FIREWALL_LOG_LEVEL_NOLOG  FirewallLogLevel = "nolog"
)

type GetClusterFirewallAliasesResponse

type GetClusterFirewallAliasesResponse struct {
    CIDR    string `json:"cidr"`
    Digest  string `json:"digest"`
    Name    string `json:"name"`
    Comment string `json:"comment"`
}

type GetClusterFirewallIPSetResponse

type GetClusterFirewallIPSetResponse struct {
    Digest  string `json:"digest"`
    Name    string `json:"name"`
    Comment string `json:"comment"`
}

type GetClusterFirewallRulesResponse

type GetClusterFirewallRulesResponse struct {
    Pos int `json:"pos"`
}

type GetNodeDatastoreContentResponse

TODO: Add missing verification property from docs.

type GetNodeDatastoreContentResponse struct {
    Format    string  `json:"format"`    // Format identifier ('raw', 'qcow2', 'subvol', 'iso', 'tgz' ...)
    Size      int     `json:"size"`      // Volume size in bytes.
    VolumeID  string  `json:"volid"`     // Volume identifier.
    CreatedAt *int    `json:"ctime"`     // Creation time (seconds since the UNIX Epoch).
    Encrypted *string `json:"encrypted"` // If whole backup is encrypted, value is the fingerprint or '1'  if encrypted. Only useful for the Proxmox Backup Server storage type.
    Notes     *string `json:"notes"`     // Optional notes. If they contain multiple lines, only the first one is returned here.
    Parent    *string `json:"parent"`    // Volume identifier of parent (for linked cloned).
    Protected *bool   `json:"protected"` // Protection status. Currently only supported for backups.
    Used      *int    `json:"used"`      // Used space. Please note that most storage plugins do not report anything useful here.
    VmID      *int    `json:"vmid"`      // Associated Owner VMID.
}

type GetNodeDatastoreResponse

type GetNodeDatastoreResponse struct {
    Content      string   `json:"content"`       // Allowed storage content types.
    Storage      string   `json:"storage"`       // The storage identifier.
    Type         string   `json:"type"`          // Storage type.
    Active       *bool    `json:"active"`        // Set when storage is accessible.
    Available    *int     `json:"avail"`         // Available storage space in bytes.
    Enabled      *bool    `json:"enabled"`       // Set when storage is enabled (not disabled).
    Shared       *bool    `json:"shared"`        // Shared flag from storage configuration.
    TotalSpace   *int     `json:"total"`         // Total storage space in bytes.
    UsedSpace    *int     `json:"used"`          // Total storage space in bytes.
    UsedFraction *float64 `json:"used_fraction"` // Used fraction (used/total).
}

type GetNodeFirewallRulesResponse

type GetNodeFirewallRulesResponse[Position interface{ int | string }] struct {
    Action          string           `json:"action"`
    Comment         string           `json:"comment"`
    Destination     string           `json:"dest"`
    DestinationPort string           `json:"dport"`
    Enable          int              `json:"enable"`
    ICMPType        string           `json:"icmp-type"`
    Interface       string           `json:"iface"`
    IPVersion       int              `json:"ipversion"`
    LogLevel        FirewallLogLevel `json:"log"`
    Macro           string           `json:"macro"`
    Pos             Position         `json:"pos"`
    Proto           string           `json:"proto"`
    Source          string           `json:"source"`
    Sport           string           `json:"sport"`
    Type            string           `json:"type"`
}

type GetNodeLxcsResponse

type GetNodeLxcsResponse struct {
    Status  LxcStatus `json:"status"`
    VMID    int       `json:"vmid"`
    Cpus    *int      `json:"cpus"`
    Lock    *string   `json:"lock"`
    MaxDisk *int      `json:"maxdisk"`
    MaxMem  *int      `json:"maxmem"`
    MaxSwap *int      `json:"maxswap"`
    Name    *string   `json:"name"`
    Tags    *string   `json:"tags"`
    Uptime  *int      `json:"uptime"`
}

type GetNodesResponse

type GetNodesResponse struct {
    Node           string     `json:"node"`
    Status         NodeStatus `json:"status"`
    CPU            float64    `json:"cpu"`
    Level          string     `json:"level"`
    MaxCpu         int        `json:"maxcpu"`
    MaxMem         int        `json:"maxmem"`
    Mem            int        `json:"mem"`
    SSLFingerprint string     `json:"ssl_fingerprint"`
    Uptime         int        `json:"uptime"`
}

type GetVersionResponse

type GetVersionResponse struct {
    Release string `json:"release"`
    Version string `json:"version"`
    RepoID  string `json:"repoid"`
}

type LxcArch

type LxcArch string


const (
    LXC_ARCH_AMD64   LxcArch = "amd64"
    LXC_ARCH_I386    LxcArch = "i386"
    LXC_ARCH_ARM64   LxcArch = "arm64"
    LXC_ARCH_ARMHF   LxcArch = "armhf"
    LXC_ARCH_RISCV32 LxcArch = "riscv32"
    LXC_ARCH_RISCV64 LxcArch = "riscv64"
)

type LxcConsoleMode

type LxcConsoleMode string


const (
    LXC_CONSOLE_MODE_SHELL   LxcConsoleMode = "shell"
    LXC_CONSOLE_MODE_CONSOLE LxcConsoleMode = "console"
    LXC_CONSOLE_MODE_TTY     LxcConsoleMode = "tty"
)

type LxcLock

type LxcLock string


const (
    LXC_LOCK_BACKUP          LxcLock = "backup"
    LXC_LOCK_CREATE          LxcLock = "create"
    LXC_LOCK_DESTROYED       LxcLock = "destroyed"
    LXC_LOCK_DISK            LxcLock = "disk"
    LXC_LOCK_FSTRIM          LxcLock = "fstrim"
    LXC_LOCK_MIGRATE         LxcLock = "migrate"
    LXC_LOCK_MOUNTED         LxcLock = "mounted"
    LXC_LOCK_ROLLBACK        LxcLock = "rollback"
    LXC_LOCK_SNAPSHOT        LxcLock = "snapshot"
    LXC_LOCK_SNAPSHOT_DELETE LxcLock = "snapshot-delete"
)

type LxcNet

TODO: Add support for trunks (vlans).

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

func (*LxcNet) String

func (n *LxcNet) String() string

type LxcStatus

type LxcStatus string


const (
    LXC_STATUS_STOPPED LxcStatus = "stopped"
    LXC_STATUS_RUNNING LxcStatus = "running"
)

type NodeStatus

Proxmox availabe node statuses

type NodeStatus string


const (
    NODE_STATUS_ONLINE  NodeStatus = "online"
    NODE_STATUS_OFFLINE NodeStatus = "offline"
    NODE_STATUS_UNKNOWN NodeStatus = "unknown"
)

type PVE

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

func New

func New(config Config) (*PVE, error)

func NewWithCredentials

func NewWithCredentials(config Config, creds *Credentials) (*PVE, error)

func (*PVE) CreateClusterFirewallAlias

func (api *PVE) CreateClusterFirewallAlias(name, cidr string, comment *string) error

CreateClusterFirewallAlias creates a cluster firewall IP or Network Alias.

func (*PVE) CreateLxc

func (api *PVE) CreateLxc(req CreateLxcRequest) (CreateLxcResponse, error)

CreateLxc creates an LXC container and return useful information to interact with it after it's creation.

func (*PVE) DeleteClusterFirewallAlias

func (api *PVE) DeleteClusterFirewallAlias(name string, digest *string) error

DeleteClusterFirewallAlias removes a cluster firewall IP or Network alias.

Digest prevents changes if current configuration file has a different digest. This can be used to prevent concurrent modifications.

func (*PVE) DownloadISOToNodeDatastore

func (api *PVE) DownloadISOToNodeDatastore(node, storageId, fileName, URL string) error

DownloadISOToNodeDatastore downloads an iso from an url into a node's datastore.

TODO: Add optional parameters.

func (*PVE) DownloadVZTemplateToNodeDatastore

func (api *PVE) DownloadVZTemplateToNodeDatastore(node, storageId, fileName, URL string) error

DownloadVZTemplateToNodeDatastore downloads a vztemplate from an url into a node's datastore.

TODO: Add optional parameters.

func (*PVE) Get

func (api *PVE) Get(node string) (GetNodesResponse, error)

Get retrieves a single nodes.

func (*PVE) GetAll

func (api *PVE) GetAll() ([]GetNodesResponse, error)

GetAll retrieves all nodes.

func (*PVE) GetClusterFirewallAlias

func (api *PVE) GetClusterFirewallAlias(name string) (GetClusterFirewallAliasesResponse, error)

GetClusterFirewallAlias retrieves cluster firewall alias by it's name.

func (*PVE) GetClusterFirewallAliases

func (api *PVE) GetClusterFirewallAliases() ([]GetClusterFirewallAliasesResponse, error)

GetClusterFirewallAliases retrieves all cluster firewall aliases.

func (*PVE) GetClusterFirewallIPSet

func (api *PVE) GetClusterFirewallIPSet() ([]GetClusterFirewallIPSetResponse, error)

GetClusterFirewallIPSet retrieves all cluster firewall IPSets.

func (*PVE) GetClusterFirewallRules

func (api *PVE) GetClusterFirewallRules() ([]GetClusterFirewallRulesResponse, error)

GetClusterFirewallRules retrieves all cluster firewall rules.

func (*PVE) GetLxcs

func (api *PVE) GetLxcs(node string) ([]GetNodeLxcsResponse, error)

GetLxcs returns node's lxc index per node.

func (*PVE) GetNextVMID

func (api *PVE) GetNextVMID() (int, error)

GetNextVMID returns the next available VMID.

func (*PVE) GetNodeDatastoreContent

func (api *PVE) GetNodeDatastoreContent(node, storageId string) ([]GetNodeDatastoreContentResponse, error)

GetNodeDatastoreContent retrieves node's datastores info.

TODO: Add optional parameters.

func (*PVE) GetNodeDatastores

func (api *PVE) GetNodeDatastores(node string) ([]GetNodeDatastoreResponse, error)

GetNodeDatastores retrieves node's datastores info.

func (*PVE) GetNodeRules

func (api *PVE) GetNodeRules(node string) ([]GetNodeFirewallRulesResponse[int], error)

GetNodeRules retrieves node's firewall rules.

func (*PVE) GetNodeRulesByPos

func (api *PVE) GetNodeRulesByPos(node string, pos int) (GetNodeFirewallRulesResponse[string], error)

GetNodeRulesByPos Retrieves a single node's firewall rule using rule's position (pos) as an index.

func (*PVE) GetVersion

func (api *PVE) GetVersion() (GetVersionResponse, error)

GetVersion retrieves proxmox version.

func (*PVE) ReadNodeLog

func (api *PVE) ReadNodeLog(node string) ([]FirewallLogEntry, error)

ReadNodeLog Retrieves node's firewall log entries.

TODO: Add missing limit, since, start, until parameters shown in docs.

func (*PVE) UpdateClusterFirewallAlias

func (api *PVE) UpdateClusterFirewallAlias(name, cidr string, comment *string, digest *string, rename *string) error

UpdateClusterFirewallAlias updates a cluster firewall IP or Network alias.

Digest prevents changes if current configuration file has a different digest. This can be used to prevent concurrent modifications.