.\"
.\" FreeBSD UFS/ZFS Snapshot Management Environment
.\" Copyright (c) 2004-2007 The FreeBSD Project. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" periodic-snapshot: snapshot periodic scheduler (implementation)
.\" $FreeBSD$
.\"
.Dd September 03, 2004
.Os
.Dt PERIODIC-SNAPSHOT 8
.Sh NAME
.Nm periodic-snapshot
.Nd run periodic UFS/ZFS backup snapshot maintenance task
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
The
.Nm
utility is intended to be called by
.Xr cron 8
to create and expire UFS/ZFS backup snapshots
through the
.Xr snapshot 8
command according to the
.Va snapshot_enable
and
.Va snapshot_schedule
settings from
.Xr periodic.conf 5 .
.Pp
The system
.Pa /etc/crontab
will typically have entries for
.Nm
similar to the following example:
.Bd -literal -offset indent
# do hourly/daily/weekly maintenance of FreeBSD UFS/ZFS snapshots
0 * * * * root periodic-snapshot hourly
0 0 * * * root periodic-snapshot daily
0 0 * * 0 root periodic-snapshot weekly
.Ed
.Pp
The
.Pa /etc/defaults/periodic.conf
system registry will typically contain the following defaults which keep
.Nm
disabled by default:
.Bd -literal -offset indent
snapshot_enable="NO"
snapshot_schedule=""
.Ed
.Pp
The
.Va snapshot_schedule
variable values have to conform to the following grammar:
.Bd -literal -offset indent
::= *
::= ("," )* ":" ::= /^\/.*$/
::= ":" ":" ::= ::= ::= ("@" ("," )*)?
::= /^[0-9]+$/
::= /^(0?[0-9]|1[0-9]|2[0-3])$/
.Ed
.Pp
The number of all added "generation" numbers of a filesystem cannot be larger
than 20 because this is the maximum number of snapshots which can be
created on a UFS/ZFS filesystem. A "generation" number of "0" disables
the creation of backup snapshots.
.Pp
The used schedule heavily depends on how much generations of snapshots
should be kept, which in turn depends on how much disk space is available.
.Sh FILES
.Bl -tag -width ".Pa /etc/defaults/periodic.conf"
.It Pa /etc/crontab
the
.Nm
utility is typically called via entries in the system default
.Xr cron 8
table.
.It Pa /etc/defaults/periodic.conf
system registry containing variables that control the behaviour of
.Nm .
.It Pa /etc/periodic.conf
this file contains local overrides for the default
.Nm
configuration.
.El
.Sh EXAMPLES
In order to configure UFS/ZFS backup snapshot creation, add
lines to
.Pa /etc/periodic.conf
similar to:
.Bd -literal -offset indent
snapshot_enable="YES"
snapshot_schedule="/,/usr:2:1:0 /var:0:2:4 /home:2:6:8@8,12,16,20"
.Ed
.Pp
This schedules the following UFS/ZFS backup snapshots: 2 weekly
(weekly.[01]) and 1 daily (daily.0) generation of snapshots on
the / and /usr filesystems, two daily (daily.[01]) and 4 hourly
(hourly.[0123]) generations of snapshots on the /var filesystem,
and 2 weekly (weekly.[01]), 6 daily (daily.[0123456]) and 8 hourly
(hourly.[01234567]) generations of snapshots on the /home filesystem.
While the hourly snapshots on /var are created every hour, the hourly
snapshots on /home are created on 08:00, 12:00, 16:00 and 20:00 only.
.Pp
.Sh SEE ALSO
.Xr sh 1 ,
.Xr crontab 5 ,
.Xr periodic.conf 5 ,
.Xr cron 8 ,
.Xr snapshot 8 ,
.Xr http://people.freebsd.org/~rse/snapshot/ .
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx .
.Sh AUTHORS
.An Ralf S. Engelschall Aq rse@FreeBSD.org