Skip to content
Stuart Mumford edited this page Jul 2, 2024 · 12 revisions
  1. Configuring Sanoid
  2. Templates
  3. Examples
  4. Running Sanoid

Configuring Sanoid

When Sanoid is installed, it will place an example config file at /etc/sanoid/sanoid.defaults.conf. This file is required, but should not be modified. Instead, you should use the file /etc/sanoid/sanoid.conf to configure your Sanoid installation. Users of Ubuntu 20.04 can find the example config file at /usr/share/doc/sanoid/examples/sanoid.conf and can copy it to /etc/sanoid/sanoid.conf to start their own configuration.

The config file uses a .inf layout. The dataset you want to configure should be put in square brackets, and any configuration should be placed below that.

[dataset1]
recursive = yes

[dataset2]
use_template = backup

Options

*Please note that this is not an exhaustive list. Look in /etc/sanoid/sanoid.defaults.conf for more.

Flag Description
process_children_only Indicates that only datasets under this one should be processed
use_template Which template should be applied to this dataset (not allowed in templates)
recursive Whether options should be applied to datasets under this one, including this one (not allowed in templates)
frequent_period How often snapshots should be taken under an hour. e.g. frequent_period = 15 means four snapshots each hour 15 minutes apart, frequent_period = 45 means two snapshots each hour with different time gaps between them: 45 minutes and 15 minutes
autosnap Sets whether snapshots should be taken automatically
frequently How many sub-hourly backups should be kept
hourly How many hourly backups should be kept
daily How many daily backups should be kept
monthly How many monthly backups should be kept
yearly How many yearly backups should be kept
autoprune Should old snapshots be pruned
prune_defer Skip pruning based on used % of pool. A value of 0 means always prune

Flags

Flag Description
--configdir= Specify a different directory to look for sanoid.conf
--cron Creates snapshots and purges expired snapshots
--verbose Prints out additional information during a sanoid run
--readonly Simulates creation/deletion of snapshots. No changes are made
--quiet Suppresses non-error output
--force-update Clears out sanoid's zfs snapshot cache
--monitor-health Reports on zpool "health", in a Nagios compatible format
--monitor-capacity Reports on zpool capacity, in a Nagios compatible format
--monitor-snapshots Reports on snapshot "health", in a Nagios compatible format
--take-snapshots Creates snapshots as specified in sanoid.conf
--prune-snapshots Purges expired snapshots as specified in sanoid.conf
--force-prune Purges expired snapshots even if a send/recv is in progress
--help Prints this helptext
--version Prints the version number
--debug Prints out a lot of additional information during a sanoid run

Templates

Templates can be used to define common behavior. Templates are defined just like datasets, but the name must start with "template_". Let's look at the example below.

[rpool/vms/ubuntu]
use_template = production

[rpool/vms/fedora]
use_template = production

[rpool/vms/snapshots]
use_template = archive
process_children_only = yes

[template_production]
    frequently = 0
    hourly = 36
    daily = 30
    monthly = 1
    yearly = 0
    autosnap = yes
    autoprune = yes

[template_archive]
    frequently = 0
    hourly = 0
    daily = 30
    monthly = 12
    yearly = 2
    autosnap = yes

In this example, I have a vm dataset and vm snapshots being automatically processed by Sanoid. I've defined two templates, production and archive, with specific behaviors. My production template is geared for live machines, and will take more frequent snapshots, but not hang on to them as long. My archive template takes fewer snapshots, but will hang onto them longer. The archive template will also not automatically prune snapshots.

Also note the process_children_only flag under my snapshots dataset. even though we're using templates, we can still define behavior specific to a dataset.

Examples

An example config file looks like this

[data/home]
	use_template = production
[data/images]
	use_template = production
	recursive = yes
	process_children_only = yes
[data/images/win7]
	hourly = 4

#############################
# templates below this line #
#############################

[template_production]
        frequently = 0
        hourly = 36
        daily = 30
        monthly = 3
        yearly = 0
        autosnap = yes
        autoprune = yes

Running Sanoid

Ubuntu Linux 20.04 and newer

During installation from the Ubuntu repositories, the systemd timer unit sanoid.timer is created which is set to run sanoid every 15 minutes. Therefore there is no need to create an entry in crontab. Having a crontab entry in addition to the sanoid.timer will result in errors similar to cannot create snapshot '<pool>/<dataset>@<snapshot>': dataset already exists.

Systemd configuration

By default, the sanoid.timer timer unit runs the sanoid-prune service followed by the sanoid service. To edit any of the command-line options, you can edit these service files.

Archlinux

Sanoid is packaged in the unofficial user repository, the AUR. The default installation contains the same unit files that are distributed with the Ubuntu package.

Other Distributions