Proxmox Ve

ディレクトリ構成

skills/proxmox-ve/
  SKILL.md
  references/
    core/
      README.md
      installation.md
      cluster.md
      storage.md
      vm-qemu.md
      container-lxc.md
      networking-sdn.md
      ceph.md
      ha.md
      backup-restore.md
      firewall.md
      user-access.md
      notifications.md
    cli/
      README.md
      qm.md
      pct.md
      pvesm.md
      pvecm.md
      pveceph.md
      pvenode.md
      pveum.md
      pvesh.md
      vzdump.md
      pveam.md
      pvesr.md
      ha-manager.md
      misc-cli.md
    config/
      README.md
      qm-conf.md
      pct-conf.md
      datacenter-cfg.md
    api/
      README.md
      rest-overview.md
      endpoints-qemu.md
      endpoints-lxc.md
      endpoints-cluster.md
      endpoints-access-storage.md
    services/
      README.md
      daemons.md
  samples/
    README.md
    vm-lifecycle.md
    container-lifecycle.md
    cluster-setup.md
    backup-restore.md
    api-automation.md
  scripts/
    README.md
    install.md
    vm-commands.md
    container-commands.md
    cluster-commands.md
    storage-commands.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

Access & Storage Endpoints

REST API endpoints for user/permission management (/access) and storage pool management (/storage, /pools).

Signature / Usage

/access/ticket
/access/users
/access/groups
/access/roles
/access/acl
/access/domains
/storage
/pools

Access Endpoints

Authentication

Login request parameters:

Login response fields:

# Obtain ticket
curl -k -s -d "username=root@pam&password=secret" \
  https://<host>:8006/api2/json/access/ticket | jq -r .data.ticket

Users

API Tokens

# Create token via CLI
pveum user token add root@pam mytoken --privsep=0

Groups, Roles & ACL

Authentication Domains (Realms)

Storage Endpoints

Storage Pool Definitions

pvesh get /storage
pvesh get /nodes/pve1/storage

Per-Node Storage

Resource Pools

Notes

• All users are in user@realm format; built-in realms are pam (Linux PAM) and pve (Proxmox internal).
• API tokens bypass CSRF requirements; a token with privsep=0 inherits full user privileges.
• ACL paths follow the resource tree: / (root), /nodes/{node}, /vms/{vmid}, /storage/{storage}, /pool/{poolid}.
• Required privilege: Sys.Audit for reading access/storage config; User.Modify for user management.

Related

• REST API Overview
• Cluster & Node Endpoints

Cluster & Node Endpoints

REST API endpoints for cluster-wide management and per-node operations.

Signature / Usage

/nodes
/nodes/{node}
/nodes/{node}/status
/nodes/{node}/tasks
/cluster
/cluster/options
/cluster/ha
/cluster/replication
/cluster/metrics

Node Endpoints

Node Listing

pvesh get /nodes
pvesh get /nodes/pve1/status --output-format json-pretty

Task Tracking (Async Operations)

All long-running API calls return an UPID (Unique Process ID). Use these endpoints to track progress:

# Check task result
pvesh get /nodes/pve1/tasks/UPID:pve1:00001234:...:qmstart:100:root@pam:/status

Cluster Endpoints

Cluster Information

pvesh get /cluster/status
pvesh get /cluster/resources --type vm
pvesh set cluster/options --console html5

High Availability

Replication

Replication key parameters:

Notes

• GET /cluster/resources accepts a type filter: vm, storage, node, or pool.
• Quorum is required for most write operations on the cluster; nodes losing quorum become read-only.
• The /version endpoint requires no authentication and is useful for connectivity checks.

Related

• REST API Overview
• Access & Storage Endpoints

LXC Container Endpoints

REST API endpoints for managing Linux containers (LXC) under /nodes/{node}/lxc.

Signature / Usage

/nodes/{node}/lxc
/nodes/{node}/lxc/{vmid}
/nodes/{node}/lxc/{vmid}/status/{action}
/nodes/{node}/lxc/{vmid}/snapshot
/nodes/{node}/lxc/{vmid}/migrate
/nodes/{node}/lxc/{vmid}/config
/nodes/{node}/lxc/{vmid}/clone

Endpoints

Container Listing & Creation

Create container key parameters:

# Example: create and start a container via pvesh
pvesh create /nodes/mynode/lxc \
  --vmid 200 \
  --ostemplate local:vztmpl/debian-12-standard_12.0-1_amd64.tar.zst \
  --hostname myct \
  --memory 512 \
  --rootfs local-lvm:8 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --start 1

Container Configuration

Container Status & Control

Snapshots

Migration & Clone

Notes

• All long-running operations return a task UPID. Poll /nodes/{node}/tasks/{upid}/status for completion.
• Required privilege: VM.Audit for reads; VM.PowerMgmt for status actions; VM.Allocate for create/delete.
• Containers share the host kernel; privileged containers have more access to host namespaces — prefer unprivileged: true.
• pvesh ls /nodes/<node>/lxc/<vmid> lists all available sub-paths for a specific container.

Related

• REST API Overview
• QEMU VM Endpoints

QEMU VM Endpoints

REST API endpoints for managing QEMU/KVM virtual machines under /nodes/{node}/qemu.

Signature / Usage

/nodes/{node}/qemu
/nodes/{node}/qemu/{vmid}
/nodes/{node}/qemu/{vmid}/status/{action}
/nodes/{node}/qemu/{vmid}/snapshot
/nodes/{node}/qemu/{vmid}/migrate
/nodes/{node}/qemu/{vmid}/config
/nodes/{node}/qemu/{vmid}/clone

Endpoints

VM Listing & Creation

Create VM key parameters:

VM Configuration

VM Status & Control

Snapshots

Snapshot key parameters:

Migration

Migrate key parameters:

Clone

Notes

• All long-running operations return a task UPID. Poll /nodes/{node}/tasks/{upid}/status for completion.
• Required privilege: VM.Audit for reads; VM.PowerMgmt for status actions; VM.Allocate for create/delete.
• pvesh ls /nodes/<node>/qemu/<vmid> lists all available sub-paths for a specific VM.

Related

• REST API Overview
• LXC Container Endpoints

API

REST API Overview

Proxmox VE exposes its full management functionality through a RESTful HTTP API on port 8006. Every action available in the web UI is accessible via the API.

Signature / Usage

Base URL: https://<host>:8006/api2/json/

Response format is specified in the URL path: json (default), extjs, html, text.

Authentication

Ticket Cookie (Session-based)

1. POST credentials to /access/ticket to obtain a signed ticket. 2. Pass the ticket via PVEAuthCookie cookie on subsequent requests. 3. For write operations (POST/PUT/DELETE), include the CSRFPreventionToken header. 4. Tickets expire after 2 hours.

# Obtain ticket
curl -k -d "username=root@pam&password=secret" \
  https://<host>:8006/api2/json/access/ticket

API Token (Stateless)

Tokens are created per user and do not require CSRF tokens. Suitable for automation.

# Create token
pveum user token add root@pam mytoken --privsep=0

# Use token
curl -k -H "Authorization: PVEAPIToken=root@pam!mytoken=<uuid>" \
  https://<host>:8006/api2/json/nodes

Endpoint Groups

pvesh — CLI Access to the API

pvesh provides direct API access from the command line on any Proxmox node (requires root). Calls are automatically proxied to the correct cluster member via SSH.

# Explore available paths
pvesh ls /nodes
pvesh ls /nodes/<node>/qemu

# Read operations
pvesh get /nodes/<node>/qemu
pvesh get /nodes/<node>/status

# Write operations
pvesh create /nodes/<node>/qemu --vmid 100 --memory 2048 --net0 virtio,bridge=vmbr0
pvesh set /cluster/options --console html5
pvesh delete /nodes/<node>/qemu/100

# Inspect API documentation for a path
pvesh usage /nodes/{node}/qemu -v

# Output formatting
pvesh get /nodes --output-format json-pretty
pvesh get /nodes --human-readable

pvesh Commands

Response Format

All JSON responses follow this envelope:

{
  "data": { ... }
}

Errors return an HTTP status code ≥ 400 with a errors key.

Notes

• The API is versioned per major release. An API call working in 6.0 works in 6.4 without changes; breaking changes only occur across major versions.
• pveproxy (port 8006, external) forwards privileged operations to pvedaemon (port 85, localhost-only). Never expose port 85 externally.
• The interactive API viewer is available at https://<host>:8006/api2/ (JavaScript SPA); offline exploration is possible via pvesh ls and pvesh usage.

Related

• QEMU VM Endpoints
• LXC Container Endpoints
• Cluster & Node Endpoints
• Access & Storage Endpoints

ha-manager

Proxmox VE High Availability Manager. Monitors cluster resources and automatically performs failover of VMs and containers when node failures are detected.

Signature / Usage

ha-manager <COMMAND> [OPTIONS]
ha-manager help [<COMMAND>]

Subcommands

Resource Management:

CRM Commands:

Rules (Affinity / Anti-affinity):

Options / Props

Key options for ha-manager add:

Key options for ha-manager status:

Notes

• HA requires a functional cluster with quorum; at least 3 nodes are recommended.
• A watchdog device is required on each node for reliable fencing.
• Use crm-command disarm-ha before planned full cluster shutdowns to prevent unintended fencing.
• Node maintenance mode (node-maintenance enable) gracefully migrates all resources off a node before maintenance.
• --state ignored removes HA management without deleting the resource config entry.
• Legacy group commands (groupadd, groupset, etc.) are deprecated; use rules instead.

Related

• pvecm.md
• pvenode.md
• qm.md
• pct.md

misc-cli

Miscellaneous Proxmox VE CLI tools: pveperf, pvesubscription, and qmrestore.

---

pveperf

Proxmox VE performance benchmark script. Measures CPU and disk performance on the specified path.

Signature / Usage

pveperf [PATH]

PATH defaults to / if not specified.

Metrics Reported

---

pvesubscription

Proxmox VE Subscription Manager. Manages the Proxmox VE support subscription key on a node.

Signature / Usage

pvesubscription <COMMAND> [OPTIONS]

Subcommands

Options / Props

Notes

• Run pvesubscription update after setting a key to activate the enterprise repository.
• pvesubscription get returns NotFound if no key is installed.

---

qmrestore

Restore a QEMU/KVM VM from a vzdump backup archive. Volumes are allocated on the original storage unless overridden.

Signature / Usage

qmrestore <archive> <vmid> [OPTIONS]
qmrestore help

Options / Props

Notes

• qmrestore is functionally equivalent to qm create --archive <file>.
• --live-restore is only supported with Proxmox Backup Server (PBS) sources.
• For LXC container restore, use pct restore (alias for pct create with an archive).

---

Related

• vzdump.md
• qm.md
• pct.md
• pvesm.md

pct

Proxmox Container Toolkit. Manages LXC containers on a Proxmox VE node, abstracting complex LXC configuration into a unified CLI.

Signature / Usage

pct <COMMAND> [OPTIONS]
pct help [<COMMAND>]

Subcommands

Options / Props

Key options for pct create:

Notes

• --unprivileged is recommended for new containers; it maps container root to an unprivileged host user.
• pct enter requires the container to be running; use pct mount + chroot for offline access.
• Snapshots require storage that supports them (e.g. ZFS, Ceph, or qcow2-backed storage).
• pct restore is an alias for pct create when restoring from a vzdump backup archive.

Related

• qm.md
• pveam.md
• vzdump.md
• pvesm.md

pveam

Proxmox VE Appliance Manager. Downloads and manages LXC container OS templates from the Proxmox template repository.

Signature / Usage

pveam <COMMAND> [OPTIONS]
pveam help [<COMMAND>]

Subcommands

Options / Props

Key options for pveam available:

Key options for pveam download:

Notes

• Run pveam update before pveam available to get the latest template list.
• The storage must be configured with content type vztmpl to accept templates.
• Downloaded templates are used with pct create via the --ostemplate option.
• Template filenames follow the pattern <distro>-<version>-standard_<ver>_<arch>.tar.zst.

Related

• pct.md
• pvesm.md

pveceph

Proxmox VE Ceph Manager. Manages Ceph services (monitors, managers, OSDs, pools, and filesystems) integrated into Proxmox VE nodes.

Signature / Usage

pveceph <COMMAND> [OPTIONS]
pveceph help [<COMMAND>]

Subcommands

Options / Props

Key options for pveceph init:

Key options for pveceph osd create:

Key options for pveceph pool create:

Notes

• Ceph requires a minimum of 3 monitors for reliable operation.
• The --network option in pveceph init must be specified before creating monitors or OSDs.
• Destroying the last monitor is prevented to protect cluster integrity.
• OSD encryption (--encrypted) is configured at creation time and cannot be changed later.
• pveceph pool destroy can optionally remove associated Proxmox storage entries.

Related

• pvesm.md
• pvecm.md

pvecm

Proxmox VE Cluster Manager. Creates and manages clusters of Proxmox VE nodes using the Corosync Cluster Engine for reliable group communication.

Signature / Usage

pvecm <COMMAND> [OPTIONS]
pvecm help [<COMMAND>]

Subcommands

Options / Props

Key options for pvecm create:

Key options for pvecm add:

Notes

• All nodes must be able to connect via UDP ports 5405–5412 for Corosync.
• SSH (TCP 22) must be open between all nodes for cluster operations.
• Date/time must be synchronized across all nodes (use NTP).
• A minimum of 3 nodes is recommended for reliable quorum in HA setups.
• Latency between cluster nodes must be under 5 ms.
• pvecm delnode requires quorum; use pvecm expected if quorum is lost.

Related

• pvenode.md
• ha-manager.md
• pveum.md

pvenode

Proxmox VE Node Management Tool. Controls node-specific settings, certificates, guest bulk operations, and task history.

Signature / Usage

pvenode <COMMAND> [OPTIONS]
pvenode help [<COMMAND>]

Subcommands

Options / Props

Key options for pvenode startall / pvenode stopall:

Key options for pvenode migrateall:

Key options for pvenode task list:

General output option:

Notes

• pvenode startall --force starts all VMs regardless of onboot setting; use with care.
• ACME certificate management integrates with Let's Encrypt and other ACME-compatible CAs.
• pvenode stopall sends a shutdown signal and waits; use --timeout to set a maximum wait time.
• Task UPIDs can be obtained from pvenode task list or API responses.

Related

• pvecm.md
• pveum.md
• ha-manager.md

pvesh

Proxmox VE API Shell. Directly invokes Proxmox REST API endpoints from the command line without going through the HTTPS server.

Signature / Usage

pvesh <COMMAND> <api-path> [OPTIONS]
pvesh help [<COMMAND>]

Subcommands

Options / Props

Notes

• Most operations require root privileges on the local node.
• pvesh bypasses the HTTPS REST API and calls the API handlers directly; useful for scripting and automation.
• API paths mirror the web UI structure (e.g. /nodes/pve1/qemu/100/status/start).
• Use pvesh ls / to explore the available API tree.
• Use pvesh usage <path> --verbose to see all parameters for a given endpoint.

Related

• pveum.md
• pvenode.md

pvesm

Proxmox VE Storage Manager. Manages storage pools and volumes across the cluster.

Signature / Usage

pvesm <COMMAND> [OPTIONS]
pvesm help [<COMMAND>]

Subcommands

Options / Props

Key options for pvesm add:

For pvesm scan:

Notes

• pvesm remove only removes the storage configuration entry; it does not delete the underlying data or pool.
• Content type rootdir is for container root volumes; images is for VM disk images.
• --shared must be set correctly in cluster environments to avoid storage conflicts.
• Use pvesm prune-backups with --dry-run to preview what would be deleted.

Related

• pveceph.md
• vzdump.md
• pvesr.md

pvesr

Proxmox VE Storage Replication. Manages replication jobs that continuously replicate guest volumes to other cluster nodes using ZFS snapshots to minimize network traffic.

Signature / Usage

pvesr <COMMAND> [OPTIONS]
pvesr help [<COMMAND>]

Subcommands

Options / Props

Key options for pvesr create-local-job:

Key options for pvesr delete:

Notes

• Storage replication requires ZFS-based storage; it uses ZFS send/receive with incremental snapshots.
• The default schedule (*/15) replicates every 15 minutes; use standard systemd OnCalendar syntax for custom schedules.
• Replicated data can serve as a warm standby for HA failover, but pvesr itself is not an HA mechanism.
• Job IDs are in the format <vmid>-<jobnum>; multiple jobs per VM are allowed with different targets.

Related

• pvesm.md
• pvecm.md
• ha-manager.md

pveum

Proxmox VE User Manager. Manages users, groups, authentication realms, roles, resource pools, API tokens, and access control lists.

Signature / Usage

pveum <COMMAND> [OPTIONS]
pveum help [<COMMAND>]

Subcommands

Options / Props

Key options for pveum user add / pveum user modify:

Key options for pveum realm add:

Key options for pveum acl modify:

Key options for pveum user token add:

Notes

• User IDs must be in name@realm format (e.g. admin@pam, john@pve).
• pam realm uses Linux PAM authentication; pve realm stores credentials in the Proxmox database.
• API tokens with --privsep 1 (default) are limited to the permissions explicitly granted via ACL, independent of the owning user's rights.
• pveum realm sync is available for LDAP, AD, and OpenID realms.
• Roles are sets of privileges; built-in roles include Administrator, PVEVMAdmin, PVEDatastoreAdmin, etc.

Related

• pvecm.md
• pvesh.md

qm

QEMU/KVM Virtual Machine Manager. Manages the full lifecycle of VMs on a Proxmox VE node.

Signature / Usage

qm <COMMAND> [OPTIONS]
qm help [<COMMAND>]

Subcommands

Options / Props

Key options for qm create / qm set:

Notes

• qm stop is a hard power-off; prefer qm shutdown for graceful stops.
• Cloud-init options (--ciuser, --sshkeys, etc.) require a cloud-init drive (--ide[n] or --scsi[n] with media=cdrom,format=raw).
• --skiplock should only be used when the lock is stale; misuse can corrupt VM state.
• Snapshots require storage that supports them (e.g. qcow2, ZFS, Ceph).

Related

• pct.md
• vzdump.md
• pvesm.md

CLI

vzdump

Backup utility for Proxmox VE VMs and containers. Creates full backups containing VM/CT configuration and all disk data.

Signature / Usage

vzdump {<vmid>} [OPTIONS]
vzdump help

<vmid> can be a single ID, a comma-separated list, or omitted with --all.

Options / Props

Backup Modes

Notes

• Global defaults can be set in /etc/vzdump.conf using key: value format.
• --prune-backups supports: keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly, keep-yearly.
• snapshot mode requires storage snapshot support or fleecing; falls back gracefully.
• Use --stdout to pipe backup data directly to a custom destination.
• vzdump is also invoked internally by scheduled backup jobs configured in the web UI.

Related

• qm.md
• pct.md
• pvesm.md
• misc-cli.md

datacenter.cfg — Datacenter Configuration File

Cluster-wide default settings for a Proxmox VE datacenter.

Path: /etc/pve/datacenter.cfg

Signature / Usage

OPTION: value

Each line is a colon-separated key-value pair. Blank lines and lines starting with # are treated as comments. This file applies to all nodes in the cluster.

# Example datacenter.cfg
keyboard: en-us
language: en
email_from: admin@example.com
migration: type=secure
fencing: watchdog
mac_prefix: BC:24:11

Options / Props

UI & Localisation

Networking

Migration & Replication

migration sub-options:

replication sub-options mirror migration (type, network).

High Availability

ha sub-options:

Fencing modes:

• watchdog — software watchdog only (default, supported everywhere)
• hardware — external IPMI/BMC fencing (requires hardware setup)
• both — watchdog + hardware (experimental)

Cluster Resource Scheduling

crs sub-options:

Bandwidth Limits

bwlimit sub-options:

Example: bwlimit: default=10240,migration=51200

VMID Allocation

next-id sub-options: lower=<int>,upper=<int>

Notifications & Email

notify sub-options:

Tag Management

user-tag-access sub-options: user-allow=free|existing|list|none, user-allow-list=<tag;...>

tag-style sub-options: case-sensitive=0|1, color-map=<tag:color:fg-color;...>, ordering=config|alphabetical, shape=full|circle|dense|none

Geographic Location

Authentication

Performance

Notes

• datacenter.cfg is cluster-replicated via pmxcfs; edits on any node propagate automatically.
• fencing: hardware and fencing: both are marked experimental and require IPMI/BMC hardware.
• Several deprecated options exist (e.g., migration_unsecure); use migration: type=insecure instead.
• Some options have prerequisites noted in the full man page (e.g., webauthn requires a configured realm).
• Editing via the web UI (Datacenter > Options) is recommended to avoid syntax errors.

Related

• qm-conf.md — VM configuration file format
• pct-conf.md — Container configuration file format

pct.conf — Container Configuration File

Configuration file for LXC containers managed by Proxmox VE.

Path: /etc/pve/lxc/<CTID>.conf

Signature / Usage

OPTION: value

Each line is a colon-separated key-value pair. Blank lines and lines starting with # are treated as comments. Low-level LXC directives can also be placed directly using lxc.<key> = <value> syntax.

# Example container config
hostname: mycontainer
arch: amd64
ostype: ubuntu
memory: 1024
swap: 512
cores: 2
unprivileged: 1
onboot: 1
rootfs: local-lvm:vm-200-disk-0,size=8G
net0: name=eth0,bridge=vmbr0,ip=dhcp,firewall=1

Options / Props

Identity & OS

CPU

Memory

Storage

rootfs format: [volume=]<volume>[,acl=1][,idmap=<mapping>][,mountoptions=<opt;...>][,quota=1][,replicate=1][,ro=1][,shared=1][,size=<DiskSize>]

mp[n] format adds mp=<Path> and backup=0|1 to the same sub-options as rootfs.

Mount sub-options:

Network

net[n] format: name=<ifname>,bridge=<bridge>,hwaddr=<MAC>,firewall=1,ip=dhcp|<CIDR>|manual,gw=<IPv4>,ip6=auto|dhcp|<CIDR>|manual,gw6=<IPv6>,tag=<1-4094>,rate=<Mbps>,mtu=<int>,type=veth

DNS

Console & TTY

Boot & Lifecycle

Security & Features

features sub-options:

Device Passthrough

dev[n] format: [path=]<Path>[,deny-write=1][,gid=<gid>][,mode=<octal>][,uid=<uid>]

Init & Runtime

Low-Level LXC

Notes

• Container IDs below 100 are reserved for internal Proxmox use.
• unprivileged: 1 is strongly recommended for untrusted workloads; it maps container root (uid 0) to an unprivileged host uid.
• Mount points must not contain symlinks for security reasons.
• shared: 1 on a mount point only marks it as already shared — it does not automatically share the storage across nodes.
• Most options take effect on next container start; running containers can be modified live for some options via pct set.
• Use pct set <ctid> --<option> <value> rather than editing the file directly while the container is running.

Related

• qm-conf.md — QEMU VM configuration file format
• datacenter-cfg.md — Datacenter-wide configuration

qm.conf — VM Configuration File

Configuration file for QEMU/KVM virtual machines managed by Proxmox VE.

Path: /etc/pve/qemu-server/<VMID>.conf

Signature / Usage

OPTION: value

Each line is a colon-separated key-value pair. Blank lines and lines starting with # are treated as comments. Snapshot sections are appended at the end of the file with a [<snapshot-name>] header.

# Example VM config
name: myvm
memory: 2048
cores: 2
sockets: 1
ostype: l26
bios: seabios
boot: order=scsi0;ide2;net0
scsi0: local-lvm:vm-100-disk-0,size=32G
ide2: none,media=cdrom
net0: virtio,bridge=vmbr0,firewall=1
onboot: 1

Options / Props

System & CPU

Memory

Boot

Storage Devices

Disk sub-options (common across ide, sata, scsi, virtio):

Network

net[n] format: model=virtio,bridge=vmbr0,macaddr=BC:24:11:xx:xx:xx,firewall=1,tag=<1-4094>,rate=<Mbps>,queues=<n>,mtu=<int>

Common models: virtio, e1000, e1000e, rtl8139, vmxnet3.

Display & Console

PCI / USB Passthrough

Cloud-Init

SMBIOS / Identity

Lifecycle & Protection

QEMU Guest Agent

Metadata

Notes

• VM IDs below 100 are reserved for internal Proxmox use.
• Options hostpci[n] and pcie=1 generally prevent live migration unless the host supports SR-IOV or mdev.
• For UEFI boot, set bios: ovmf and add an efidisk0.
• Snapshot state is appended inline; do not edit the [<snapshot>] sections manually.
• Changes to most options require a VM restart; some (network, disk) support hotplug.
• Use qm set <vmid> --<option> <value> rather than editing the file directly while the VM is running.

Related

• pct-conf.md — LXC container configuration file format
• datacenter-cfg.md — Datacenter-wide configuration

config

Backup & Restore

Proxmox VE provides integrated backup via vzdump. All backups are full backups containing VM/CT configuration and complete disk data. Proxmox Backup Server (PBS) integration adds deduplication, live-restore, and single-file restore.

Signature / Usage

# Backup a VM (snapshot mode)
vzdump <vmid> --mode snapshot --storage <storage-id>

# Backup with retention
vzdump <vmid> --mode snapshot --storage pbs-storage \
  --prune-backups keep-daily=7,keep-weekly=4,keep-monthly=3

# Restore a VM
qmrestore <backup-file> <new-vmid>

# Restore a container
pct restore <ctid> <backup-file>

# Limit bandwidth during restore (KiB/s)
qmrestore <backup-file> <vmid> --bwlimit 51200

Options / Props

vzdump modes

Container-specific change detection (with PBS)

Retention (--prune-backups)

Key options

Notes

• Fleecing (VMs only): caches backup data on a fast local storage before streaming to PBS, improving guest I/O at the cost of extra storage space
• Live-restore (PBS only): VM starts immediately while disk data is loaded in the background; ideal for large VMs requiring rapid recovery
• Single-file restore (PBS only): browse and download individual files from a backup without restoring the entire disk
• Backup jobs can be scheduled in the web UI under Datacenter → Backup; retention policies are set per job
• --bwlimit prevents backup/restore from saturating storage and impacting running guests

Related

• vm-qemu.md
• container-lxc.md
• storage.md

Hyper-Converged Ceph

Proxmox VE integrates Ceph directly, allowing cluster nodes to serve as both compute and storage. Core components are OSD (object storage), MON (monitor), and MGR (manager).

Signature / Usage

# Initialize Ceph on the first node
pveceph init --network 10.10.10.0/24

# Add a monitor
pveceph mon create

# Add an OSD (one per physical disk)
pveceph osd create /dev/sdb

# Create a storage pool
pveceph pool create <pool-name> --size 3 --min_size 2

# Check Ceph cluster status
ceph status

Options / Props

pveceph init

pveceph pool create

Component roles

Notes

• Minimum recommended deployment: 3 nodes, 12 OSDs distributed evenly across nodes
• Recommended memory: 8 GB per OSD for stable performance
• Recommended network: 10+ Gbps dedicated; separate public and cluster networks reduce OSD replication impact on client I/O
• Do not use hardware RAID controllers with Ceph OSDs; use raw disks or HBAs in passthrough mode
• SSDs improve OSD recovery time and latency; NVMe recommended for WAL/DB devices

Related

• storage.md
• cluster.md
• ha.md

Cluster Management

Proxmox VE cluster management uses pvecm with Corosync for group communication and pmxcfs (Proxmox Cluster File System) to distribute configuration across all nodes in real time.

Signature / Usage

# Create a new cluster
pvecm create <cluster-name>

# Add a node to an existing cluster (run on the new node)
pvecm add <existing-node-IP>

# Show cluster status
pvecm status

# Remove a node (run from another cluster node)
pvecm delnode <nodename>

Options / Props

pvecm add

Corosync requirements

Notes

• Each node receives one vote; quorum is lost when fewer than half the nodes are reachable, causing the cluster to enter read-only mode
• Dedicated physical NIC for cluster traffic is strongly recommended; Corosync is latency-sensitive despite low bandwidth usage
• Before removing a node: migrate all VMs/CTs away and remove any Ceph or replication jobs referencing it — these become irremovable otherwise
• Always power off a node before deletion to avoid cluster corruption
• pmxcfs transparently replicates /etc/pve/ to all nodes in real time over a FUSE filesystem

Related

• ha.md
• storage.md

LXC Containers

Proxmox VE manages Linux Containers (LXC) via the pct CLI and the web UI. Containers share the host kernel and are lighter than VMs. Unprivileged containers are the recommended default.

Signature / Usage

# Download a container template
pveam download local debian-12-standard_12.7-1_amd64.tar.zst

# Create a container from a template
pct create <ctid> local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --hostname myct --memory 512 --rootfs local-lvm:8

# Start / stop / enter shell
pct start <ctid>
pct stop <ctid>
pct enter <ctid>

# Resize root disk
pct resize <ctid> rootfs +5G

# Restore from backup
pct restore <ctid> /path/to/backup.tar.zst

Options / Props

pct create key options

Mount points

Notes

• Unprivileged containers (default) map container root UID to an unprivileged host UID — container escapes affect only unprivileged users
• Privileged containers rely on AppArmor and seccomp; use only in trusted environments
• Bind mounts bypass Proxmox storage management and do not support snapshots or backups via vzdump
• Enable nesting=1 feature to run Docker or systemd inside a container
• Templates are tar archives managed by pveam; available from official Proxmox template repositories
• Resource limits use Linux cgroupv2 in modern Proxmox versions

Related

• storage.md
• backup-restore.md

Firewall

Proxmox VE includes a built-in firewall that operates at three levels: datacenter, node/host, and VM/container. Configuration is stored in /etc/pve/firewall/ and distributed via pmxcfs.

Signature / Usage

# Configuration files
/etc/pve/firewall/cluster.fw       # Datacenter-level rules
/etc/pve/nodes/<node>/host.fw      # Node/host-level rules
/etc/pve/firewall/<vmid>.fw        # VM/CT-level rules

# Example cluster.fw
[OPTIONS]
enable: 1
policy_in: DROP
policy_out: ACCEPT

[RULES]
IN ACCEPT -p tcp --dport 22 -source +management
IN DROP -source +blacklist

Options / Props

Configuration levels

Traffic zones

Traffic directions

Standard IP sets

Default auto-allowed traffic (when firewall is enabled)

• Loopback interface
• Established/related connections
• Corosync cluster traffic (UDP 5405–5412)
• Web UI (TCP 8006), SSH (TCP 22), SPICE (TCP 5900–5999), SPICE proxy (TCP 3128)

Notes

• Each virtual network device has its own firewall enable flag; the firewall must be enabled at both the datacenter and VM level to take effect
• Security groups bundle reusable rule sets at the cluster level; reference them in VM rules using GROUP <name>
• IP sets group hosts/networks referenced in rules with +setname syntax
• IP aliases associate human-readable names with addresses for cleaner rule definitions

Related

• networking-sdn.md
• user-access.md

High Availability (HA)

Proxmox VE HA manager automatically restarts or migrates VMs and containers when a cluster node fails. It uses watchdog-based fencing to prevent split-brain scenarios.

Signature / Usage

# Add a VM to HA management
ha-manager add vm:<vmid> --state started --max_restart 2 --max_relocate 1

# Add a container to HA
ha-manager add ct:<ctid> --state started

# List HA resources
ha-manager status

# Remove from HA
ha-manager remove vm:<vmid>

Options / Props

ha-manager resource options

Node Affinity Rules (v9.0+, replaces HA Groups)

Resource Affinity Rules

Watchdog modes

Watchdog states

Notes

• HA requires a minimum of 3 cluster nodes for reliable quorum
• Two daemons cooperate: pve-ha-lrm (Local Resource Manager, per node) and pve-ha-crm (Cluster Resource Manager, elected master)
• Fencing is mandatory — without reliable fencing, HA cannot safely restart services from a failed node
• HA Groups are deprecated since PVE 9.0; use Node Affinity Rules instead
• pmxcfs locking ensures only one LRM and one CRM master run at any time

Related

• cluster.md
• vm-qemu.md
• container-lxc.md

Installation

Install Proxmox VE from a hybrid ISO image (recommended) or on top of an existing Debian system. The installer handles partitioning, timezone/network configuration, and package setup.

Signature / Usage

# Access web UI after installation
https://<IP>:8006

Options / Props

Installer disk layout options (LVM)

ZFS options

BTRFS options

Notes

• All existing data on target disk is erased during installation
• ZFS on hardware RAID is unsupported and risks data loss; use ZFS directly on raw disks
• Secure Boot must be disabled for installer versions before 8.1
• ZFS works best with plenty of RAM: ~4 GB base + 1 GB per TB of raw storage
• Advanced users can install on existing Debian, but this requires detailed knowledge of PVE internals
• After installation, log in to the web interface at https://<IP>:8006 with root credentials set during setup

Related

• cluster.md
• storage.md

Networking & SDN

Proxmox VE uses the Linux network stack configured via /etc/network/interfaces. The Software-Defined Networking (SDN) layer adds virtual zones and VNets for fine-grained multi-node guest network control.

Signature / Usage

# Apply network config live (requires ifupdown2)
ifreload -a

# Example /etc/network/interfaces — bridge with VLAN
auto vmbr0
iface vmbr0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes

# Example bond configuration
auto bond0
iface bond0 inet manual
    bond-slaves eno1 eno2
    bond-mode active-backup
    bond-miimon 100

Options / Props

Traditional networking

SDN zone types

SDN VNet options

SDN subnet options

Notes

• Network changes are staged in /etc/network/interfaces.new; apply with "Apply Configuration" in the web UI or ifreload -a (requires ifupdown2)
• SDN core packages are installed by default in PVE 8.1+; advanced features require dnsmasq (DHCP), frr (BGP/EVPN), and ifupdown2
• Use a dedicated physical NIC for Corosync cluster traffic separate from VM traffic
• VNets become standard Linux bridges on each node after SDN configuration is applied

Related

• cluster.md
• vm-qemu.md
• container-lxc.md
• firewall.md

Notifications

Proxmox VE routes system alerts to configurable notification targets using matchers. Targets and matchers are managed in the web UI under Datacenter → Notifications.

Signature / Usage

# Example notification target (sendmail)
[sendmail: admin-mail]
    mailto-user root@pam
    from-address pve@example.com

# Example matcher
[matcher: errors-only]
    target admin-mail
    match-severity error
    match-field type=vzdump

Options / Props

Notification target types

Sendmail / SMTP options

Gotify options

Webhook options

Matcher filter options

Built-in notification event types

Notes

• A matcher with no filter rules always triggers for every event
• Multiple matchers targeting the same notification target will not send duplicate messages
• SMTP target has no retry mechanism; use sendmail/Postfix for reliable delivery
• Webhook bodies support Handlebars helpers: URL encoding, JSON escaping, and metadata field injection
• Common webhook integrations: Discord, Slack, ntfy.sh

Related

• user-access.md
• backup-restore.md

Core

Storage

Proxmox VE storage configuration lives in /etc/pve/storage.cfg and is distributed automatically to all cluster nodes. Backends are divided into file-level (flexible content types) and block-level (raw images only).

Signature / Usage

# Add a storage backend via CLI
pvesm add <type> <storage-id> [options]

# Example: add a local directory storage
pvesm add dir local-data --path /mnt/data --content images,backup

# List configured storages
pvesm status

Options / Props

Storage backend comparison

Common storage.cfg properties

Notes

• Thin provisioning allows volumes larger than available space; monitor utilization carefully to prevent data corruption
• Shared storage (NFS, Ceph RBD, etc.) enables live VM migration without copying disk data
• Snapshot support depends on backend: native on ZFS/LVM-thin/RBD; qcow2-based on file backends
• Never reuse storage configuration (especially locking storage) across multiple independent clusters

Related

• vm-qemu.md
• container-lxc.md
• ceph.md
• backup-restore.md

User & Access Management

Proxmox VE uses role-based access control (RBAC) with users, groups, roles, and authentication realms. Configuration is stored in /etc/pve/user.cfg and distributed to all cluster nodes.

Signature / Usage

# Create a user
pveum user add alice@pve --comment "Alice" --email alice@example.com

# Assign a role on a path
pveum acl modify /vms/100 --user alice@pve --role PVEVMAdmin

# Create a group and assign a role
pveum group add ops-team
pveum acl modify /nodes/pve1 --group ops-team --role PVEAuditor

# Create an API token
pveum user token add alice@pve token1 --privsep 1

# List ACLs
pveum acl list

Options / Props

User identifier format

<username>@<realm>

Examples: root@pam, alice@pve, bob@ldap

Authentication realms

Built-in roles

ACL path templates

pveum acl modify options

API token options

Two-factor authentication methods

Notes

• root@pam cannot be deleted and always retains Administrator access
• Prefer assigning roles to groups rather than individual users for maintainable ACLs
• API token values are shown only once upon creation; store securely
• By default, tokens use privsep=1 (separated privileges) and require explicit ACL grants
• 2FA lockout: 8 failed attempts for TOTP; 100 for WebAuthn and recovery keys
• Permissions propagate down the path hierarchy; user-level permissions override group permissions at the same path

Related

• firewall.md
• notifications.md

Virtual Machines (QEMU/KVM)

Proxmox VE manages KVM virtual machines via the qm CLI and the web UI. Sensible defaults are applied automatically; key settings affect performance, portability, and storage behavior.

Signature / Usage

# Create a VM
qm create <vmid> --name myvm --memory 2048 --cores 2 --net0 virtio,bridge=vmbr0

# Start / stop / status
qm start <vmid>
qm stop <vmid>
qm status <vmid>

# Convert VM to template
qm template <vmid>

# Live migrate to another node
qm migrate <vmid> <target-node> --online

Options / Props

CPU

Memory

Disk

Network

Firmware

Cloud-Init

Notes

• Use VirtIO SCSI single with iothread=1 as the modern default disk controller for Linux VMs
• Setting --cpu host provides maximum performance but prevents live migration across different CPU families
• Dynamic memory (balloon) adds memory when host usage is below 80%; leave enabled unless debugging
• qm migrate --online requires shared storage or storage migration support
• Memory encryption (SEV) on AMD EPYC prevents snapshots and live migration

Related

• storage.md
• ha.md
• backup-restore.md

Proxmox VE Daemons

Core Proxmox VE background daemons. Each runs as a systemd service and can be controlled with systemctl start|stop|restart|status <name> or the daemon's own CLI.

Signature / Usage

External client
    │ HTTPS :8006
    ▼
pveproxy (www-data)
    │ HTTP :85 (privileged ops)
    ▼
pvedaemon (root)
    │ reads/writes
    ▼
pmxcfs (/etc/pve) ←→ Corosync ←→ other nodes

Options / Props

Notes

Key Ports

• pvedaemon and pveproxy are the API stack: never expose port 85 externally.
• pve-ha-crm and pve-ha-lrm work together: CRM holds the cluster view, LRM executes on each node. Both rely on pmxcfs locks for coordination.
• pmxcfs must be running before most other PVE services start; it provides /etc/pve which holds all cluster config.
• Worker counts for pvedaemon and pveproxy are both controlled by MAX_WORKERS in their respective /etc/default/ files.

Services

API Automation

Automate Proxmox VE operations via the REST API (curl + API token) and the pvesh CLI wrapper.

# --- API Token authentication ---
# Create a token in the GUI: Datacenter > Permissions > API Tokens
# Or via pvesh:
pvesh create /access/users/root@pam/token/monitoring --privsep 0

# Token format: USER@REALM!TOKENID=UUID
TOKEN="root@pam!monitoring=aaaaaaaaa-bbb-cccc-dddd-ef0123456789"
BASE="https://pve.example.com:8006/api2/json"

# --- Read operations with curl ---

# List cluster nodes
curl -sk -H "Authorization: PVEAPIToken=${TOKEN}" "${BASE}/nodes"

# Get version info
curl -sk -H "Authorization: PVEAPIToken=${TOKEN}" "${BASE}/version"

# List VMs on a node
curl -sk -H "Authorization: PVEAPIToken=${TOKEN}" "${BASE}/nodes/pve1/qemu"

# List containers on a node
curl -sk -H "Authorization: PVEAPIToken=${TOKEN}" "${BASE}/nodes/pve1/lxc"

# --- Write operations with curl ---

# Start VM 123
curl -sk -X POST -H "Authorization: PVEAPIToken=${TOKEN}" \
  "${BASE}/nodes/pve1/qemu/123/status/start"

# Stop VM 123
curl -sk -X POST -H "Authorization: PVEAPIToken=${TOKEN}" \
  "${BASE}/nodes/pve1/qemu/123/status/stop"

# Create a container via API
curl -sk -X POST -H "Authorization: PVEAPIToken=${TOKEN}" \
  --data-urlencode "vmid=101" \
  --data-urlencode "ostemplate=local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst" \
  --data-urlencode "hostname=api-ct" \
  --data-urlencode "memory=512" \
  --data-urlencode "net0=name=eth0,bridge=vmbr0,ip=dhcp" \
  --data-urlencode "storage=local-lvm" \
  "${BASE}/nodes/pve1/lxc"

# --- pvesh: direct CLI access to the same API ---

# Get cluster node list
pvesh get /nodes

# Get VM status
pvesh get /nodes/pve1/qemu/123/status/current

# Start a container
pvesh create /nodes/pve1/lxc/101/status/start

# List all users
pvesh get /access/users

# Create a new user
pvesh create /access/users --userid deploy@pve

# Update cluster options (e.g., set default console to html5)
pvesh set /cluster/options --console html5

# Inspect available API endpoints under a path
pvesh ls /nodes/pve1

Notes

• API tokens with --privsep 0 inherit the owner's full permissions; use --privsep 1 and assign minimal ACLs for service accounts.
• curl -sk disables certificate verification (-k) for self-signed certs; replace with -cacert /etc/pve/pve-root-ca.pem in production.
• Write operations (POST/PUT/DELETE) via curl do not need a CSRFPreventionToken header when using API tokens (only ticket-based auth requires it).
• All API calls return UPID task IDs for async operations; poll GET /nodes/{node}/tasks/{upid}/status to track completion.

Backup and Restore

Back up VMs and containers with vzdump, restore with qmrestore/pct restore, and schedule recurring jobs.

# --- On-demand backups ---

# Snapshot-mode backup of VM 123 to a storage (no guest downtime)
vzdump 123 --storage my_backup_storage --mode snapshot --compress zstd

# Backup a container (suspend mode for consistency)
vzdump 200 --storage my_backup_storage --mode suspend --compress zstd

# Backup all guests at once, send notification email
vzdump --all --mode snapshot --storage my_backup_storage --mailto admin@example.com

# Backup multiple specific guests
vzdump 101 102 103 --storage my_backup_storage --compress zstd

# Backup all guests except specific IDs
vzdump --all --mode suspend --storage my_backup_storage --exclude 101,102

# Limit backup bandwidth to 100 MiB/s
vzdump 123 --storage my_backup_storage --bwlimit 102400

# Backup with retention pruning (keep last 3, last 13 daily, last 9 yearly)
vzdump 123 --storage my_backup_storage --prune-backups keep-last=3,keep-daily=13,keep-yearly=9

# --- Restore ---

# Restore a VM backup to new VMID 601
qmrestore /mnt/backup/vzdump-qemu-123-2024_01_15.vma.zst 601

# Live-restore VM (starts immediately, data loads in background — PBS only)
qmrestore /mnt/backup/vzdump-qemu-123.vma 601 --live-restore

# Restore a container backup to new CTID 600
pct restore 600 /mnt/backup/vzdump-lxc-200-2024_01_15.tar.zst

# Clone a container to CTID 300 via pipe (no intermediate file)
vzdump 200 --stdout | pct restore --rootfs 4 300 -

# --- Default settings via config file ---
# /etc/vzdump.conf
# storage: my_backup_storage
# mode: snapshot
# compress: zstd
# bwlimit: 10000

# --- Schedule daily backups at 22:00 (legacy cron) ---
# Add to /etc/cron.d/vzdump or use the Datacenter > Backup GUI scheduler:
# 0 22 * * * root /usr/sbin/vzdump --all --mode snapshot --storage my_backup_storage

Notes

• Backup modes: snapshot (no downtime, requires snapshot-capable storage), suspend (brief pause), stop (full downtime but always consistent).
• zstd compression offers the best speed/ratio trade-off; use gzip when compatibility with older tools matters.
• --prune-backups runs pruning immediately after backup; configure storage-level retention in Datacenter > Storage for continuous pruning.
• Live restore (--live-restore) is only available with Proxmox Backup Server (PBS) as the storage target.

Cluster Setup

Create a Proxmox VE cluster, join nodes, verify quorum, and remove nodes using pvecm.

# --- On the first node: create the cluster ---

# Create a new cluster (name cannot be changed later)
pvecm create my-cluster

# Verify the cluster was created and check quorum
pvecm status

# List current members
pvecm nodes

# --- On each additional node: join the cluster ---

# Join by specifying an IP address of any existing cluster member
pvecm add 10.0.0.1

# If using a dedicated cluster network on a separate interface:
pvecm add 10.0.0.1 --link0 10.10.0.2

# After joining, verify from any node
pvecm status
pvecm nodes

# --- Removing a node ---

# Ensure the node to be removed is powered off or out of the cluster.
# Run from a remaining cluster node:
pvecm delnode oldnode

# If quorum is lost during removal, temporarily lower the expected votes:
pvecm expected 1
pvecm delnode oldnode

Notes

• The cluster name follows the same naming rules as node names and cannot be changed after creation.
• All nodes must have synchronized time (NTP/Chrony) before forming a cluster; drift causes split-brain.
• Corosync requires UDP ports 5405–5412 to be open between all nodes.
• Recommended maximum latency between nodes is under 5 ms; high latency causes quorum instability.
• After pvecm add, the new node inherits the cluster configuration from the existing node automatically.

Container Lifecycle

Create, start, configure, snapshot, and restore LXC containers using pct and pveam.

# --- Fetch a container template ---

# Update the template list from online repositories
pveam update

# List available templates (filter by section)
pveam available --section system

# Download a template to local storage
pveam download local debian-12-standard_12.7-1_amd64.tar.zst

# Confirm the template is available locally
pveam list local

# --- Create and start a container ---

# Create container CTID 100 using the downloaded template
# rootfs on local-lvm with 8 GB, 512 MB RAM, bridged network
pct create 100 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
  --rootfs local-lvm:8 \
  --memory 512 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --hostname mycontainer \
  --password secretpassword \
  --unprivileged 1

# Start the container
pct start 100

# Open a shell inside the container
pct enter 100

# --- Resource configuration ---

# Set CPU and memory limits; enable auto-start at boot
pct set 100 --cores 2 --cpulimit 0.5 --memory 1024 --onboot 1

# Add a bind-mount from the host
pct set 100 --mp0 /mnt/bindmounts/shared,mp=/shared

# --- Snapshots ---

# Create a snapshot before changes
pct snapshot 100 snap1 --description "Before updates"

# List all snapshots
pct listsnapshot 100

# Roll back to a snapshot (and start the container afterward)
pct rollback 100 snap1 --start 1

# Delete a snapshot
pct delsnapshot 100 snap1

# --- Stop and remove ---

# Graceful stop
pct stop 100

# Destroy the container (remove disk and config)
pct destroy 100

Notes

• CTID must be unique across the cluster (range 100–999999999).
• Snapshots require storage that supports them (e.g., ZFS, LVM-thin); classic dir storage does not.
• Use --unprivileged 1 for better isolation; privileged containers run as root on the host and should be avoided unless necessary.
• pveam download stores templates under <storage>:vztmpl/; reference the full path when calling pct create.

samples