ZETABACK(1)

NAME
zetaback - perform backup, restore and retention policies for ZFS backups.

SYNOPSIS
  zetaback -v

  zetaback [-l | -s | -sx | -sv] [--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.

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

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.

  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. Defaults to (14 * 86400), or two weeks.

compressionprogram
    Compress files using gzip or bzip2. Defaults to gzip.

compressionlevel
    Compress files using gzip or bzip2 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.

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)