Where configuration actually lives

Why this matters in production

When a disk fills up, a configuration file corrupts, or a node is rebuilt, the first question is: where is the configuration I need to preserve? This lesson gives a complete map, so you never have to guess.

The mental model

Proxmox has three layers of configuration:

1. Cluster-wide (/etc/pve/) — replicated via pmxcfs. Anything here is automatically consistent across the cluster (assuming quorum).
2. Node-local (/etc/pve/nodes/<nodename>/ plus traditional /etc/ paths) — written per-node. Survives cluster reconfiguration, but must be backed up per node.
3. Per-VM / per-container (/etc/pve/qemu-server/<vmid>.conf, /etc/pve/lxc/<ctid>.conf) — these are cluster-wide because the VM must be live-migrable.

flowchart LR
  subgraph CW[Cluster-wide — pmxcfs]
    A["/etc/pve/qemu-server/"]
    B["/etc/pve/lxc/"]
    C["/etc/pve/storage.cfg"]
    D["/etc/pve/user.cfg"]
    E["/etc/pve/ha/"]
    F["/etc/pve/sdn/"]
    G["/etc/pve/ceph.conf"]
  end
  subgraph NL[Node-local]
    H["/etc/pve/nodes/<node>/"]
    I["/etc/network/interfaces"]
    J["/etc/default/grub"]
    K["/etc/pve/priv/"]
    L["/etc/pve/nodes/<thisnode>/priv"]
  end

The complete map

Cluster-wide (/etc/pve/)

Node-local (/etc/pve/nodes/<nodename>/ and /etc/)

VM disks and runtime state

How tools write

GUI walkthrough

The GUI exposes config through “Configuration” sections in the tree:

• Datacenter → Configuration — clustering, users, storage, firewall, SDN, HA, replication.
• Node → Configuration — network, DNS, certificates, subscription.

Each section has a Revert button that restores the previous file from the pmxcfs snapshot. This is invaluable when an edit went wrong.

CLI walkthrough

ls -la /etc/pve/

cat /etc/pve/storage.cfg

pmxcfs-tool status && pmxcfs-tool versions

Production considerations

• Version-control your config. A simple cron job that tars /etc/pve/ and pushes to a Git repo (or etckeeper) gives you auditability and roll-back. The files are text.
• Back up /etc/pve/ off-host. pmxcfs replicates across the cluster but is not a backup. If all nodes lose their disks, the config is gone.
• Restoration on a fresh node is fast. Drop the old /etc/pve/ (cluster-join process handles sync) and the new node joins with all VM configs intact.

Common mistakes

• Trying to back up /etc/pve/<file> per node. Files in /etc/pve/ are the same on every node (pmxcfs replicates). Backing up from one node is sufficient.
• Confusing /etc/pve/priv (cluster-wide keys for things like PBS storage credentials) with /etc/pve/nodes/<local>/priv (node-local secrets like Ceph keyrings).
• Editing config files on a node that has lost quorum. Edits succeed locally but cannot propagate.

Key takeaways

• /etc/pve/ is the cluster filesystem (pmxcfs); replicated, authoritative.
• /etc/pve/priv/ is per-node secrets; not replicated.
• All config is text and human-readable. This is a feature.

Knowledge check