zfsnap —
create
and delete rolling ZFS snapshots
| zfsnap |
[-h]
[-V] |
<command>
[options]
zpool/filesystem ... |
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--TimeToLive
(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 deletion.
The majority of functionality is implemented at the
<command> layer. However, 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.
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 scenarios, but also has the capacity to bite you if you're not paying
attention. Remember,
-n (dry‐run) is
provided for a reason.
Only one
<command> can be passed per
invocation of
zfsnap.
By default,
zfsnap
destroy will only delete snapshots whose TTLs
have expired. 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.
zfsnap recurseback is
different from `zfs rollback` in that it will rollback 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.
The purpose of
zfsnap
snapshot is simple: to create snapshots.
-
-
- -a
TTL
- How long the snapshots should be kept. If not declared, the
default 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 follows 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.
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).
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 October 31st is ambiguous. The TTL math chooses the more
conservative (later) result.
-
-
- 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)
zfsnap exits 0 on success and 1 if an error occurs.
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 usually not a
problem if snapshots live a few hours longer. Thus, it is usually best to
delete old snapshots once a day.
# Minute Hour Day Month Day Who Command
0 1 * * * root /sbin/zfsnap destroy -r zpool
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).
zfsnap was created by
Aldis Berjoza,
graudeejs@yandex.com,
and is co‐maintained with
Alex Waite
alex@waite.eu. See
the AUTHORS file for more information.
zfsnap is released under the
“BSD‐3‐Clause License.” See the LICENSE file for
more information.