Proxmox VE Operations Reference (Release 9.1.2)
Nodes, guests, and services can be down, unreachable, or vanish mid-operation. Never assume one is
up: re-query real state, retry under a timeout, and degrade gracefully. For the self-healing
patterns, see bitranox:coding-resilience.
1. Cluster Configuration (Auto-Detect)
| Check | Command |
|---|---|
| Environment | pveversion --verbose (full component versions: kernel, pve-manager, corosync, qemu-server) |
| Nodes | pvecm nodes (count, names, IDs) / pvecm status (IPs, quorum, transport, link states) |
| Quorum | pvecm status -- check "Quorate" field. Threshold: floor(total_nodes/2) + 1 |
| API Access | pvesh (local CLI), pveproxy (HTTPS :8006), REST API. Use --output-format json for scripts |
| Storage | pvesm status (active storages) / cat /etc/pve/storage.cfg (full config) |
| Network | pvesh get /nodes/{node}/network --output-format json / cat /etc/network/interfaces |
| Subscription | pvesubscription get (check status) / pvesubscription set <key> (apply key) |
2. Safety Protocols
| Rule | Details |
|---|---|
| No destructive bulk ops | Commands affecting >1 node (reboot, shutdown, bulk VM stop) require explicit user confirmation. |
| Quorum check | Before node reboot/maintenance: pvecm status. If (current - 1) < floor(total/2) + 1 -- abort. On 2-node clusters, check QDevice. |
| Backup first | Before VM config changes or upgrades, verify backup exists: pvesm list {storage} --content backup |
| No force delete | Never --purge or --force without verifying resource ID: qm config {vmid} or pct config {vmid} |
| HA status | Before HA resource changes: ha-manager status -- verify no migrations/fencing in progress. |
| Network changes | Always dry-run first: ifreload -a -n (ifupdown2 has no --test). Never ifdown on a bridge carrying guest traffic. Remote apply and DHCP/bond/WLAN traps: references/host-networking.md. |
| Corosync config | Copy first, edit copy, backup current, then move. Always increment config_version. |
| Storage ops | Before removing storage: pvesm list {storage} to verify no VMs/CTs reference it. |
| Protection flag | qm set {vmid} --protection 1 / pct set {vmid} --protection 1 to prevent accidental deletion. |
| ZFS property sweeps | PVE stores a guest's configured disk size AS the dataset's refquota. A sweep that clears refquota/refreservation across all datasets silently removes every guest's disk limit while pct config still reports the old size, so one container can fill the pool. Exclude leaf names starting subvol- or vm-. |
3. Action Review Protocol
Mandatory. Perform this review before every action executed directly on a Proxmox node, VM, or container (commands, config changes, service operations).
Exception: Read-only operations - reading logs, querying status, gathering information without changing anything - are considered safe and can be performed immediately without this review.
Run this gate on
opus. This steelman / red-team judgment gates a change to LIVE infrastructure - a weaker model under-weights outage, data-loss, and quorum risk. Do the review onopus: delegate it to a pinnedopussubagent at effortmedium(review dispatch, see bitranox:process-agents-subagent-driven-development "Review dispatches"), or (if you keep it inline) offer switch-model-or-continue BEFORE executing. Never run this gate on an unknown lesser tier. Seebitranox:process-agents-subagent-driven-development("The session model is fixed" / "Concrete tiers").
3.1 Steelman Prompt
Consider the planned action or configuration to be executed on the Proxmox server in its ideal, most successful form. Imagine this action represents the safest, most efficient, and optimally integrated solution. Articulate how this action perfectly fulfills the goals of system administration, increases stability, and fully meets user needs.
3.2 Red-Team Prompt
Review the planned Proxmox action as if you were an experienced admin or security analyst seeking to uncover potential risks. Identify possible weaknesses in the configuration, consider outage risks, data loss, or unintended side effects. Test the robustness of the plan under worst-case scenarios to ensure it remains safe and reliable even under pressure.
3.3 Decision
At the end of the red-team review, assess whether the identified risks or weaknesses are severe enough to stop the planned action. If the action appears safe, logical, and robust, it can be executed immediately. If significant uncertainties remain, the user must be explicitly asked for confirmation. Conclude with a clear decision: either "Execute action" or "Ask user for confirmation".
4. Code & Response Style
- Responses: Short, precise, CLI-focused (
pvesh,pvecm,pvesm,qm,pct,ha-manager,vzdump,pvesr,pvenode,pveceph,pveum,pveam). - Troubleshooting: Always query logs first:
journalctl -u pvedaemon -n 50,pvenode task list --errors 1,/var/log/pveproxy/access.log. - JSON preference: Use
--output-format jsonorjson-pretty. Use--noborder --noheaderfor scripted parsing. - Rollback plan: Every change must include rollback. Back up config files first. Ensure backups exist before storage/VM changes.
5. Cluster Size Quick Table
| Size | Behavior |
|---|---|
| Single node | No cluster ops. No HA. Focus on local storage + external backups. |
| 2-node | QDevice strongly recommended. Without it: 1 node loss = quorum loss. pvecm expected 1 for emergency. |
| 3+ nodes | Full HA. Tolerates floor((N-1)/2) failures (3 nodes: 1, 5 nodes: 2). |
Detect node count: pvecm nodes | grep -c '^\s*[0-9]'
6. Troubleshooting Quick Reference
| Problem | Diagnosis |
|---|---|
| Cluster not quorate | pvecm status > "Quorate: No". Check connectivity, systemctl status corosync. Emergency: pvecm expected 1. |
| Node won't join | Verify UDP 5405-5412, time sync, SSH (TCP 22). Try: pvecm add {IP} --fingerprint {SHA256}. |
| VM won't start | Check lock: qm config {vmid} | grep lock. Storage: pvesm status. Log: pvenode task list --vmid {vmid}. |
| CT won't start | Check lock: pct config {vmid} | grep lock. Try: pct fsck {vmid}. Log: journalctl -u pve-container@{vmid}. |
| Storage offline | pvesm status (check active). NFS: mount | grep nfs. Ceph: ceph -s. iSCSI: iscsiadm -m session. |
| Migration fails | Target storage: pvesm status --target {node}. Locks: qm unlock {vmid}. Network: ping {target}. |
| HA fencing | journalctl -u pve-ha-crm -n 100. Watchdog: cat /dev/watchdog (should error if active). |
| Slow GUI | MAX_WORKERS=5 in /etc/default/pveproxy, then systemctl restart pveproxy.service. |
| Backup failures | Space: pvesm status. Logs: /var/log/vzdump/{vmid}-*.log. PBS: verify connectivity. |
| Ceph issues | ceph health detail, ceph osd tree, ceph pg stat. Maintenance: ceph osd set noout. |
| NIC names changed | ip link show. Pin: pve-network-interface-pinning generate. Check /etc/network/interfaces. |
| Windows VM ~25% slower | cpu: host exposes vmx, so Win11 auto-enables VBS (~25% CPU penalty). A no-vmx model (IvyBridge/x86-64-v2-AES) keeps VBS off; Docker must then use process isolation (isolation=process in daemon.json exec-opts), because hyperv-container isolation rides the same VBS hypervisor. Confirm in the guest: (Get-CimInstance -Namespace root\Microsoft\Windows\DeviceGuard -ClassName Win32_DeviceGuard).VirtualizationBasedSecurityStatus reads 2 while VBS runs and 0 when it is off. Disabling HVCI/Credential Guard in the registry leaves it at 2 on a vmx guest; only bcdedit /set hypervisorlaunchtype off drops it, and that also removes hyperv isolation, so full speed and hyperv isolation exclude each other. kvm64 does not boot Win11 (no SSE4.2/POPCNT). Prefer the named model of the OLDEST node's CPU generation (appendix-e-vcpu-list.md) over x86-64-v2-AES: they tie on plain compute, the named one also exposes AVX and the like, and it stays migration-safe. A named model exposes no vmx unless the nested-virt flag is added; the status check above confirms it. |
| Cloned VM missing a disk | qm clone only brings the VM's CONFIGURED/managed disks. A base that keeps app data on a separate disk (e.g. Docker data-root on D:) loses it on clone (dockerd fails "Incorrect function"). Repoint the app or attach the disk. |
| Cloned VM has no network | qm clone (linked or full) gives the clone new MACs, so any NIC naming keyed on the MAC misses. A PVE 9 install pins nic0/nic1 with /usr/local/lib/systemd/network/50-pmx-nic*.link files matching MACAddress=: a clone of a nested-PVE template boots with ens18/ens19 and a port-less vmbr0 (measured on a 9.1 template). Before qm template, rewrite each .link to match Path= instead (the ID_PATH from udevadm info /sys/class/net/<nic>, e.g. pci-0000:06:12.0), which every clone shares: [Match] Path=pci-0000:06:12.0 Type=ether, [Link] Name=nic0. Prove it with one clone before relying on it: ip -br link there lists nic0/nic1 and bridge link shows nic0 as a port of vmbr0. A guest config matching the MAC elsewhere (netplan match: macaddress) fails by the same mechanism (not measured here). |
| One VM starved under load | The lever is cpuunits (cgroup weight): raise the priority guest above the default, which is 100 under cgroup v2 and 1024 only on a host still on legacy cgroup v1 (qm set <vmid> --cpuunits 800 gives it 8x a default guest's share; weight is relative, so the number only means anything next to the others). Leave or lower the batch guests. Weight only biases the scheduler UNDER contention, so batch peak throughput is untouched - unlike cpulimit, which hard-caps it. Size vCPUs to the guest's real concurrency (static), NOT via hot-plug, and derive multi-queue counts from the BOOT vCPU count rather than a hot-add ceiling. |
| Reading PSI from the API | The rrddata pressure keys are pressurecpu{some,full}, pressureio{some,full}, pressurememory{some,full} - note pressurememory, NOT pressuremem*. Dump the keys of a real record (pvesh get /nodes/<n>/qemu/<vmid>/rrddata --output-format json) rather than guessing a name. |
| Snapshot/backup a guest | Use ONLY native PVE: qm/pct snapshot/rollback/delsnapshot and vzdump/PBS. NEVER a manual zfs snapshot of the guest zvols or a hand-MADE [snapshot] conf section - qm keeps the snapshot's config in sync with the live guest; manual zfs does not. Editing KEYS inside a section qm snapshot made is fine, and is the only way to change one: qm set edits the live section only. Write the conf WHOLE (read, change, write back), since sed -i fails on pmxcfs. On zfspool storage qm rollback reaches only the NEWEST snapshot (is not most recent snapshot): see references/zfs-guest-disks.md. |
| Toggle an apt repo (CLI) | pvesh create /nodes/<node>/apt/repositories --path <file> --index <i> --enabled 0 (or 1) - a POST changes an existing entry; read path and index from pvesh get /nodes/<node>/apt/repositories --output-format json. pvesh set on that path is the ADD-a-standard-repository call (by --handle) and fails Unknown option: path. Verify in the file itself (Enabled: false in a .sources file) and with apt-get update; echo rc=$?. |
| PBS storage shows 0 KiB | A PBS storage whose API token holds DatastoreAdmin only on a child NAMESPACE (/datastore/<ds>/<ns>) is listed active with 0 total, used and available in pvesm status (observed PBS 4.2 with PVE 9.1), while backup, restore and namespace create/delete through it all work. Do not read the zeros as a broken storage: prove it with a small backup and pvesm list <storage>. |
| PBS token from the CLI | proxmox-backup-manager user generate-token <user> <name> has no --output-format (passing one fails parameter verification) and prints Result: {...}: parse the JSON from the first { and store the secret at once, it is shown only this time. A token's effective rights are its OWN ACL entries intersected with its user's: give the token its own ACL entries, and expect it never to exceed the user. Read the result with proxmox-backup-manager user permissions '<user>@<realm>!<token>' --path <path>. Call proxmox-backup-debug api with --output-format json in a script: a call whose text output fails may already have taken effect, so read the state before retrying. |
CLI qm call blocks / VM still locked after stop | From the CLI, qm start/shutdown/stop and pvesh create .../status/* wait for their task to END, so qm shutdown --timeout N || qm stop hard-stops a guest still shutting down cleanly. Detach (setsid -f qm shutdown ...), read the UPID from pvesh get /nodes/<node>/tasks --vmid <vmid> --since <epoch>, poll its status, and wait for the task, not for qm status stopped, before the next qm on that vmid: the config lock outlives the stop. Filing a task of your own: same file. references/pve-tasks.md. |
qm set on a running VM | Hot-plugs every key the hotplug option covers (default network, disk, usb) into the LIVE guest at once; only the rest goes [PENDING]. An IDE/SATA CD-ROM is staged only: it appears after a full stop and qm start, not after a reboot inside the guest. references/running-vm-config-and-exit.md. |
| How did the VM end? | Power-off, qm stop and a killed QEMU all log scope: Deactivated successfully. Run qmeventd -v (its graceful/guest flags tell the three apart), or look for the kernel's tap<vmid>i<N> (unregistering) line, which only a signal-killed QEMU leaves. references/running-vm-config-and-exit.md. |
| VM Notes not in the .conf | The Notes (qm set <vmid> --description) are stored as the leading # comment lines of <vmid>.conf, not as a description: key, so grepping the file for description: finds nothing although the Notes are set. qm config <vmid> prints them as one encoded description: line. They belong to the live config only: qm snapshot does not copy them, and the # lines right after a [snapshot] header are that snapshot's own description. |
| External VNC viewer | The API vncproxy call without websocket opens a one-shot PLAIN-VNC port with a generated password; qm vncproxy over ssh needs LC_PVE_TICKET; a bare ssh -L to /var/run/qemu-server/<vmid>.vnc fails VNC auth. references/external-vnc-viewer.md. |
| ZFS guest volumes | A storage ID is not the dataset prefix (pvesm path <volid>); rollback reaches only the newest snapshot; qm clone --snapname cannot full-clone from a zfspool snapshot (zfs send/recv instead); un-templating means renaming base- volumes back; growing a ZFS-root guest needs the partition and pool grown too. references/zfs-guest-disks.md. |
| Change a VM's VMID | No command renumbers a guest, and qm clone to the new id drops every snapshot. On zfspool storage rename the volumes and the conf by hand, VM stopped, after checking the new id is free in the whole cluster (pvesh get /cluster/nextid --vmid <new> fails with VM <new> already exists when it is taken) and finding the other files naming the old id (backup jobs, firewall, HA, replication, pools): references/zfs-guest-disks.md. |
| Docker in an UNPRIVILEGED CT | Needs THREE things, not one. features: keyctl=1 (a no-op on a privileged CT - PVE's schema says "for unprivileged containers only", so do not copy it from a working privileged CT as though it were the fix there), lxc.apparmor.profile: unconfined, AND dpkg-divert --rename --add /usr/sbin/apparmor_parser INSIDE the container. Without the divert every docker run fails: Could not check if docker-default AppArmor profile was loaded: open /sys/kernel/security/apparmor/profiles: permission denied. That path IS visible in the CT but is idmapped to nobody, so docker probes it, concludes AppArmor is available, and cannot read it. A PRIVILEGED CT fails DIFFERENTLY (apparmor_parser: Access denied. You need policy admin privileges) and needs no divert - the fix does not carry between the two kinds. Put the divert in a post-deploy hook, or a rebuild loses docker silently. This is the AppArmor half only: the CT also needs nesting=1 alongside keyctl=1, and inside it the iptables backend switched to legacy, or dockerd fails network setup instead - see ch11-containers/security-and-os-config.md, which covers that half. |
| Docker in a PRIVILEGED CT | Fails with apparmor_parser: Access denied. You need policy admin privileges to manage profiles: docker loads its own docker-default profile at container start, which needs CAP_MAC_ADMIN, and the default LXC drop list removes it. Fix in the CT config: lxc.apparmor.profile: unconfined plus an empty lxc.cap.drop: line. No apparmor_parser divert, and keyctl=1 does nothing here (unprivileged only). Check unprivileged: in pct config before copying docker settings between CTs: the two kinds need different sets. |
| CT memory limit / rare OOM | Do not wait for the next rare kill: oom_kill stays 0 on every boot until the one where reclaim loses the race, so a clean boot proves nothing for a 1-in-N fault. Restart the CT (its cgroup is recreated at start, so the peak begins fresh), let it run its heaviest phase (boot-time updates included), then read /sys/fs/cgroup/lxc/<vmid>/memory.peak and memory.events. A peak equal to the limit with high (throttled by reclaim) or max events counting means undersized, killed or not. Raise it (pct set <vmid> --memory <MiB>), restart, re-read: size from the new peak with headroom and require high and max to stay 0. echo 0 > memory.peak exits 0 but resets the peak only for reads through that same file descriptor, so a later cat shows the old value; a CT restart is the reset. A limit set only in /etc/pve/lxc/<vmid>.conf is host state no guest deploy carries: record it where the guest is documented. |
| Restored CT as a new machine | pct restore keeps the source's identity, not just its data, and nothing shows while the CT is stopped. Before the FIRST start, against the stopped rootfs (pct mount <id>): a fresh MAC (pct restore ... --unique 1) and the new address via pct set <id> --net0 ...,hwaddr=<that MAC>,ip=<new>, because --hostname and --onboot given to the restore apply but a --net0 given to it is silently ignored, its ip= too (measured on pve-container 6.1.16: the copy kept the source's static ip); read back pct config <id> | grep ^net0 for both, blank /etc/machine-id and delete /var/lib/dbus/machine-id, regenerate the SSH host keys, set the hostname, nameserver/searchdomain and description (inherited verbatim, it describes the source), grep every unit for the source's checkout path (a service may RUN from it), and blank the application's own site data. If the first pct start exits 1 with unable to get PID for CT <id> (not running?), read pct status <id> before retrying: the CT may be running. Checklist and ground-truth verification: references/restored-guest-identity.md. |
pveam picks an arm64 template | pveam available lists an arm64 build beside the amd64 one of the same template (debian-13-standard_<ver>_amd64.tar.zst and ..._arm64.tar.zst), so selecting a template by name with grep or awk can pick the wrong architecture. Match _amd64 (the node's architecture) in the name. |
pct create: "You may need to enable nesting" | Systemd <ver> detected. You may need to enable nesting. is pve-container's warning for a CT whose systemd is newer than 241 and whose features lack nesting=1 (Debian 13 and current distributions). The GUI wizard ticks Nesting for an unprivileged CT; pct create sets nothing, so pass --features nesting=1 at create time rather than a stop, pct set, start round afterwards. |
| Fresh PVE 9 node gaps | Each looks like a failure of the step you are on. (1) A bare install may lack git and rsync (observed on PVE 9.2): a repo clone or file sync dies on git: command not found, which reads as an auth or path problem; check each tool alone (for t in git rsync; do command -v "$t" >/dev/null || echo "missing: $t"; done; one command -v git rsync can pass with one missing) and install them first (apt-get install -y git rsync). (2) No rsyslog on the Debian 13 base, so no /var/log/mail.log: a test mail grepped there reads as unverified while it was delivered. Verify with journalctl -t postfix/smtp --since "-5 min" and require status=sent. (3) pct restore keeps the source's MAC and static ip, whatever --net0 it is given: see Restored CT as a new machine. (4) vzdump --notes-template needs --storage: see vzdump notes-template 400. (5) On a laptop node the wireless tools (iw, rfkill, wpa_supplicant) are absent too, and iw dev X scan | grep -c ^BSS reads 0 for a missing binary exactly as for a dead radio: read /sys/class/rfkill/*/soft and /hard and the driver's boot messages instead. |
| vzdump notes-template 400 | vzdump --notes-template requires --storage. With --dumpdir (a plain directory) the API refuses the job before writing anything: 400 Parameter verification failed. storage: missing property required by 'notes-template'. Back up to a configured storage (--storage <id>; add the directory as a dir storage if needed), or drop the notes. |
| apt-get update exits 100 | On a host without a subscription the enterprise repo answers 401 Unauthorized, and apt treats that as a hard error: apt-get update exits 100, so every update run, scheduled or manual, fails while pve-no-subscription has the packages. A disabled pve-enterprise.list proves nothing: an upgrade to a new major release can add the deb822 /etc/apt/sources.list.d/pve-enterprise.sources enabled. Find every entry with grep -rn enterprise.proxmox.com /etc/apt/sources.list /etc/apt/sources.list.d/, disable each with an Enabled: no line (a .sources file) or a comment (a .list file), and configure pve-no-subscription (ch03-host-admin/package-repositories.md). Verify with apt-get update; echo rc=$? and require rc=0: an updater that fails every run leaves the package versions unchanged, exactly like one with nothing to do. |
| Reading the PVE repo from a script | https://download.proxmox.com fails certificate verification (its certificate names enterprise.proxmox.com and the CDN hosts), and the no-subscription and test suites are not on enterprise.proxmox.com (401 without a subscription). Fetch over http as apt does and trust only the gpgv-verified InRelease, checking gpgv's exit code; the signed test component is pve-test, not pvetest. Steps: references/package-repo-from-script.md. |
| DHCP dry-run says timeout | Under ifreload -a -n, an interface being switched to inet dhcp prints dhclient: timeout failed to detect new ip addresses and still exits 0: no-act never applies the stanza, so no address can appear. It is an artifact, not a lease failure. Prove DHCP with dhclient -1 -sf /bin/true -v <iface> (look for DHCPOFFER/DHCPACK; a successful probe daemonizes, so kill it by PID). A /etc/dhcp/dhclient.conf edit is applied by neither ifreload -a nor -f, because the running client is not restarted: plan it as a reboot and verify by the content and mtime of /etc/resolv.conf. Over SSH, arm a rollback timer and apply detached: references/host-networking.md. |
| Bond down: slave NIC absent | bond-primary <nic> naming an absent NIC (a driver that failed to load after a kernel update) aborts the WHOLE bond (ifname <nic> not present in cache, then bridge port bond0 does not exist), while a missing bond-slaves entry is only skipped. Leave bond-primary out and set it after the bond exists: post-up echo <nic> > /sys/class/net/bond0/bonding/primary 2>/dev/null || true. ifquery -a -i <file> checks syntax only: prove the missing-NIC case before the next boot with the node's own ifupdown2 under unshare -mn and veth pairs, NIC absent and present (references/host-networking.md). |
| WLAN bond slave: no traffic | Bridge on an active-backup bond, WLAN standby associated after failover, gateway unreachable: a WiFi station may transmit only its own MAC. It needs BOTH options bonding fail_over_mac=1 in /etc/modprobe.d/ (ifupdown2 has no attribute for it; in interfaces it is ignored) AND an unpinned bridge MAC: PVE's shipped ifupdown2 policy sets bridge_set_static_mac_from_port: yes (/sys/class/net/vmbr0/addr_assign_type reads 3). Override it with /etc/network/ifupdown2/policy.d/<name>.json holding {"bridge": {"module_globals": {"bridge_set_static_mac_from_port": "no"}}} and REBOOT (ifreload cannot unpin a live bridge). Verify addr_assign_type reads 1 and vmbr0's MAC equals bond0's, then test a failover behind an auto-restore. Guests stay dark on the WLAN slave either way: it is a host lifeline only (references/host-networking.md). |
| WLAN drops after ifreload | A wpa-conf line in /etc/network/interfaces associates at boot, but under ifreload -a the ifupdown hook starts the supplicant and kills it in the same second (Successfully initialized, then CTRL-EVENT-TERMINATING), leaving none and no error. For a WLAN that must stay up, use wpa_supplicant@<iface>.service (config /etc/wpa_supplicant/wpa_supplicant-<iface>.conf) with a drop-in adding Restart=on-failure and RestartSec=10 (the packaged unit has no Restart=), and iface <iface> inet manual with no wpa-conf. 4-Way Handshake failed - pre-shared key may be incorrect with a correct passphrase on a module-allowlisted host is a blocked cipher (ccm): read the allowlist log first, see bitranox:infra-modulejail and references/host-networking.md. |
| ZFS member label missing | A member UNAVAIL with label missing or invalid whose partitions never appeared is often a corrupt PRIMARY GPT, not a dead disk: a SATA link error at boot (kernel log: link exception, aborted command, link speed downshift) aborted the reads of the first sectors while the SECONDARY GPT at the end of the disk stayed intact. A passing SMART health check decides nothing; read the counters: 0 reallocated/pending/uncorrectable with a non-zero UDMA_CRC_Error_Count is a cable or connector fault. Recover in place (sgdisk --backup, --load-backup, partprobe, zdb -l, zpool online <pool> <guid>); never zpool replace it and never clone a sibling's GPT. Done only when the cable is fixed and the CRC count has stopped climbing on every member. Procedure: references/zfs-member-label-missing.md. |
| Guest ignores qm shutdown | Without the guest agent, qm shutdown / GUI Shutdown presses the ACPI power button, which a guest with no handler ignores until the task times out. A minimal Alpine ships no acpid: apk add acpid, rc-update add acpid default, rc-service acpid start (busybox has no shutdown; use poweroff). Still ignored with acpid running: check that the kernel registered the fixed-event button (/sys/bus/acpi/devices/LNXPWRBN:00 has a driver link); if not, load tiny_power_button with power_signal=12. Tells, workaround and verify: references/guest-ignores-shutdown.md. |
Deep Reference - Chapter Documentation
For detailed documentation beyond this quick reference, read the relevant chapter file from the skill directory.
Which File Do I Need?
| I need to... | Read |
|---|---|
| Understand PVE features | ch01-introduction.md |
| Install or upgrade Proxmox VE | ch02-installation.md |
| Use advanced installer options | ch02-installation-advanced.md |
| Configure package repositories | ch03-host-admin/package-repositories.md |
| Read the package repo from a script | references/package-repo-from-script.md |
| Set up networking | ch03-host-admin/network-configuration.md |
| Change node networking over SSH | references/host-networking.md |
| Manage ZFS on the host | ch03-host-admin/zfs.md |
| Repair a ZFS member with no label | references/zfs-member-label-missing.md |
| Manage LVM on the host | ch03-host-admin/lvm.md |
| Manage BTRFS on the host | ch03-host-admin/btrfs.md |
| Configure certificates / ACME | ch03-host-admin/certificate-management.md |
| Configure the bootloader | ch03-host-admin/host-bootloader.md |
| Monitor disk health | ch03-host-admin/disk-health.md |
| Set up time sync / NTP | ch03-host-admin/time-synchronization.md |
| Use the web GUI | ch04-gui.md |
| Create or manage a cluster | ch05-cluster-manager/_index.md |
| Understand pmxcfs | ch06-pmxcfs.md |
| Add or configure storage | ch07-storage/_index.md |
| Deploy Ceph | ch08-ceph/_index.md |
| Set up storage replication | ch09-storage-replication.md |
| Create or manage VMs | ch10-qemu/_index.md |
| Import a VM (OVF, disk images) | ch10-qemu/importing-vms.md |
| Set up PCI passthrough | ch10-qemu/pci-passthrough.md |
| Use Cloud-Init with VMs | ch10-qemu/cloud-init.md |
| Poll or file a PVE task, CLI blocking | references/pve-tasks.md |
qm set live, cold start, how VM ended | references/running-vm-config-and-exit.md |
| Open a VM console in an external viewer | references/external-vnc-viewer.md |
| ZFS guest volumes: clone, rollback, grow | references/zfs-guest-disks.md |
| Renumber a VMID, keep its snapshots | references/zfs-guest-disks.md |
| Fix a guest ignoring qm shutdown | references/guest-ignores-shutdown.md |
| Create or manage containers | ch11-containers/_index.md |
| Configure SDN | ch12-sdn/_index.md |
| Configure the firewall | ch13-firewall/_index.md |
| Manage users and permissions | ch14-user-management/_index.md |
| Set up High Availability | ch15-high-availability/_index.md |
| Back up or restore VMs/CTs | ch16-backup-restore/_index.md |
| Configure notifications | ch17-notifications.md |
| Manage PVE service daemons | ch18-service-daemons.md |
| Find answers to common questions | ch20-faq.md |
| Look up a CLI command | appendix-a-cli/_index.md |
| Migrate a VM (online/offline) | ch10-qemu/migration.md |
| Migrate a container / CT | ch11-containers/backup-migration-config.md |
| Turn a restored CT into a new machine | references/restored-guest-identity.md |
| Recover quorum / cluster cold start | ch05-cluster-manager/qdevice-advanced.md |
| Evacuate a node / maintenance runbook | ch03-host-admin/node-management.md |
| Use the pvesh REST API | appendix-a-cli/pvesh.md |
| Run Docker on the host / in an LXC | ch11-containers/security-and-os-config.md |
| Benchmark host / manage subscription | ch19-cli-tools.md |
| Check firewall macros | appendix-f-firewall-macros.md |
| Format VM/node notes with Markdown | appendix-g-markdown-primer.md |
| Understand config file format | appendix-c-config-files.md |
| Schedule jobs (calendar events) | appendix-d-calendar-events.md |
| Look up QEMU vCPU types | appendix-e-vcpu-list.md |
| Daemon CLI (pve-firewall, etc.) | appendix-b-service-daemons.md |
Chapter Detail (tier 2)
For topics not in the quick-lookup table, find the right chapter here,
then read its _index.md for sub-topic routing to individual files.
| Topic - key terms | Chapter index |
|---|---|
| Host Admin - repos, updates, firmware, networking, bonding, VLANs, NTP, metrics, disk health, LVM, ZFS, ZFS encryption, BTRFS, node management, certs, ACME, bootloader, GRUB, Secure Boot, KSM | ch03-host-admin/_index.md |
| Cluster - create, join, quorum, corosync, QDevice, cluster network, remove node, rejoin | ch05-cluster-manager/_index.md |
| Storage backends - Dir, NFS, CIFS, PBS, ZFS pool, LVM, LVM-thin, iSCSI, Ceph RBD, CephFS, BTRFS, ZFS-over-iSCSI | ch07-storage/_index.md |
| Ceph - install, config, monitors, managers, OSDs, pools, CRUSH, CephFS, client, maintenance | ch08-ceph/_index.md |
| QEMU/KVM - settings, hardware, CPU, memory, encryption, display, USB, PCI, boot, migration, clones, templates, import, cloud-init, passthrough, hookscripts, hibernation, resource mapping, qm, locks | ch10-qemu/_index.md |
| Containers - LXC, distributions, images, settings, security, apparmor, storage, backup, migration, pct config, locks | ch11-containers/_index.md |
| SDN - zones, VNets, subnets, controllers, fabrics, IPAM, DNS, DHCP, firewall integration | ch12-sdn/_index.md |
| Firewall - directions, zones, cluster.fw, host rules, VM/CT rules, security groups, IP sets, nftables | ch13-firewall/_index.md |
| Users - users, groups, tokens, pools, auth realms, LDAP, AD, OpenID, 2FA, TOTP, WebAuthn, permissions, ACLs, roles | ch14-user-management/_index.md |
| HA - resources, groups, fencing, watchdog, error recovery, maintenance, scheduling | ch15-high-availability/_index.md |
| Backup - modes (snapshot/suspend/stop), fleecing, compression, encryption, jobs, retention, restore | ch16-backup-restore/_index.md |
CLI Reference (Appendix A)
| Tool | File |
|---|---|
| - | general-and-format-options.md |
pvesm | pvesm.md |
pveceph | pveceph.md |
pvenode | pvenode.md |
pvesh | pvesh.md |
qm | qm.md |
qmrestore | qmrestore.md |
pct | pct.md |
pveam | pveam.md |
pvecm | pvecm.md |
pvesr | pvesr.md |
pveum | pveum.md |
vzdump | vzdump.md |
ha-manager | ha-manager.md |