Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
ZFS-SNAPSHOT-MGMT(8)	     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  configura-
     tion 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  cre-
	   ated  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 re-
	   moving snapshots at each filesystem.  The value for this key contains
	   keys  for each filesystem (as seen by ZFS, e.g. tank/home) with snap-
	   shot 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 speci-
     fies 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  parame-
	   ter.   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 filesys-
	 tems 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.

FreeBSD ports 15.quarterly	  June 6, 2008		    ZFS-SNAPSHOT-MGMT(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=zfs-snapshot-mgmt&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help