Important
 This is an UNRELEASED version of cfsnap, use for TESTING purposes ONLY.

Synopsis

cfsnap [restore | purge]

Description

cfsnap is a command and associated service with timer that provide regular snapshotting of virtual Proxmox Cluster Filesystem (pmxcfs) mounted by all PVE nodes - clustered and non-clustered alike - at runtime to /etc/pve.

Arguments

With no argument given, creates an instant snapshot of the virtual filesystem.

restore

Restores the most recent snaphost of pmxcfs. The service of pve-cluster is stopped for the restore to proceed and restarted afterwards.

Warning
 If unsuccessful, do NOT run this command multiple times, as on the first run, a backup copy of the to-be-overwritten backend database is put aside. On subsequent runs, the previously restored state would overwrite it.

In a cluster, this should result in e.g. node previously unable to properly start up due to corrupt local instance of pmxcfs to be able to re-join the cluster, catch up on what it had missed and continue participating in the cluster without further troubleshooting necessary.

purge

Removes ALL previous snapshots in the target directory.

Important
 Please purge snapshots after you have made a significant configuration change to the node, e.g. such as have it join a cluster.

Services

cfsnap.service

Service is activated 5 minutes after boot and re-activated hourly and performs a single invocation of cfsnap command. The regular run is provided by cfsnap.timer systemd unit.

Configuration

The contents of the following files influences the behaviour of the tool and scheduling of its runs:

/etc/free-pmx/cfsnap.conf

Configuration file sourced for option variables. Comes with the install, but is optional.

/etc/systemd/system/cfsnap.timer.d/interval.conf

A systemd timer drop-in for timing interval settings.

cfsnap.conf

All option names are uppercase, values lowercase. There must NO WHITESPACE between option name, = sign and the assigned value.

FREE_PMX_CFSNAP_RETAIN_DAYS=NUM

Number of days to retain snapshots. If unset, defaults to: 3

Operation

At regular intervals, cfsnap takes snapshots of pmxcfs state from where they could be restored and further backed-up.

pmxcfs provides unified access to cluster-wide configurations and is replicated in real-time across all (quorate) nodes or operating in a local mode on a solitary node. Actual backend is provided by SQLite database that is constantly writing. Both the mounted directory contents and the database file are unsuitable for regular backup tools.

Files

Snapshots are SQLite dumps gzipped into an archive.

The snapshots are stored in the following location:

/var/lib/free-pmx/csnaps/

Important
 Should you mount this directory off shared storage, NEVER let unrelated nodes SHARE one directory.
Filename format is:

cfsnap~<status>~<sequence>~<node>~<host>.pmxcfs.sql.gz

<status>

One of (n) no corosync active or returning error; (q) quorate; or (i) inquorate.

<sequence>

Timestamp in the form of YYYYMMDDHHMMSS - all times are UTC.

<node>

Node number - if it could been obtained from corosync.

<host>

Hostname as reported by the system itself.

Actual examples of snapshot file for a single and clustered node, respectively:

  • cfsnap~n~20250419181257~~pve2.pmxcfs.sql.gz

  • cfsnap~q~20250419181311~02~pve2.pmxcfs.sql.gz

Exit status

0

Success.

1

Failure.

Resources

Copying

Copyright © 2025 free-pmx.
Free use of this software is granted under the terms of the AGPL v3 License.