ZFSNAP(8)

📦 version 2.0.0, in nixos 26.05, nixpkgs unstable

✨ ZFSNAP(8) — the zfsnap girlie's guide 💅

okay so bestie, welcome to zfsnap(8), the System Manager's Manual page that's about to become your whole personality. this is the manual for zfsnap, and I'm gonna walk you through every single bit of it, no cap. 🫶

🌸 NAME 🌸

zfsnap — create and delete rolling ZFS snapshots. that's it, that's the vibe. ✨

🎀 SYNOPSIS 🎀

zfsnap [-h] [-V] | <command> [options] zpool/filesystem ...

literally that's the whole shape of it. two little top-level flags, or a <command> with its own options and then your pools/filesystems. easy. 💖

🦋 DESCRIPTION 🦋

so here's the tea: zfsnap creates and deletes rolling ZFS snapshots — usually with cron. its main advantages are its portability and the fact that all the info needed for snapshot management is kept in the snapshot name itself. like, the name IS the database. iconic behavior honestly. 👑

zfsnap snapshots are in the format of pool/fs@[prefix]Timestamp--TimeToLive (e.g. zpool/var@monthly-2010-08-03_02.06.00--1y).

breaking that down for you, bestie:

  • the prefix is optional and is quite useful for filtering;
  • Timestamp is the date and time when the snapshot was created;
  • and TimeToLive (TTL) is the amount of time the snapshot will be kept until it's ready for deletion.

⭐ Top-level Options ⭐

the majority of functionality is implemented at the <command> layer. however, a few options can be passed to zfsnap directly. these are the tiny ones that live at the top:

  • -h — print a summary of zfsnap's command-line options and then exit.
  • -V — print the version number and exit.
💀 important vibe check: zfsnap operates only on snapshots and will never destroy or create a pool or filesystem. it's not gonna touch your actual data structures, it just does snapshots. periodt.

🌈 Commands 🌈

most zfsnap actions are performed by using a <command>. all options and arguments passed to a <command> are operated on as they are read (i.e. sequentially). this provides the flexibility needed for complex scenarios, but also has the capacity to bite you if you're not paying attention. 🫣 remember, -n (dry-run) is provided for a reason. use it. love it. don't skip it.

only one <command> can be passed per invocation of zfsnap.

💅 destroy

by default, zfsnap destroy will only delete snapshots whose TTLs have expired. however, options are provided to override that behavior with more aggressive approaches. (aggressive. we love a confident queen. 🔥)

only snapshots created by zfsnap (or, more specifically, snapshots which match the very specific name pattern it employs) will be considered for deletion. so it's not gonna go deleting random snapshots you made by hand, bestie, it only recognizes its own children. 🙈

  • -D — delete all zfsnap snapshots — regardless of their TTL expiration — on all ZFS file systems that follow this option.
  • -F age — force delete all snapshots exceeding age (defined in TTL format) — regardless of their TTL expiration — on all ZFS file systems that follow this option. see “TTL SYNTAX” for more information.
  • -h — print a summary of destroy's command-line options and then exit.
  • -n — dry-run. perform a trial run with no actions actually performed.
  • -p prefix — enable filtering to only consider snapshots with prefix; it can be specified multiple times to build a list.
  • -P — disable filtering for prefixes.
  • -r — operate recursively for snapshots on all ZFS file systems that follow this option.
  • -R — do not operate recursively for snapshots on all ZFS file systems that follow this option.
  • -s — skip pools that are resilvering.
  • -S — skip pools that are scrubbing.
  • -v — verbose output.

🧚 recurseback

zfsnap recurseback is different from zfs rollback in that it will rollback for not only the specified dataset, but also for all that dataset's children. it's giving "rollback but make it family-sized". 👑

  • -d depth — limit the recursion to depth. a depth of 1 will rollback only the dataset and its direct children.
  • -f — typically used with the [-R] option to force an unmount of any clone file systems that are to be destroyed.
  • -h — print a summary of recurseback's command-line options and then exit.
  • -n — dry-run. perform a trial run with no actions actually performed.
  • -r — destroy any snapshots and bookmarks more recent than the one specified.
  • -R — destroy any snapshots and bookmarks more recent than the one specified, as well as any clones of those snapshots.
  • -v — verbose output.

🍓 snapshot

the purpose of zfsnap snapshot is simple: to create snapshots. that's it. that's the whole job. and she does it beautifully. ✨

  • -a TTL — how long the snapshots should be kept. if not declared, the default TTL is one month. see “TTL SYNTAX” for more information.
  • -h — print a summary of snapshot's command-line options and then exit.
  • -n — dry-run. perform a trial run with no actions actually performed.
  • -p prefix — prefix to apply when naming snapshots for all ZFS file systems that follow this option.
  • -P — don't apply any prefix when naming snapshots for all ZFS file systems that follow this option.
  • -r — create recursive snapshots of all ZFS file systems that follow this option.
  • -R — create non-recursive snapshots for each ZFS file system that follows this option.
  • -s — skip pools that are resilvering.
  • -S — skip pools that are scrubbing.
  • -v — verbose output.
  • -z — round snapshot creation time down to 00 seconds. she's punctual. ⭐

💜 TTL SYNTAX 💜

the Time-To-Live (TTL) contains numbers and modifiers. valid modifiers are:

  • y — years (calendar)
  • m — months (calendar)
  • w — weeks
  • d — days
  • h — hours
  • M — minutes
  • s — seconds
  • forever — a special-case modifier that will never expire and cannot be used with other TTL modifiers. both [-F] and [-D] will delete snapshots with a TTL of forever.

you do not need to use all of the modifiers, but they must be used in the above order (i.e. sequentially). so no 5d1y shenanigans, bestie, that's not how this works. 🙈

TTL numbers must be greater than zero and cannot have leading zeros (e.g. both 0y and 09d are invalid).

the default TTL is 1m (one month).

🧮 TTL Math 🧮

when a TTL is added to a date, each field is added independently, then any month overflows are carried into years, and then all overflows are carried normally from right to left.

for example, with a date of 2009-02-27 and a TTL of 1m3d, the expiration date is 2009-03-30 rather than 2009-04-02. the math is mathing. 💅

as a corner case, adding a TTL of 1m (one month) to the date 2009-10-31 will result in an expiration date of 2009-12-01 rather than 2009-11-30. because there are only 30 days in November, precisely one month after October 31st is ambiguous. the TTL math chooses the more conservative (later) result.

😭 yes this is the "what even is a month" problem and yes it's handled. moving on.

🌟 TTL Examples 🌟

  • 1y6m5d2h — one year, six months, five days, and two hours
  • 18m — eighteen months
  • 90M — ninety minutes
  • 86400s — eighty-six thousand and four hundred seconds (1 day)

🔥 EXIT STATUS 🔥

zfsnap exits 0 on success and 1 if an error occurs. clean, simple, no drama. 🫶

🌈 EXAMPLES 🌈

zfsnap was designed to work with cron. thus, some of these examples will include cron markup.

every hour, create recursive snapshots of an entire pool and keep for 5 days.

# Minute  Hour  Day  Month  Day  Who   Command
5         *     *    *      *    root  /sbin/zfsnap snapshot -a 5d -r zpool

create snapshots of different datasets in different zpools and keep for 2 weeks.

zfsnap snapshot -a 2w zpool2/git zpool2/jails -r zpool2/jails/main zpool1/var

note that [-a], [-r], and [-R] can be used many times in a single line. slay. 💅

now, for a more complex example. here, zfsnap will snapshot:

  • zpool/var recursively and hold it for 1 year
  • zpool/home recursively and hold it for 6 minutes
  • zpool/usr recursively and hold it for 3 months
  • zpool/root non-recursively and hold it for 3 months.
zfsnap snapshot -a 1y -r zpool/var -a 6M zpool/home -a 3m zpool/usr -R zpool/root

deleting ZFS snapshots is much slower than creating them, and it's usually not a problem if snapshots live a few hours longer. thus, it is usually best to delete old snapshots once a day.

# Minute  Hour  Day  Month  Day  Who   Command
0         1     *    *      *    root  /sbin/zfsnap destroy -r zpool

🦋 SEE ALSO 🦋

cron(8), zfs(8), zpool(8)

the zfsnap website is available at http://www.zfsnap.org

please report any bugs to https://github.com/zfsnap/zfsnap/issues

general questions and discussion can be directed to our mailing list at zfsnap@librelist.com (gmane.comp.sysutils.zfsnap on gmane).

👑 AUTHORS 👑

zfsnap was created by Aldis Berjoza, graudeejs@yandex.com, and is co-maintained with Alex Waite Alexqw85@gmail.com. see the AUTHORS file for more information.

zfsnap is released under the "BSD-3-Clause License." see the LICENSE file for more information.

and that's the whole page, bestie!! 🫶 this edition came from Debian, dated February 11, 2014, and it lives under ZFSNAP(8) — go forth and snapshot responsibly, and remember: dry-run first, always. 💖✨

📦 where this page comes from