DragonFly On-Line Manual Pages

ZFS-SNAPSHOT-MGMT(8)   DragonFly System Manager's Manual  ZFS-SNAPSHOT-MGMT(8)

NAME
     zfs-snapshot-mgmt - automate creation of new and removal of stale ZFS
     snapshots

SYNOPSIS
     zfs-snapshot-mgmt

DESCRIPTION
     The utility creates ZFS snapshots and removes snapshots it has created
     that are stale.  Rules for creating and removing are defined in the
     configuration file.

     zfs-snapshot-mgmt is designed to be run by the cron(8) utility.

CONFIGURATION
     zfs-snapshot-mgmt reads settings from the
     /usr/local/etc/zfs-snapshot-mgmt.conf file.

   General Structure
     The file is in the YAML format: it contains keys and values separated by
     a colon (:). Each value may span multiple lines and be a list or a map
     with key-value pairs. The indentation is always a multiple of two spaces.

     There are two top-level options:

     snapshot_prefix
           prefix for snapshots created and recognised by this tool.  All
           created snapshots will have names consisting of this prefix and
           current date and time.  Only snapshots beginning with this prefix
           will be considered for removal.

     filesystems
           the main part of configuration - specifies rules for creating and
           removing snapshots at each filesystem.  The value for this key
           contains keys for each filesystem (as seen by ZFS, e.g. tank/home)
           with snapshot creation and preservation settings.

     There is an example configuration in the EXAMPLES section.

   Creation Rules
     For each filesystem there is one snapshot creation_rule defined.  It
     specifies when snapshots for the particular filesystem should be created.
     It has two parameters.  All values are specified in minutes.

     at_multiple
           defines how often should a snapshot be created.  E.g. a value of 60
           means that a snapshot is to be created every hour.

     offset
           defines an offset from midnight that is to be applied to the
           parameter.  E.g. specifying a value of 30 means that the first
           snapshot will be taken 30 minutes after midnight.

   Preservation Rules
     These rules specify which of the created snapshots should be preserved.
     All that do not match the any of the rules and whose names begin with
     snapshot_prefix are destroyed.

     Each of the rules has three parameters:

     for_minutes
           specifies how long after snapshot creation is the rule applicable.

     at_multiple
           analogous to the same parameter for creation_rule - snapshots whose
           creation time (in minutes since midnight) is a multiple of this
           value are retained.

     offset
           analogous to the same parameter for creation_rule - applies to
           at_multiple.

EXAMPLES
   Crontab Configuration
     To invoke the program every five minutes you may add the following line
     to the /etc/crontab configuration file:

           */5 * * * * root /usr/local/bin/zfs-snapshot-mgmt

     Bear in mind that this effectively limits the resolution to 5 minutes.

   zfs-snapshot-mgmt.conf
     Here is an example configuration.

           snapshot_prefix: auto-
           filesystems:
             tank/usr/home:
               creation_rule:
                 at_multiple: 5
                 offset: 0
               preservation_rules:
                 - { for_minutes:    90, at_multiple:    0, offset:    0 }
                 - { for_minutes:   720, at_multiple:   30, offset:    0 }
                 - { for_minutes: 10080, at_multiple:  180, offset:  120 }
             tank/usr:
               recursive: true
               creation_rule:
                 at_multiple: 1440
                 offset: 1200
               preservation_rules:
                 - { for_minutes: 5760, at_multiple: 1440, offset: 1200 }

     which specifies the following settings:

     *   names of created snapshots start with auto- and only such snapshots
         are considered for removal.

     *   there are two filesystems: tank/usr/home and tank/usr.

     *   snapshots for tank/usr/home are created every five minutes, starting
         at midnight.

     *   all snapshots for tank/usr/home are kept for 90 minutes after
         creation.

     *   only snapshots created af full and half hour are retained for 12
         hours (720 minutes) after creation for tank/usr/home.

     *   snapshots created at multiple of three hours starting with 2 a.m. are
         retained for a week (10080 minutes) after creation for tank/usr/home.
         This means: 2 a.m., 5 a.m., 8 a.m. and so on.

     *   snapshots on tank/usr are created once a day at 20 p.m. and retained
         for 4 days.

     *   snapshots are taken recursively on tank/usr filesystem and all
         filesystems mounted under it.

FILES
     /usr/local/etc/zfs-snapshot-mgmt.conf The configuration file

SEE ALSO
     cron(8), zfs(1M)

AUTHORS
     Marcin Simonides <marcin@studio4plus.com>

BUGS
     There is no way to use alternative path for the configuration file.

DragonFly 6.5-DEVELOPMENT        June 6, 2008        DragonFly 6.5-DEVELOPMENT