README.md
1# RSNAPSHOT [![Build Status](https://api.travis-ci.org/rsnapshot/rsnapshot.png?branch=master)](https://travis-ci.org/rsnapshot/rsnapshot)
2
3rsnapshot comes with ABSOLUTELY NO WARRANTY. This is free software,
4and you are welcome to redistribute it under certain conditions.
5See the GNU General Public Licence for details.
6
7rsnapshot is a filesystem snapshot utility based on rsync. rsnapshot makes it
8easy to make periodic snapshots of local machines, and remote machines over ssh.
9The code makes extensive use of hard links whenever possible, to greatly reduce
10the disk space required.
11
12It is written entirely in perl with no module dependencies, and has been
13tested with versions 5.004 through 5.24.3. It should work on any reasonably
14modern UNIX compatible OS. It has been tested successfully on the following
15operating systems:
16
17 - Debian: 3.0 (woody), 9.9 (stretch)
18 - Redhat: 7.x, 8.0
19 - RedHat Enterprise Linux: 3.0 ES, 5, 6, 7
20 - Fedora Core: 1, 3
21 - Fedora: 17, 18
22 - CentOS: 3, 4, 5, 6, 7
23 - WhiteBox Enterprise Linux 3.0
24 - Slackware 9.0
25 - SuSE: 9.0
26 - Gentoo Linux
27 - FreeBSD 4.9-STABLE
28 - OpenBSD 3.x
29 - Solaris 8 (SPARC and x86)
30 - Mac OS X
31 - IRIX 6.5
32
33If this is your first experience with rsnapshot, you may want to read the man
34page which will give you a detailed walk-through on how to get rsnapshot up and
35running and also serve as a reference of all available commands.
36
37If you are upgrading from version 1.1.6 or earlier, make sure you read the
38file [Upgrading from 1.1](docs/Upgrading_from_1.1).
39
40For installation or upgrade instructions please read the [INSTALL](INSTALL.md) doc.
41
42If you want to work on improving rsnapshot please read the
43[CONTRIBUTING](CONTRIBUTING.md) doc.
44
45If you want to ask a question or have a general discussion use the
46[Mailing List](https://lists.sourceforge.net/lists/listinfo/rsnapshot-discuss).
47
48## COMPATIBILITY NOTICES (Please read)
49
50 1. Note that systems which use GNU cp version 5.9 or later will have problems
51 with rsnapshot versions up to and including 1.2.3, if `cmd_cp` is enabled
52 (and points at the later gnu cp). This is no longer a problem since
53 rsnapshot 1.2.9, as it strips off trailing slashes when running cp.
54
55 2. If you have rsync version 2.5.7 or later, you may want to enable the
56 link_dest parameter in the rsnapshot.conf file.
57
58 If you are running Linux but do not have the problem above, you should
59 enable the `cmd_cp` parameter in rsnapshot.conf (especially if you do not
60 have link_dest enabled).
61
62 Be advised that currently `link_dest` doesn't do well with unavailable hosts.
63 Specifically, if a remote host is unavailable using `link_dest`, there will
64 be no latest backup of that machine, and a full re-sync will be required
65 when it becomes available. Using the other methods, the last good snapshot
66 will be preserved, preventing the need for a re-sync. We hope to streamline
67 this in the future.
68
69## CONFIGURATION
70Once you have installed rsnapshot, you will need to configure it.
71The default configuration file is /etc/rsnapshot.conf, although the exact path
72may be different depending on how the program was installed. If this
73file does not exist, copy `/etc/rsnapshot.conf.default` over to
74`/etc/rsnapshot.conf` and edit it to suit your tastes. See the man page for
75the full list of configuration options.
76
77When `/etc/rsnapshot.conf` contains your chosen settings, do a quick sanity
78check to make sure everything is ready to go:
79
80 $ rsnapshot configtest
81
82If this works, you can see essentially what will happen when you run it for
83real by executing the following command (where interval is `alpha`, `beta`, `etc`):
84
85 $ rsnapshot -t [interval]
86
87Once you are happy with everything, the final step is to setup a cron job to
88automate your backups. Here is a quick example which makes backups every four
89hours, and beta backups for a week:
90
91 0 */4 * * * /usr/local/bin/rsnapshot alpha
92 50 23 * * * /usr/local/bin/rsnapshot beta
93
94In the previous example, there will be six `alpha` snapshots
95taken each day (at 0,4,8,12,16, and 20 hours). There will also
96be beta snapshots taken every night at 11:50PM. The number of
97snapshots that are saved depends on the "interval" settings in
98/etc/rsnapshot.conf.
99
100For example:
101
102 interval alpha 6
103
104This means that every time `rsnapshot alpha` is run, it will make a
105new snapshot, rotate the old ones, and retain the most recent six
106(`alpha.0` - `alpha.5`).
107
108If you prefer instead to have three levels of backups (which we'll
109call `beta`, `gamma` and `delta`), you might set up cron like this:
110
111 00 00 * * * /usr/local/bin/rsnapshot beta
112 00 23 * * 6 /usr/local/bin/rsnapshot gamma
113 00 22 1 * * /usr/local/bin/rsnapshot delta
114
115This specifies a `beta` rsnapshot at midnight, a `gamma` snapshot
116on Saturdays at 11:00pm and a `delta` rsnapshot at 10pm on the
117first day of each month.
118
119Note that the backups are done from the highest interval first
120(in this case `delta`) and go down to the lowest interval. If
121you are not having cron invoke the `alpha` snapshot interval,
122then you must also ensure that `alpha` is not listed as one of
123your intervals in rsnapshot.conf (for example, comment out alpha,
124so that `beta` becomes the lowest interval).
125
126Remember that it is only the lowest interval which actually does
127the rsync to back up the relevant source directories, the higher
128intervals just rotate snapshots around. Unless you have enabled
129`sync_first` in your configuration-file, in which case only the `sync`
130pseudo-interval does the actual rsync, and all real intervals
131just rotate snapshots.
132
133For the full documentation, type `man rsnapshot` once it is installed. The
134[HOWTO](docs/HOWTOs/rsnapshot-HOWTO.en.html) also has a detailed overview of
135how to install and configure rsnapshot, and things like how to set it up so
136users can restore their own files.
137
138If you plan on using the `backup_script` parameter in your backup scheme,
139take a look at the `utils/`-directory in the source distribution for several
140example scripts. The `utils/rsnapreport.pl` script is well worth a look.
141
142## AUTHORS
143
144Please see the [AUTHORS](/AUTHORS) file for the complete list of contributors.
145