rsnapshot - Man Page

rsnapshot [-vtxqVD] [-c cfgfile] [command] [args]

rsnapshot is a filesystem snapshot utility. It can take incremental snapshots of local and remote filesystems for any number of machines.

Local filesystem snapshots are handled with rsync(1). Secure remote connections are handled with rsync over ssh(1), while anonymous rsync connections simply use an rsync server. Both remote and local transfers depend on rsync.

rsnapshot saves much more disk space than you might imagine. The amount of space required is roughly the size of one full backup, plus a copy of each additional file that is changed. rsnapshot makes extensive use of hard links, so if the file doesn't change, the next snapshot is simply a hard link to the exact same file.

rsnapshot will typically be invoked as root by a cron job, or series of cron jobs. It is possible, however, to run as any arbitrary user with an alternate configuration file.

All important options are specified in a configuration file, which is located by default at /etc/rsnapshot.conf. An alternate file can be specified on the command line. There are also additional options which can be passed on the command line.

The command line options are as follows:

/etc/rsnapshot.conf is the default configuration file. All parameters in this file must be separated by tabs. /etc/rsnapshot.conf.default can be used as a reference.

It is recommended that you copy /etc/rsnapshot.conf.default to /etc/rsnapshot.conf, and then modify /etc/rsnapshot.conf to suit your needs.

Long lines may be split over several lines.  "Continuation" lines must begin with a space or a tab character.  Continuation lines will have all leading and trailing whitespace stripped off, and then be appended with an intervening tab character to the previous line when the configuration file is parsed.

Here is a list of allowed parameters:

cmd_postexec

Full path (plus any arguments) to postexec script (optional). This script will run immediately after each backup operation (but not any rotations). If the execution fails, rsnapshot will stop immediately.

linux_lvm_cmd_lvcreate

linux_lvm_cmd_lvremove

linux_lvm_cmd_mount

linux_lvm_cmd_umount

Paths to lvcreate, lvremove, mount and umount commands, for use with Linux LVMs.  You may include options to the commands also. The lvcreate, lvremove, mount and umount commands are required for managing snapshots of LVM volumes and are otherwise optional.

    1        Quiet            Show fatal errors only
    2        Default          Show warnings and errors
    3        Verbose          Show equivalent shell commands being executed
    4        Extra Verbose    Same as verbose, but with more detail
    5        Debug            All kinds of information

    # THIS IS A COMMENT, REMEMBER TABS MUST SEPARATE ALL ELEMENTS

    config_version  1.2

    snapshot_root   /.snapshots/

    cmd_rsync           /usr/bin/rsync
    cmd_ssh             /usr/bin/ssh
    #cmd_cp             /bin/cp
    cmd_rm              /bin/rm
    cmd_logger          /usr/bin/logger
    cmd_du              /usr/bin/du

    linux_lvm_cmd_lvcreate        /sbin/lvcreate
    linux_lvm_cmd_lvremove        /sbin/lvremove
    linux_lvm_cmd_mount           /bin/mount
    linux_lvm_cmd_umount          /bin/umount

    linux_lvm_snapshotsize    2G
    linux_lvm_snapshotname    rsnapshot
    linux_lvm_vgpath          /dev
    linux_lvm_mountpath       /mnt/lvm-snapshot

    retain              alpha  6
    retain              beta   7
    retain              gamma  7
    retain              delta 3

    backup              /etc/                     localhost/
    backup              /home/                    localhost/
    backup_script       /usr/local/bin/backup_mysql.sh  mysql_backup/

    backup              root@foo.com:/etc/        foo.com/
    backup              root@foo.com:/home/       foo.com/
    backup              root@mail.foo.com:/home/  mail.foo.com/
    backup              rsync://example.com/pub/  example.com/pub/
    backup              lvm://vg0/xen-home/       lvm-vg0/xen-home/
    backup_exec         echo "backup finished!"

rsnapshot can be used by any user, but for system-wide backups you will probably want to run it as root.

Since backups usually get neglected if human intervention is required, the preferred way is to run it from cron.

When you are first setting up your backups, you will probably also want to run it from the command line once or twice to get a feel for what it's doing.

Here is an example crontab entry, assuming that backup levels alpha, beta, gamma and delta have been defined in /etc/rsnapshot.conf

This example will do the following:

It is usually a good idea to schedule the larger backup levels to run a bit before the lower ones. For example, in the crontab above, notice that "beta" runs 10 minutes before "alpha".  The main reason for this is that the beta rotate will pull out the oldest alpha and make that the youngest beta (which means that the next alpha rotate will not need to delete the oldest alpha), which is more efficient.  A secondary reason is that it is harder to predict how long the lowest backup level will take, since it needs to actually do an rsync of the source as well as the rotate that all backups do.

If rsnapshot takes longer than 10 minutes to do the "beta" rotate (which usually includes deleting the oldest beta snapshot), then you should increase the time between the backup levels. Otherwise (assuming you have set the lockfile parameter, as is recommended) your alpha snapshot will fail sometimes because the beta still has the lock.

Remember that these are just the times that the program runs. To set the number of backups stored, set the retain numbers in /etc/rsnapshot.conf

To check the disk space used by rsnapshot, you can call it with the "du" argument.

For example:

This will show you exactly how much disk space is taken up in the snapshot root. This feature requires the UNIX du command to be installed on your system, for it to support the "-csh" command line arguments, and to be in your path. You can also override your path settings and the flags passed to du using the cmd_du and du_args parameters.

It is also possible to pass a relative file path as a second argument, to get a report on a particular file or subdirectory.

The GNU version of "du" is preferred. The BSD version works well also, but does not support the -h flag (use -k instead, to see the totals in kilobytes). Other versions of "du", such as Solaris, may not work at all.

To check the differences between two directories, call rsnapshot with the "diff" argument, followed by two backup levels or directory paths.

For example:

This will call the rsnapshot-diff program, which will scan both directories looking for differences (based on hard links).

rsnapshot sync

rsnapshot sync [dest]

rsnapshot configtest

/etc/rsnapshot.conf

rsync(1), ssh(1), logger(1), sshd(1), ssh-keygen(1), perl(1), cp(1), du(1), crontab(1)

Use the -t flag to see what commands would have been executed. This will show you the commands rsnapshot would try to run. There are a few minor differences (for example, not showing an attempt to remove the lockfile because it wasn't really created in the test), but should give you a very good idea what will happen.

Using the -v, -V, and -D flags will print increasingly more information to STDOUT.

Make sure you don't have spaces in the config file that you think are actually tabs.

Much other weird behavior can probably be attributed to plain old file system permissions and ssh authentication issues.

Please report bugs (and other comments) to the rsnapshot-discuss mailing list:

http://lists.sourceforge.net/lists/listinfo/rsnapshot-discuss

Make sure your /etc/rsnapshot.conf file has all elements separated by tabs. See /etc/rsnapshot.conf.default for a working example file.

Make sure you put a trailing slash on the end of all directory references. If you don't, you may have extra directories created in your snapshots. For more information on how the trailing slash is handled, see the rsync(1) manpage.

Make sure to make the snapshot directory chmod 700 and owned by root (assuming backups are made by the root user). If the snapshot directory is readable by other users, they will be able to modify the snapshots containing their files, thus destroying the integrity of the snapshots.

If you would like regular users to be able to restore their own backups, there are a number of ways this can be accomplished. One such scenario would be:

Set snapshot_root to /.private/.snapshots in /etc/rsnapshot.conf

Set the file permissions on these directories as follows:

Export the /.private/.snapshots directory over read-only NFS, a read-only Samba share, etc.

See the rsnapshot HOWTO for more information on making backups accessible to non-privileged users.

For ssh to work unattended through cron, you will probably want to use public key logins. Create an ssh key with no passphrase for root, and install the public key on each machine you want to backup. If you are backing up system files from remote machines, this probably means unattended root logins. Another possibility is to create a second user on the machine just for backups. Give the user a different name such as "rsnapshot", but keep the UID and GID set to 0, to give root privileges. However, make logins more restrictive, either through ssh configuration, or using an alternate shell.

BE CAREFUL! If the private key is obtained by an attacker, they will have free run of all the systems involved. If you are unclear on how to do this, see ssh(1), sshd(1), and ssh-keygen(1).

Backup scripts are run as the same user that rsnapshot is running as. Typically this is root. Make sure that all of your backup scripts are only writable by root, and that they don't call any other programs that aren't owned by root. If you fail to do this, anyone who can write to the backup script or any program it calls can fully take over the machine. Of course, this is not a situation unique to rsnapshot.

By default, rsync transfers are done using the --numeric-ids option. This means that user names and group names are ignored during transfers, but the UID/GID information is kept intact. The assumption is that the backups will be restored in the same environment they came from. Without this option, restoring backups for multiple heterogeneous servers would be unmanageable. If you are archiving snapshots with GNU tar, you may want to use the --numeric-owner parameter. Also, keep a copy of the archived system's /etc/passwd and /etc/group files handy for the UID/GID to name mapping.

If you remove backup points in the config file, the previously archived files under those points will permanently stay in the snapshots directory unless you remove the files yourself. If you want to conserve disk space, you will need to go into the <snapshot_root> directory and manually remove the files from the smallest backup level's ".0" directory.

For example, if you were previously backing up /home/ with a destination of localhost/, and alpha is your smallest backup level, you would need to do the following to reclaim that disk space:

Please note that the other snapshots previously made of /home/ will still be using that disk space, but since the files are flushed out of alpha.0/, they will no longer be copied to the subsequent directories, and will thus be removed in due time as the rotations happen.

Mike Rubel - http://www.mikerubel.org/computers/rsync_snapshots/

- Created the original shell scripts on which this project is based

Nathan Rosenquist (nathan@rsnapshot.org)

- Primary author and original maintainer of rsnapshot.

David Cantrell (david@cantrell.org.uk)

- Previous maintainer of rsnapshot

- Wrote the rsnapshot-diff utility

- Improved how use_lazy_deletes work so slow deletes don't screw up the next backup at that backup level.

David Keegel <djk@cybersource.com.au>

- Previous rsnapshot maintainer

- Fixed race condition in lock file creation, improved error reporting

- Allowed remote ssh directory paths starting with "~/" as well as "/"

- Fixed a number of other bugs and buglets

Benedikt Heine <benedikt@heine.rocks>

- Current rsnapshot maintainer

Carl Wilhelm Soderstrom (chrome@real-time.com)

- Created the RPM .spec file which allowed the RPM package to be built, among other things.

Ted Zlatanov (tzz@lifelogs.com)

- Added the one_fs feature, autoconf support, good advice, and much more.

Ralf van Dooren (r.vdooren@snow.nl)

- Added and maintains the rsnapshot entry in the FreeBSD ports tree.

SlapAyoda

- Provided access to his computer museum for software testing.

Carl Boe (boe@demog.berkeley.edu)

- Found several subtle bugs and provided fixes for them.

Shane Leibling (shane@cryptio.net)

- Fixed a compatibility bug in utils/backup_smb_share.sh

Christoph Wegscheider (christoph.wegscheider@wegi.net)

- Added (and previously maintained) the Debian rsnapshot package.

Bharat Mediratta (bharat@menalto.com)

- Improved the exclusion rules to avoid backing up the snapshot root (among other things).

Peter Palfrader (weasel@debian.org)

- Enhanced error reporting to include command line options.

Nicolas Kaiser (nikai@nikai.net)

- Fixed typos in program and man page

Chris Petersen - (http://www.forevermore.net/)

Added cwrsync permanent-share support

Robert Jackson (RobertJ@promedicalinc.com)

Added use_lazy_deletes feature

Justin Grote (justin@grote.name)

Improved rsync error reporting code

Anthony Ettinger (apwebdesign@yahoo.com)

Wrote the utils/mysqlbackup.pl script

Sherman Boyd

Wrote utils/random_file_verify.sh script

William Bear (bear@umn.edu)

Wrote the utils/rsnapreport.pl script (pretty summary of rsync stats)

Eric Anderson (anderson@centtech.com)

Improvements to utils/rsnapreport.pl.

Alan Batie (alan@batie.org)

Bug fixes for include_conf

Dieter Bloms (dieter@bloms.de)

Multi-line configuration options

Henning Moll (newsScott@gmx.de)

stop_on_stale_lockfile

Ben Low (ben@bdlow.net)

Linux LVM snapshot support

Copyright (C) 2003-2005 Nathan Rosenquist

Portions Copyright (C) 2002-2007 Mike Rubel, Carl Wilhelm Soderstrom, Ted Zlatanov, Carl Boe, Shane Liebling, Bharat Mediratta, Peter Palfrader, Nicolas Kaiser, David Cantrell, Chris Petersen, Robert Jackson, Justin Grote, David Keegel, Alan Batie, Dieter Bloms, Henning Moll, Ben Low, Anthony Ettinger

This man page is distributed under the same license as rsnapshot: the GPL (see below).

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA