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
       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 cre-
       ated.  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 pa-
	     rameter.  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  applica-
	     ble.

       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,	start-
	   ing at midnight.

          all	snapshots for tank/usr/home are	kept for 90 minutes after cre-
	   ation.

          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 re-
	   tained 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.

FreeBSD	Ports 14.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+14.3.quarterly>

home | help