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 areweeks
,days
,hours
,minutes
,seconds
, including various abbreviations likew
,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¶
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.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line