Local archive
The local destination writes a single compressed tar archive to any writeable directory on the host: an internal disk, an NFS or SMB mount, or a USB drive.
One file, self-contained
hostcfg-HOST-TIMESTAMP.tar.zst file (or .tar.gz when zstd is absent). The file contains the entire archive tree — manifest.json, metadata/ and rootfs/ — and can be restored on any Proxmox host with the ProxMenux restore flow, or extracted manually with tar --zstd -xf on any Linux system. No server, no repository init, no external dependency. This is the destination with the shortest recovery path when neither PBS nor Borg is available.Configuring the target directory
The local destination is a single persisted target directory — not a list. ProxMenux stores the operator's choice at /usr/local/share/proxmenux/local-target.conf and reads it on every backup. When no target has been configured, the default HB_LOCAL_TARGET_DEFAULT = /var/lib/vz/dump is used (the same directory Proxmox uses for its own vzdump outputs). The target is configured from Configure backup destinations → Local destinations:
- •Use default (
/var/lib/vz/dump). The Proxmox local storage. Present on every Proxmox install; the archive sits next to vzdump outputs and is picked up by the Monitor's Backups tab automatically. - •Enter a custom path. Any absolute filesystem path can be used: an NFS mount, an SMB share mounted via
fstab, a dedicated ZFS dataset, a second internal disk. ProxMenux validates that the path exists and is a directory before persisting it. - •Pick a USB drive. Opens the USB submenu (below), which detects removable devices and offers to mount or format one.
USB drive detection and mounting
The USB submenu lists partitions on removable devices reported by lsblk. Each partition is presented with its size, filesystem label and current state. The state determines the action ProxMenux offers.
The three device states
| State | Menu entry | Action |
|---|---|---|
| mounted | Size · label · [fstype] · → /mount/point | The partition is already mounted somewhere. Selecting it persists the current mount point as the local target. No mounting is performed. |
| unmounted | Size · label · [fstype] · (not mounted — will be mounted) | A filesystem is present but not mounted. On confirmation, ProxMenux runs hb_mount_usb_partition: creates /mnt/backup-LABEL (or a UUID-based path if there is no label), mounts the partition and persists the mount point as the local target. |
| empty | Size · raw USB disk — no filesystem (will be FORMATTED) | The device has no filesystem. A destructive path — protected by two confirmations. First a Yes/No dialog explains that the operation will erase the disk. Second, an inputbox requires the operator to type the exact device path (e.g. /dev/sdb) before ProxMenux creates a fresh GPT + ext4 partition and mounts it. |
When no USB device is detected, the submenu falls back to a plain inputbox. The operator can enter an arbitrary mount point path; if the path is not a registered mount point, a confirmation dialog warns before proceeding.
Safety check — destination inside a backup path
Before writing the archive, _bk_local verifies that the destination directory is not a subpath of any directory being backed up. A common footgun would be adding /root to the profile and picking /root/backups as the destination — the archive would then include itself, either producing a corrupt archive or growing without bound until the disk fills. The check resolves both paths with readlink -m, compares them and, on conflict, aborts the backup with a dialog that names the conflicting path and lists three ways to resolve it: choose a destination outside the conflicting path, remove the custom entry that contains the destination, or use Custom mode to uncheck the conflicting path for this run.
Archive format and compression
The output filename embeds the source hostname and the backup timestamp so that a directory holding several archives sorts chronologically and each file is self-identifying.
hostcfg-HOSTNAME-YYYYMMDD_HHMMSS.tar.zstCompression
The primary path uses tar --zstd -cf — a single-command pipeline that compresses at zstd's default level. When zstd is not present on the source (rare on Proxmox but possible on minimal installs), ProxMenux falls back to gzip. In the fallback path, if pv is available, a progress bar is added to the pipeline so the operator sees the archive size grow in real time; without pv, plain tar -czf is used silently.
What goes into the archive
The tar command is invoked with -C "$staging_root" ., which archives the full staging root: rootfs/, metadata/ and manifest.json. All three payloads land side by side at the top of the tarball. Extracting the archive produces the exact same tree that the restore code consumes.
The sidecar JSON
Every successful local backup produces a companion file: HOSTNAME-TIMESTAMP.tar.zst.proxmenux.json, written next to the archive by hb_write_archive_sidecar. This small JSON file lets the ProxMenux Monitor identify the archive as a ProxMenux host backup even if it is later moved, renamed or archived elsewhere.
Sidecar contents
The sidecar stores the schema version, whether the backup came from an interactive run or a scheduled job (kind), the job ID for scheduled runs, the profile mode used (default or custom), the source hostname, the original archive basename, an ISO-8601 creation timestamp and the archive size in bytes.
The Monitor's Backups tab scans configured local directories for *.proxmenux.json sidecars — not for *.tar.zst files — because a .tar.zst without a sidecar might not be a ProxMenux backup at all. The scan is fast (JSON files are tiny) and the pairing is stable across renames of the archive as long as the sidecar is renamed to match.
Restoring from a local archive
The ProxMenux restore flow discovers local archives by scanning the configured local target for sidecars and displaying them in the Archives list. Selecting one triggers _rs_check_layout, which extracts the tarball into a staging directory and confirms the three-payload layout before proceeding. For manual extraction outside of ProxMenux, tar --zstd -xf hostcfg-HOSTNAME-TIMESTAMP.tar.zst -C /tmp/hostcfg yields the same tree the restore code consumes.