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

FreeBSD Manual Pages

  
 
  

home | help
ZFSNAP(8)		  BSD System Manager's Manual		     ZFSNAP(8)

NAME
     zfsnap -- create and delete rolling ZFS snapshots

SYNOPSIS
     zfsnap [-h] [-V] |	_command_ [options] zpool/filesystem ...

DESCRIPTION
     zfsnap creates and	deletes	rolling	ZFS snapshots -- usually with cron.
     zfsnap's main advantages are its portability and that all information
     needed for	snapshot management is kept in the snapshot name itself.

     zfsnap snapshots are in the format	of pool/fs@[prefix]Timestamp--TimeTo-
     Live (e.g.	zpool/var@monthly-2010-08-03_02.06.00--1y).

     The prefix	is optional and	is quite useful	for filtering; Timestamp is
     the date and time when the	snapshot was created; and TimeToLive (TTL) is
     the amount	of time	the snapshot will be kept until	it's ready for dele-
     tion.

   Top-level Options
     The majority of functionality is implemented at the _command_ layer. How-
     ever, a few options can be	passed to zfsnap directly.

     -h	     Print a summary of	zfsnap's command-line options and then exit.

     -V	     Print the version number and exit.

     zfsnap operates only on snapshots and will	never destroy or create	a pool
     or	filesystem.

Commands
     Most zfsnap actions are performed by using	a _command_.  All options and
     arguments passed to a _command_ are operated on as	they are read (i.e.
     sequentially).  This provides the flexibility needed for complex scenar-
     ios, but also has the capacity to bite you	if you're not paying atten-
     tion. Remember, -n	(dry-run) is provided for a reason.

     Only one _command_	can be passed per invocation of	zfsnap.

   destroy
     By	default, zfsnap	destroy	will only delete snapshots whose TTLs have ex-
     pired. However, options are provided to override that behavior with more
     aggressive	approaches.

     Only snapshots created by zfsnap (or, more	specifically, snapshots	which
     match the very specific name pattern it employs) will be considered for
     deletion.

     -D	     Delete all	zfsnap snapshots -- regardless of their	TTL expiration
	     --	on all ZFS file	systems	that follow this option.

     -F	age  Force delete all snapshots	exceeding age (defined in TTL format)
	     --	regardless of their TTL	expiration -- on all ZFS file systems
	     that follow this option. See TTL SYNTAX for more information.

     -h	     Print a summary of	destroy's command-line options and then	exit.

     -n	     Dry-run. Perform a	trial run with no actions actually performed.

     -p	prefix
	     Enable filtering to only consider snapshots with prefix; it can
	     be	specified multiple times to build a list.

     -P	     Disable filtering for prefixes.

     -r	     Operate recursively for snapshots on all ZFS file systems that
	     follow this option.

     -R	     Do	not operate recursively	for snapshots on all ZFS file systems
	     that follow this option.

     -s	     Skip pools	that are resilvering.

     -S	     Skip pools	that are scrubbing.

     -v	     Verbose output.

   recurseback
     zfsnap recurseback	is different from `zfs rollback` in that it will roll-
     back for not only the specified dataset, but also for all that dataset's
     children.

     -d	depth
	     Limit the recursion to depth.  A depth of 1 will rollback only
	     the dataset and its direct	children.

     -f	     Typically used with the [-R] option to force an unmount of	any
	     clone file	systems	that are to be destroyed.

     -h	     Print a summary of	recurseback's command-line options and then
	     exit.

     -n	     Dry-run. Perform a	trial run with no actions actually performed.

     -r	     Destroy any snapshots and bookmarks more recent than the one
	     specified.

     -R	     Destroy any snapshots and bookmarks more recent than the one
	     specified,	as well	as any clones of those snapshots.

     -v	     Verbose output.

   snapshot
     The purpose of zfsnap snapshot is simple: to create snapshots.

     -a	TTL  How long the snapshots should be kept. If not declared, the de-
	     fault TTL is one month. See TTL SYNTAX for	more information.

     -h	     Print a summary of	snapshot's command-line	options	and then exit.

     -n	     Dry-run. Perform a	trial run with no actions actually performed.

     -p	prefix
	     Prefix to apply when naming snapshots for all ZFS file systems
	     that follow this option.

     -P	     Don't apply any prefix when naming	snapshots for all ZFS file
	     systems that follow this option.

     -r	     Create recursive snapshots	of all ZFS file	systems	that follow
	     this option.

     -R	     Create non-recursive snapshots for	each ZFS file system that fol-
	     lows this option.

     -s	     Skip pools	that are resilvering.

     -S	     Skip pools	that are scrubbing.

     -v	     Verbose output.

     -z	     Round snapshot creation time down to 00 seconds.

TTL SYNTAX
     The Time-To-Live (TTL) contains numbers and modifiers. Valid modifiers
     are:

	 y	   years (calendar)

	 m	   months (calendar)

	 w	   weeks

	 d	   days

	 h	   hours

	 M	   minutes

	 s	   seconds

	 forever   a special-case modifier that	will never expire and cannot
		   be used with	other TTL modifiers. Both [-F] and [-D]	will
		   delete snapshots with a TTL of forever.

     You do not	need to	use all	of the modifiers, but they must	be used	in the
     above order (i.e. sequentially).

     TTL numbers must be greater than zero and cannot have leading zeros (e.g.
     Both 0y and 09d are invalid).

     The default TTL is	1m (one	month).

   TTL Math
     When a TTL	is added to a date, each field is added	independently, then
     any month overflows are carried into years, and then all overflows	are
     carried normally from right to left.

     For example, with a date of 2009-02-27 and	a TTL of 1m3d, the expiration
     date is 2009-03-30	rather than 2009-04-02.

     As	a corner case, adding a	TTL of 1m (one month) to the date 2009-10-31
     will result in an expiration date of 2009-12-01 rather than 2009-11-30.
     Because there are only 30 days in November, precisely one month after Oc-
     tober 31st	is ambiguous. The TTL math chooses the more conservative
     (later) result.

   TTL Examples
     1y6m5d2h  One year, six months, five days,	and two	hours

     18m       Eighteen	months

     90M       Ninety minutes

     86400s    Eighty-six thousand and four hundred seconds (1 day)

EXIT STATUS
     zfsnap exits 0 on success and 1 if	an error occurs.

EXAMPLES
     zfsnap was	designed to work with cron. Thus, some of these	examples will
     include cron markup.

     Every hour, create	recursive snapshots of an entire pool and keep for 5
     days.

	   # Minute  Hour  Day	Month  Day  Who	  Command
	   5	     *	   *	*      *    root  /sbin/zfsnap snapshot	-a 5d -r zpool

     Create snapshots of different datasets in different zpools	and keep for 2
     weeks.

	   zfsnap snapshot -a 2w zpool2/git zpool2/jails -r zpool2/jails/main
	   zpool1/var

     Note that [-a], [-r], and [-R] can	be used	many times in a	single line.

     Now, for a	more complex example. Here, zfsnap will	snapshot
       -   zpool/var recursively and hold it for 1 year
       -   zpool/home recursively and hold it for 6 minutes
       -   zpool/usr recursively and hold it for 3 months
       -   zpool/root non-recursively and hold it for 3	months.

	   zfsnap snapshot -a 1y -r zpool/var -a 6M zpool/home -a 3m zpool/usr
	   -R zpool/root

     Deleting ZFS snapshots is much slower than	creating them, and it's	usu-
     ally not a	problem	if snapshots live a few	hours longer. Thus, it is usu-
     ally best to delete old snapshots once a day.

	   # Minute  Hour  Day	Month  Day  Who	  Command
	   0	     1	   *	*      *    root  /sbin/zfsnap destroy -r zpool

SEE ALSO
     cron(8), zfs(8), zpool(8)

     The zfsnap	website	is available at	http://www.zfsnap.org

     Please report any bugs to https://github.com/zfsnap/zfsnap/issues

     General questions and discussion can be directed to our mailing list at
     zfsnap@librelist.com (gmane.comp.sysutils.zfsnap on gmane).

AUTHORS
     zfsnap was	created	by Aldis Berjoza, graudeejs@yandex.com,	and is co-
     maintained	with Alex Waite	Alexqw85@gmail.com.  See the AUTHORS file for
     more information.

COPYRIGHT
     zfsnap is released	under the "BSD-3-Clause	License." See the LICENSE file
     for more information.

BSD			       February	11, 2014			   BSD

NAME | SYNOPSIS | DESCRIPTION | Commands | TTL SYNTAX | EXIT STATUS | EXAMPLES | SEE ALSO | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zfsnap&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help