gromox-snapshot(8)

okay so bestie, welcome to gromox-snapshot(8) from the Gromox admin reference 💖 this is the helper that makes snapshots of mailboxes, and it's giving quietly essential system admin main character energy ✨

🌸 Name 🌸

gromox-snapshot — Helper to create snapshots of mailboxes. That's the name, that's the job, slay.

✨ Synopsis ✨

/usr/libexec/gromox/gromox-snapshot

No args, no flags, just vibes and that exact path 🫶

🦋 Description 🦋

gromox-snapshot calls btrfs(8) or cp(1)/--reflink to create snapshots of the current state of mailboxes as needed. It is meant to be periodically invoked by a systemd timer (or, failing that, a classic cron job), and the default interval of gromox-snapshot.timer is hourly. Periodt.

The program generates snapshots "for this day" / "for this week" / etc., rather than snapshots which are at least one day / one week / etc. apart. When the snapshotter is run periodically, this evens out and is not a concern at all. So don't stress, bestie 💅

💅 Options 💅

The program has no command-line options. Literally zero. Not a single flag to collect. Iconic minimalism, ngl.

🎀 Configuration file 🎀

/etc/gromox/snapshot.cfg will be read on startup. It is a trivial key=value file, with one variable per line. Keep it cute and simple 🎀

• retention_days=n — make daily snapshots and keep them for n days. Use 0 to deactivate daily snapshotting. Default: 7.
• retention_hours=n — make hourly snapshots and keep them for n hours. Use 0 to deactivate hourly snapshotting. Default: 0.
• retention_months=n — make monthly snapshots and keep them for n months (more precisely, n*31 days). Use 0 to deactivate monthly snapshotting. Default: 0.
• retention_weeks=n — make weekly snapshots and keep them for n weeks. Use 0 to deactivate weekly snapshotting. Default: 4.
• subvolume_root — when btrfs is used, this directive specifies the root directory of the nearest btrfs subvolume. (As of Linux 6.2.1, it is not possible to snapshot arbitrary directories; it has to be the root of a subvolume. Confer with btrfs sub list to see subvolumes.) Otherwise, this must point to the Gromox data directory. Default: /var/lib/gromox.
• snapshot_archive — the directory where snapshots (these are subdirectories) will be placed. This directory needs to be on the same device as the snapshot source (subvolume_root, see above). Default: /var/lib/gromox-snapshots.

Each time a "category" (days, weeks, etc.) is independently evaluated and snapshots are always made from subvolume_root, never from another snapshot. A weekly snapshot generated on the first day of the week is not strictly equal to the daily snapshot generated for the same day, as there is technically a very small time window between individual btrfs commands. Tiny window, real facts, no cap 🦋

😭 Errors 😭

• Invalid cross-device link — snapshot_archive was not on the same device as subvolume_root. The devices gotta match, bestie 😭
• Operation not supported — the filesystem employed on snapshot_archive does not support reflinks. If it doesn't support reflinks, it's not gonna reflink, periodt.

💀 Known issues 💀

When a reflink-based snapshot is deleted (which happens via /bin/rm), rm may modify the directory's timestamp. If that rm call is interrupted without completing, the next run of gromox-snapshot will erroneously consider the directory as "too new" and not resume the deletion until it has sufficiently aged again. So yeah, interrupted rm is giving chaos gremlin energy 💀

🔥 See also 🔥

gromox(7) — go read it, bestie 🫶

---

💖 cute sign-off: source/version is Gromox, the manual is gromox-snapshot(8), and the footer doesn't list a date, so no date to report — periodt 🎀