eznap

Extremely Simple ZFS Snapshotter

Overview

eznap is a pure bash, zfs-auto-snapshot-inspired, extremely simple, zero-configuration snapshotter suite for ZFS.

This application adheres to the KISS principle and only does one thing - rolling ZFS snapshots.

Wherever a dataset is mentioned, volume is implied, too.

Requirements

Hard:

bash > 4.0.0

Soft:

cron-like mechanism (systemd.timer units included)

eznap script can be called manually without any limitation (hence the "soft" requirement) but the whole point of rolling snapshosts is that they are automated.

How does it work?

eznap uses labels to determine the frequency of snapshots. The labels are:

frequent (evey 15min by default)
hourly
daily
weekly
monthly

"Zero-configuration" means eznap itself doesn't have any configuration. Everything is driven by zfs properties, for example com.sun:auto-snapshot:hourly=8.

Setup ZFS datasets

Each dataset with com.sun:auto-snapshot property set to true will be snapshotted with default retention policies:

com.sun:auto-snapshot=true

Datasets without this are completely ignored by eznap, even for extraneous snapshot deletion.

All labels are enabled by default with default retention policies. To disable a specific label:

com.sun.auto-snapshot:<label>=false

To enable a label explicitly (like when the property is inherited):

com.sun.auto-snapshot:<label>=true

To enable a label with a custom retention policy:

com.sun.auto-snapshot:<label>=<integer>

<label> is a keyword described above (frequent, daily, etc.)

Setting the property to 0 is permitted and will delete all snapshots with that label.

Custom frequet snapshots frequency

The frequency of the frequent snapshots can be set per dataset setting the property cz.jfi.eznap:frequency to a positive integer. The integer represents minutes. You need to adjust your timer triggers to have the same or better resolution than your frequent frequency. See Usage below.

Setting the property to 0 is not supported but with the current code base it will result in triggering the frequent label on every run of the trigger, equalling the frequency to the trigger timer.

Retention policy

Only a limited number of snapshots is kept per each dataset and frequency group. The number of snapshots is determined by retention policy.

DEFAULT retention policies:

frequent = 96
hourly = 48
daily = 14
weekly = 8
monthly = 12

These vaules are (currently) hardcoded.

CUSTOM retention policy means the number of snapshots in the frequency group is set by the com.sun:auto-snapshot:<label> property.

For example, use com.sun:auto-snapshot:daily=7 to keep only 7 days worth of daily snapshots of the dataset.

Setting the property to false or anything else that eznap doesn't understand (like random strings, negative integers, etc.) will disable snapshots for that label (same as if com.sun:auto-snapshot was set to false or not set at all).

Usage

First make sure to set the properties on all your datasets that you wish to snapshot:

zfs set -o com.sun:auto-snapshot=true  tank
zfs set -o com.sun:auto-snapshot=false tank/nosnapshots

zfs set -o com.sun:auto-snapshot:hourly=8 tank/data
zfs set -o com.sun:auto-snapshot:hourly=false tank/data/ephemeral

zfs set -o cz.jfi.eznap:frequency=5 tank/data/important_database

...

Manual invocation:

$ eznap <label | "trigger">

<label> will process the label (daily, weekly, ...) and create (and delete) snapshot with that label. Warning: running a label directly will result in its immediate application, regardless of the real time schedule! This means that if you, for instance, run eznap weekly three times in a row, you will end up with three snapshots called weekly and you will lose all weekly snapshots below the retention threshold.

It is recommended to run labels directly only as part of testing or debugging, otherwise they should only be run by an apropriately timed cron job, timer, or other scheduler.

trigger will process all labels according to their schedules. This operation invokes eznap's internal scheduling logic which will trigger all labels according to their schedules. It is safe to run trigger many times over, the labels will not be triggered unless their schedule is due.

Simple cron, use eznap's builtin scheduling and triggering. This is the recommended approach when using cron:

*/5 * * * * eznap trigger

Custom cron, if you don't want to use eznap's internal scheduling, you can schedule all labels manually:

*/15 * * * *  eznap frequent
@hourly       eznap hourly
@daily        eznap daily
@weekly       eznap weekly
@monthly      eznap montly

Systemd timer:

systemctl enable --now eznap.timer

This timer triggers eznap every 15 minutes by default which is optimal for the default frequent frequency. If you change your frequent frequency (see above) to anything else than 15 minutes, make sure that the timer is triggered according to that frequency. You can use the eznap@.timer template for that:

systemctl enable --now eznap@5min.timer

The user executing eznap must have the rights to create and delete snapshots, such as by zfs-allow(8), or being root.

That's it!

jficz/eznap