DragonFly On-Line Manual Pages
ZETABACK(1) User Contributed Perl Documentation ZETABACK(1)
NAME
zetaback - perform backup, restore and retention policies for ZFS
backups.
SYNOPSIS
zetaback -v
zetaback [-l|-s|-sx|-sv|-svv] [--files] [-c conf] [-d] [-h host] [-z zfs]
zetaback -a [-c conf] [-d] [-h host] [-z zfs]
zetaback -b [-ff] [-fi] [-x] [-c conf] [-d] [-n] [-h host] [-z zfs]
zetaback -x [-b] [-c conf] [-d] [-n] [-h host] [-z zfs]
zetaback -r [-c conf] [-d] [-n] [-h host] [-z zfs] [-t timestamp]
[-rhost host] [-rzfs fs]
DESCRIPTION
The zetaback program orchestrates the backup (either full or
incremental) of remote ZFS filesystems to a local store. It handles
frequency requirements for both full and incemental backups as well as
retention policies. In addition to backups, the zetaback tool allows
for the restore of any backup to a specified host and zfs filesystem.
OPTIONS
The non-optional action command line arguments define the invocation
purpose of zetaback. All other arguments are optional and refine the
target of the action specified.
Generic Options
The following arguments have the same meaning over several actions:
-c <conf>
Use the specified file as the configuration file. The default
file, if none is specified is /usr/local/etc/zetaback.conf. The
prefix of this file may also be specified as an argument to the
configure script.
-d Enable debugging output.
-n Don't actually perform any remote commands or expunging. This is
useful with the -d argument to ascertain what would be done if the
command was actually executed.
-t <timestamp>
Used during the restore process to specify a backup image from the
desired point in time. If omitted, the command becomes
interactive. This timestamp is a UNIX timestamp and is shown in
the output of the -s and -sx actions.
-rhost <host>
Specify the remote host that is the target for a restore operation.
If omitted the command becomes interactive.
-rzfs <zfs>
Specify the remote ZFS filesystem that is the target for a restore
operation. If omitted the command becomes interactive.
-h <host>
Filters the operation to the host specified. If <host> is of the
form /pattern/, it matches 'pattern' as a perl regular expression
against available hosts. If omitted, no limit is enforced and all
hosts are used for the action.
-z <zfs>
Filters the operation to the zfs filesystem specified. If <zfs> is
of the form /pattern/, it matches 'pattern' as a perl regular
expression against available zfs filesystems. If omitted, no
filter is enforced and all zfs filesystems are used for the action.
Actions
-v Show the version.
-l Show a brief listing of available backups.
-s Like -l, -s will show a list of backups but provides additional
information about the backups including timestamp, type (full or
incremental) and the size on disk.
-sx Shows an extended summary. In addition to the output provided by
the -s action, the -sx action will show detail for each availble
backup. For full backups, the detail will include any more recent
full backups, if they exist. For incremental backups, the detail
will include any incremental backups that are more recent than the
last full backup.
-sv Display all backups in the current store that violate the
configured backup policy. This is where the most recent full backup
is older than full_interval seconds ago, or the most recent
incremental backup is older than backup_interval seconds ago.
If, at the time of the most recent backup, a filesystem no longer
exists on the server (because it was deleted), then backups of this
filesystem are not included in the list of violators. To include
these filesystems, use the -svv option instead.
-svv
The violators summary will exclude backups of filesystems that are
no longer on the server in the list of violators. Use this option
to include those filesystems.
--files
Display the on-disk file corresponding to each backup named in the
output. This is useful with the -sv flag to name violating files.
Often times, violators are filesystems that have been removed on
the host machines and zetaback can no longer back them up. Be very
careful if you choose to automate the removal of such backups as
filesystems that would be backed up by the next regular zetaback
run will often show up as violators.
-a Performs an archive. This option will look at all eligible backup
points (as restricted by -z and -h) and move those to the
configured archive directory. The recommended use is to first
issue -sx --files then carefully review available backup points and
prune those that are unneeded. Then invoke with -a to move only
the remaining "desired" backup points into the archives. Archived
backups do not appear in any listings or in the list of policy
violators generated by the -sv option. In effect, they are no
longer "visible" to zetaback.
-b Performs a backup. This option will investigate all eligible
hosts, query the available filesystems from the remote agent and
determine if any such filesystems require a new full or incremental
backup to be taken. This option may be combined with the -x option
(to clean up afterwards.)
-ff Forces a full backup to be taken on each filesystem encountered.
This is used in combination with -b. It is recommended to use this
option only when targeting specific filesystems (via the -h and -z
options.) Forcing a full backup across all machines will cause
staggered backups to coalesce and could cause performance issues.
-fi Forces an incremental backup to be taken on each filesystem
encountered. This is used in combination with -b. It is
recommended to use this option only when targeting specific
filesystems (via the -h and -z options.) Forcing an incremental
backup across all machines will cause staggered backups to coalesce
and could cause performance issues.
-x Perform an expunge. This option will determine which, if any, of
the local backups may be deleted given the retention policy
specified in the configuration.
-r Perform a restore. This option will operate on the specified
backup and restore it to the ZFS filesystem specified with -rzfs on
the host specified with the -rhost option. The -h, -z and -t
options may be used to filter the source backup list. If the
filtered list contains more than one source backup image, the
command will act interactively. If the -rhost and -rzfs command
are not specified, the command will act interactively.
When running interactively, you can choose multiple filesystems
from the list using ranges. For example 1-4,5,10-11. If you do
this, zetaback will enter multi-restore mode. In this mode it will
automatically select the most recent backup, and restore
filessytems in bulk.
In multi-restore mode, you have the option to specify a base
filesystem to restore to. This filesystem will be added as a prefix
to the original filesystem name, so if you picked a prefix of
data/restore, and one of the filesystems you are restoring is
called data/set/myfilesystem, then the filesystem will be restored
to data/restore/data/set/myfilesystem.
Note that, just like in regular restore mode, zetaback won't create
intermediate filesystems for you when restoring, and these should
either exist beforehand, or you should make sure you pick a set of
filesystems that will restore the entire tree for you, for example,
you should restore data as well as data/set before restoring
data/set/foo.
CONFIGURATION
The zetaback configuration file consists of a default stanza,
containing settings that can be overridden on a per-host basis. A
stanza begins either with the string 'default', or a fully-qualified
hostname, with settings enclosed in braces ({}). Single-line comments
begin with a hash ('#'), and whitespace is ignored, so feel free to
indent for better readability. Every host to be backed up must have a
host stanza in the configuration file.
Storage Classes
In addition to the default and host stanzas, the configuration file can
also contain 'class' stanzas. Classes allow you to override settings on
a per-filesystem basis rather than a per-host basis. A class stanza
begins with the name of the class, and has a setting 'type = class'.
For example:
myclass {
type = class
store = /path/to/alternate/store
}
To add a filesystem to a class, set a zfs user property on the relevant
filesystem. This must be done on the server that runs the zetaback
agent, and not the zetaback server itself.
zfs set com.omniti.labs.zetaback:class=myclass pool/fs
Note that user properties (and therefore classes) are are only
available on Solaris 10 8/07 and newer, and on Solaris Express build 48
and newer. Only the server running the agent needs to have user
property support, not the zetaback server itself.
The following settings can be included in a class stanza. All other
settings will be ignored, and their default (or per host) settings used
instead:
o store
o full_interval
o backup_interval
o retention
o dataset_backup
o violator_grace_period
Settings
The following settings are valid in both the default and host scopes:
store
The base directory under which to keep backups. An interpolated
variable '%h' can be used, which expands to the hostname. There is
no default for this setting.
archive
The base directory under which archives are stored. The format is
the same as the store setting. This is the destination to which
files are relocated when issuing an archive action (-a).
agent
The location of the zetaback_agent binary on the host. There is no
default for this setting.
time_format
All timestamps within zetaback are in UNIX timestamp format. This
setting provides a string for formatting all timestamps on output.
The sequences available are identical to those in strftime(3). If
not specified, the default is '%Y-%m-%d %H:%M:%S'.
backup_interval
The frequency (in seconds) at which to perform incremental backups.
An incremental backup will be performed if the current time is more
than backup_interval since the last incremental backup. If there
is no full backup for a particular filesystem, then a full backup
is performed. There is no default for this setting.
full_interval
The frequency (in seconds) at which to perform full backups. A
full backup will be performed if the current time is more than
full_interval since the last full backup.
retention
The retention time (in seconds) for backups. This can be a simple
number, in which case all backups older than this will be expunged.
The retention specification can also be more complex, and consist
of pairs of values separated by a comma. The first value is a time
period in seconds, and the second value is how many backups should
be retained within that period. For example:
retention = 3600,4;86400,11
This will keep up to 4 backups for the first hour, and an
additional 11 backups over 24 hours. The times do not stack. In
other words, the 11 backups would be kept during the period from 1
hour old to 24 hours old, or one every 2 hours.
Any backups older than the largest time given are deleted. In the
above example, all backups older than 24 hours are deleted.
If a second number is not specified, then all backups are kept
within that period.
Note: Full backups are never deleted if they are depended upon by
an incremental. In addition, the most recent backup is never
deleted, regardless of how old it is.
This value defaults to (14 * 86400), or two weeks.
compressionlevel
Compress files using gzip at the specified compression level. 0
means no compression. Accepted values are 1-9. Defaults to 1
(fastest/minimal compression.)
ssh_config
Full path to an alternate ssh client config. This is useful for
specifying a less secure but faster cipher for some hosts, or using
a different private key. There is no default for this setting.
dataset_backup
By default zetaback backs zfs filesystems up to files. This option
lets you specify that the backup go be stored as a zfs dataset on
the backup host.
offline
Setting this option to 1 for a host will mark it as being
'offline'. Hosts that are marked offline will not be backed up,
will not have any old backups expunged and will not be included in
the list of policy violators. However, the host will still be shown
when listing backups and archiving.
violator_grace_period
This setting controls the grace period used when deciding if a
backup has violated its backup window. It is used to prevent false
positives in the case where a filesystem is still being backed up.
For example, if it is 25 hours since the last daily backup, but the
daily backup is in progress, the grace period will mean that it is
not shown in the violators list.
Like all intervals, this period is in seconds. The default is 21600
seconds (6 hours).
Global Settings
The following settings are only valid in the default scope:
process_limit
This setting limits the number of concurrent zetaback processes
that can run at one time. Zetaback already has locks on hosts and
datasets to prevent conflicting backups, and this allows you to
have multiple zetaback instances running in the event a backup
takes some time to complete, while still keeping a limit on the
resources used. If this configuration entry is missing, then no
limiting will occur.
CONFIGURATION EXAMPLES
Uniform hosts
This config results in backups stored in /var/spool/zfs_backups, with a
subdirectory for each host. Incremental backups will be performed
approximately once per day, assuming zetaback is run hourly. Full
backups will be done once per week. Time format and retention are
default.
default {
store = /var/spool/zfs_backups/%h
agent = /usr/local/bin/zetaback_agent
backup_interval = 83000
full_interval = 604800
}
host1 {}
host2 {}
Non-uniform hosts
Here, host1's and host2's agents are found in different places, and
host2's backups should be stored in a different path.
default {
store = /var/spool/zfs_backups/%h
agent = /usr/local/bin/zetaback_agent
backup_interval = 83000
full_interval = 604800
}
host1 {
agent = /opt/local/bin/zetaback_agent
}
host2 {
store = /var/spool/alt_backups/%h
agent = /www/bin/zetaback_agent
}
FILES
zetaback.conf
The main zetaback configuration file. The location of the file can
be specified on the command line with the -c flag. The prefix of
this file may also be specified as an argument to the configure
script.
SEE ALSO
zetaback_agent(1)
perl v5.20.3 2015-10-07 ZETABACK(1)