man rsnapshot (Commandes) - remote filesystem snapshot utility

NAME

rsnapshot - remote filesystem snapshot utility

SYNOPSIS

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

DESCRIPTION

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 BIrsync(1). Secure remote connections are handled with rsync over BIssh(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: -v verbose, show shell commands being executed -t test, show shell commands that would be executed -c path to alternate config file -x one filesystem, don't cross partitions within each backup point -q quiet, suppress non-fatal warnings -V same as -v, but with more detail -D a firehose of diagnostic information

CONFIGURATION

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

Here is a list of allowed parameters: config_version Config file version (required). Default is 1.2. Make sure this is the first parameter snapshot_root Local filesystem path to save all snapshots no_create_root If set to 1, rsnapshot won't create snapshot_root directory cmd_rsync Full path to rsync (required) cmd_ssh Full path to ssh (optional) cmd_cp Full path to cp (optional, but must be GNU version) If you are using Linux, you should uncomment cmd_cp. If you are using a different platform, you should leave cmd_cp commented out. With GNU cp, rsnapshot can take care of both normal files and special files (such as FIFOs, sockets, and block/character devices) in one pass. If cmd_cp is disabled, rsnapshot will use its own built-in function, native_cp_al() to backup up regular files and directories. This will then be followed up by a seperate call to rsync, to move the special files over (assuming there are any). cmd_rm Full path to rm (optional) cmd_logger Full path to logger (optional, for syslog support) cmd_du Full path to du (optional, for disk usage reports) interval [name] [number] name refers to the name of this interval (i.e. hourly, daily). number is the number of snapshots for this type of interval that will be stored. The value of name will be the command passed to rsnapshot to perform this type of backup. Example: interval hourly 6 [root@localhost]# rsnapshot hourly For this example, every time this is run, the following will happen: <snapshot_root>/hourly.5/ will be deleted, if it exists. <snapshot_root>/hourly.{1,2,3,4} will all be rotated +1, if they exist. <snapshot_root>/hourly.0/ will be copied to <snapshot_root>/hourly.1/ using hard links. Each backup point (explained below) will then be rsynced to the corresponding directories in <snapshot_root>/hourly.0/ Intervals must be specified in the config file in order, from most frequent to least frequent. The first entry is the one which will be synced with the backup points. The subsequent intervals (i.e. daily, weekly, etc) simply rotate, with each higher interval pulling from the one below it for its .0 directory. Example: interval hourly 6 interval daily 7 interval weekly 4 daily.0/ will be copied from hourly.5/, and weekly.0/ will be copied from daily.6/ hourly.0/ will be rsynced directly from the filesystem. link_dest 1 If your version of rsync supports --link-dest (2.5.7 or newer), you can enable this to let rsync handle some things that GNU cp or the built-in subroutines would otherwise do. Enabling this makes rsnapshot take a slightly more complicated code branch, but it's the best way to support special files on non-Linux systems. verbose 2 The amount of information to print out when the program is run. Allowed values are 1 through 5. The default is 2. 

    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
loglevel 3 This number means the same thing as verbose above, but it determines how much data is written to the logfile, if one is being written. The only thing missing from this at the higher levels is the direct output from rsync. We hope to add support for this in a future relase. logfile /var/log/rsnapshot Full filesystem path to the rsnapshot log file. If this is defined, a log file will be written, with the amount of data being controlled by loglevel. If this is commented out, no log file will be written. include ??? This gets passed directly to rsync using the --include directive. This parameter can be specified as many times as needed, with one pattern defined per line. See the rsync(1) man page for the syntax. exclude ??? This gets passed directly to rsync using the --exclude directive. This parameter can be specified as many times as needed, with one pattern defined per line. See the rsync(1) man page for the syntax. include_file /path/to/include/file This gets passed directly to rsync using the --include-from directive. See the rsync(1) man page for the syntax. exclude_file /path/to/exclude/file This gets passed directly to rsync using the --exclude-from directive. See the rsync(1) man page for the syntax. rsync_short_args -a List of short arguments to pass to rsync. If not specified, -a is the default. Please note that these must be all next to each other. For example, -az is valid, while -a -z is not. rsync_long_args --delete --numeric-ids --relative --delete-excluded List of long arguments to pass to rsync. Beginning with rsnapshot 1.2.0, this default has changed. In previous versions, the default values were 
    --delete --numeric-ids
Starting with version 1.2.0, the default values are 
    --delete --numeric-ids --relative --delete-excluded
This directly affects how the destination paths in your backup points are constructed. Depending on what behaviour you want, you can explicitly set the values to make the program behave like the old version or the current version. The newer settings are recommended if you're just starting. If you are upgrading, read the upgrade guide in the INSTALL file in the source distribution for more information. NOTE: In Debian the --relative option is automatically omitted if rsnapshot is used with a pre v1.2 config file to ensure backward compatibility. However it is strongly recommended to update the config file, please read /usr/share/doc/rsnapshot/NEWS.Debian.gz for a starting point on how to do this. ssh_args -p 22 Arguments to be passed to ssh. If not specified, the default is none. du_args -csh Arguments to be passed to du. If not specified, the default is -csh. GNU du supports -csh, BSD du supports -csk, Solaris du doesn't support -c at all. The GNU version is recommended, since it offers the most features. lockfile /var/run/rsnapshot.pid Lockfile to use when rsnapshot is run. This prevents a second invocation from clobbering the first one. If not specified, no lock file is used. Make sure to use a directory that is not world writeable for security reasons. one_fs 1 Prevents rsync from crossing filesystem partitions. Setting this to a value of 1 enables this feature. 0 turns it off. This parameter is optional. The default is off. UPGRADE NOTICE: If you have used an older version of rsnapshot, you might notice that the destination paths on the backup points have changed. Please read the INSTALL file in the source distribution for upgrade options. backup /etc/ localhost/ backup root@example.com:/etc/ example.com/ backup rsync://example.com/path2/ example.com/ backup /var/ localhost/ one_fs=1 backup_script /usr/local/bin/backup_pgsql.sh pgsql_backup/ Examples: backup /etc/ localhost/ Backs up /etc/ to <snapshot_root>/<interval>.0/localhost/etc/ using rsync on the local filesystem backup /usr/local/ localhost/ Backs up /usr/local/ to <snapshot_root>/<interval>.0/localhost/usr/local/ using rsync on the local filesystem backup root@example.com:/etc/ example.com/ Backs up root@example.com:/etc/ to <snapshot_root>/<interval>.0/example.com/etc/ using rsync over ssh backup root@example.com:/usr/local/ example.com/ Backs up root@example.com:/usr/local/ to <snapshot_root>/<interval>.0/example.com/usr/local/ using rsync over ssh backup rsync://example.com/pub/ example.com/pub/ Backs up rsync://example.com/pub/ to <snapshot_root>/<interval>.0/example.com/pub/ using an anonymous rsync server. Please note that unlike backing up local paths and using rsync over ssh, rsync servers have modules, which are top level directories that are exported. Therefore, the module should also be specified in the destination path, as shown in the example above (the pub/ directory at the end). backup /var/ localhost/ one_fs=1 This is the same as the other examples, but notice how the fourth parameter is passed. This sets this backup point to not span filesystem partitions. If the global one_fs has been set, this will override it locally. backup_script /usr/local/bin/backup_database.sh db_backup/ In this example, we specify a script or program to run. This script should simply create files and/or directories in it's current working directory. rsnapshot will then take that output and move it into the directory specified in the third column. Please note that whatever is in the destination directory will be completely deleted and recreated. For this reason, rsnapshot prevents you from specifying a destination directory for a backup_script that will clobber other backups. So in this example, say the backup_database.sh script simply runs a command like: #!/bin/sh mysqldump -uusername mydatabase > mydatabase.sql rsnapshot will take the generated mydatabase.sql file and move it into the <snapshot_root>/<interval>.0/db_backup/ directory. On subsequent runs, rsnapshot checks the differences between the files created against the previous files. If the backup script generates the same output on the next run, the files will be hard linked against the previous ones, and no additional disk space will be taken up.

Remember that tabs must separate all elements, and that there must be a trailing slash on the end of every directory.

A hash mark (#) on the beginning of a line is treated as a comment.

Putting it all together (an example file): 

    # THIS IS A COMMENT, REMEMBER TABS MUST SEPERATE 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

    interval        hourly  6
    interval        daily   7
    interval        weekly  7
    interval        monthly 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/

USAGE

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 intervals hourly, daily, weekly and monthly have been defined in /etc/rsnapshot.conf 0 */4 * * * /usr/local/bin/rsnapshot hourly 50 23 * * * /usr/local/bin/rsnapshot daily 40 23 1,8,15,22 * * /usr/local/bin/rsnapshot weekly 30 23 1 * * /usr/local/bin/rsnapshot monthly

This example will do the following: 6 hourly backups a day (once every 4 hours, at 0,4,8,12,16,20) 1 daily backup every day, at 11:50PM 4 weekly backups a month, at 11:40PM, on the 1st, 8th, 15th, and 22nd 1 monthly backup every month, at 11:30PM on the 1st day of the month

It is usually a good idea to schedule the larger intervals to run a bit before the lower ones. For example, in the crontab above, notice that daily runs 10 minutes before hourly. This helps prevent race conditions where the daily would try to run before the hourly job had finished. This is where the lockfile parameter really comes in handy.

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

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

For example: rsnapshot du

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. rsnapshot du localhost/home/

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.

EXIT VALUES

0 All operations completed successfully 1 A fatal error occurred 2 Some warnings occurred, but the backup still finished

FILES

/etc/rsnapshot.conf

SEE ALSO

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

DIAGNOSTICS

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.

BUGS

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

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

NOTES

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 BIrsync(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: drwx------ /.private drwxr-xr-x /.private/.snapshots

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 BIssh(1), BIsshd(1), and BIssh-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 interval's .0 directory.

For example, if you were previously backing up /home/ with a destination of localhost/, and hourly is your smallest interval, you would need to do the following to reclaim that disk space: rm -rf <snapshot_root>/hourly.0/localhost/home/

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 hourly.0/, they will no longer be copied to the subsequent directories, and will thus be removed in due time as the rotations happen.

AUTHORS

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 maintainer of rsnapshot.

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

COPYRIGHT

Copyright (C) 2003-2005 Nathan Rosenquist

Portions Copyright (C) 2002-2005 Mike Rubel, Carl Wilhelm Soderstrom, Ted Zlatanov, Carl Boe, Shane Liebling, Bharat Mediratta, Peter Palfrader

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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA