Welcome to zsm’s documentation!

ZSM is a console program that manages ZFS snapshots.

  • Manage multiple sets of rolling snapshots.
  • Configure a custom schedule via the config file.
  • Run in background by adding it to crontab.

Technically, most of the functionality is in zsm-lib, and zsm is just a thin console interface.

Project status

Alpha but works very well and has great test coverage.

Table of Contents

Installation

PyPI

$ pip install zsm

Note

Always avoid running pip install as root. Instead, use a virtual environment, or install it isolated to the current user.

Quickstart

Step 1: Create config file

The default location is /usr/local/etc/zsm.yaml on FreeBSD and /etc/zsm.yaml on Linux.

snapshots:
  - dataset: "tank/data"
    label: "daily"
    frequency: "1d"
    retention: 30

  - dataset: "tank/data"
    label: "hourly"
    frequency: "1h"
    retention: 24

Step 2: Verify configuration

Not required, but a good sanity check.

Validate the config file

$ sudo zsm validate-config

Perform a dry run

$ sudo zsm cron --dry-run --log-console

Step 3: Add to crontab

Add a line to crontab as the root user, passing the cron command to zsm.

*/1 * * * * zsm cron

The log file is by default located at /var/log/zsm.log, and the default log level is INFO.

If you need help creating a crontab line, check out crontab guru.

Configuration file

The config file is a YAML file where the top level object is a mapping.

Fields

  • snapshots (List of mappings) - Define what snapshots to take.
    • dataset (String) - Name of an existing dataset, including pool name.
      Example: tank/data.
    • label (String) - Descriptive short name, typically describing the frequency.
      Examples: daily, weekly, every-2-minutes.
    • frequency (String) - Define how often the snapshot should be taken.
      Can contain multiple values consisting of a number and a unit.
      Supported units are weeks, days, hours, minutes, seconds, including various abbreviations like w, d, h, min, sec.
      Examples: 2w, 3d 12h, 2Weeks3DAYS 5h,3mins,2secs.
    • retention (Integer) - Number of old snapshots to keep.
      Example: 12.

Command Line Interface

Commands

  • cron : The main command that performs all work.
  • validate-config: Validate the configuration file.
  • version : Prints the version of the program.

Commands are passed as the first argument to zsm.

For example:

$ zsm version

Options to cron command

All of these options are optional.

--config-file <filename>

Path to a config file.

Default: /usr/local/etc/zsm.yaml on FreeBSD and /etc/zsm.yaml on Linux.

--log-file <filename>

Path to a log file.

Default: /var/log/zsm.log.

--log-level <level>

Minimum log level that will be outputted.

Must be one of DEBUG, INFO, WARNING, ERROR, CRITICAL.

Default: INFO.

--log-console

Print log output to stdout.

Default: Off.

--dry-run

Disable all operations that make modifications.

Default: Off.

Options to validate-config command

All of these options are optional.

--config-file <filename>

Path to a config file.

Default: /usr/local/etc/zsm.yaml on FreeBSD and /etc/zsm.yaml on Linux.

--log-level <level>

Minimum log level that will be outputted.

Must be one of DEBUG, INFO, WARNING, ERROR, CRITICAL.

Default: INFO.

FAQ

How does zsm store its meta data?

All meta data is stored in the name of the snapshot. Everything zsm does is calculated at run time, based on the current configuration file and existing snapshots in ZFS.

  • All meta data is immediately visible to the user in the snapshot name.
  • There is no hidden meta data stored in properties or attributes.
  • There is no database or other third party storage.

Will zsm interfere with other snapshots?

Nope. Zsm will only manage snapshots that starts with zsm. As long as you avoid creating snapshots that starts with zsm using other tools than zsm itself, it will be fine.

What happens when removing a snapshot config?

Zsm will only manage snapshots for the list of snapshot configs that are in the configuration file at the moment when it starts. Any existing snaphots created from an older configuration file will simply remain in ZFS, and can safely be destroyed manually.

If you want to have zsm clean up existing snapshots before removing a snapshot config, set retention to 0 and let zsm run once.

Changelog

Changelog for zsm

0.2.0

Update zsm-lib to version 0.2.0.

Start including tests in source packages.

0.1.0

Initial release.

Add commands:

  • cron
  • validate-config
  • version

Changelog for zsm-lib

0.2.0

Snapshot config field name renamed to label, to avoid confusion with the actual ZFS snapshot name. Also improved validation.

Snapshot config field delta renamed to frequency, because it makes more sense grammatically. Also changed implementation from simple dict to complex string. See Quickstart and Configuration file for more information.

Fix bug where it would incorrectly find and manage snapshots where the label was only a partial match. Add regression test to detect this bug.

Start including tests in source packages.

Improve test coverage.

0.1.0

Initial release.

Contributing

Development takes place at:

Issues and Merge Requests are welcome =)

Indices and tables