1 .TH rsync-backup 8 "7 October 2012" rsync-backup
10 script is a backup program of the currently popular
15 ability to create hardlinks from (apparently) similar existing local
16 trees to make incremental dumps efficient, even from remote sources.
17 Restoring files is easy because the backups created are just directories
18 full of files, exactly as they were on the source \(en and this is
23 The script does more than just running
25 It is also responsible for creating and removing snapshots of volumes to
26 be backed up, and expiring old dumps according to a user-specified
31 script should be installed and run on a central backup server with local
32 access to the backup volumes.
34 The script should be run with full (root) privileges, so that it can
35 correctly record file ownership information. The server should also be
38 to the client machines, and run processes there as root. (This is not a
39 security disaster. Remember that the backup server is, in the end,
40 responsible for the integrity of the backup data. A dishonest backup
41 server can easily compromise a client which is being restored from
47 .SS Configuration commands
48 The configuration file is simply a Bash shell fragment: configuration
49 commands are shell functions.
51 .BI "backup " "fs\fR[:\fIfsarg\fR] ..."
52 Back up the named filesystems. The corresponding
54 may be required by the snapshot type.
59 commands will back up filesystems on the named
65 .BI "like " "host\fR ..."
66 Declare that subsequent filesystems are `similar' to like-named
67 filesystems on the named
71 should use those trees as potential sources of hardlinkable files. Be
72 careful when using this option without
75 option: an erroneous hardlink will cause the backup to fail. (The
76 backup won't be left silently incorrect.)
78 .BI "retain " frequency " " duration
79 Define part a backup retention policy: backup trees of the
81 should be kept for the
93 which means the same); the
101 Expiry considers each existing dump against the policy lines in order:
102 the last applicable line determines the dump's fate \(en so you should
103 probably write the lines in decreasing order of duration.
105 .BI "snap " type " " \fR[\fIargs\fR...]
108 for subsequent backups. Some snapshot types require additional
109 arguments, which may be supplied here.
110 .SS Configuration variables
111 The following shell variables may be overridden by the configuration
115 The number of log files to be kept for each filesystem. Old logfiles
116 are deleted to keep the total number below this bound. The default
120 Command-line options to pass to
122 in addition to the basic set:
123 .B \-\-archive \-\-hard-links \-\-numeric-ids \-\-del \-\-sparse
124 .B \-\-compress \-\-one-file-system \-\-partial
125 .B \-\-filter="dir-merge .rsync-backup"
132 snapshots are mounted on subdirectories below the
134 .IR "on backup clients" .
139 is the backup mount directory configured at build time.
142 The volume size option to pass to
144 when creating a snapshot. The default is
146 which seems to work fairly well.
149 Where the actual backup trees should be stored. See the section on
156 is the backup mount directory configured at build time.
159 The hash function to use for verifying archive integrity. This is
164 so it must name one of the hash functions supported by your Python's
166 module. The default is
169 The configuration file may define shell functions to perform custom
170 actions at various points in the backup process.
172 .BI "backup_precommit_hook " host " " fs " " date
173 Called after a backup has been verified complete and about to be
174 committed. The backup tree is in
176 in the current directory, and the
180 A typical action would be to create a digital signature on the
183 .BI "backup_commit_hook " host " " fs " " date
184 Called during the commit procedure. The backup tree and manifest have
185 been renamed into their proper places. Typically one would use this
186 hook to rename files created by the
187 .B backup_precommit_hook
190 .BR "whine " [ \-n ] " " \fItext\fR...
191 Called to report `interesting' events when the
193 option is in force. The default action is to echo the
195 to (what was initially) standard output, followed by a newline unless
199 The following snapshot types are available.
202 A trivial snapshot type: attempts to back up a live filesystem. How
203 well this works depends on how active the filesystem is. If files
204 change while the dump is in progress then the
206 verification will likely fail. Backups using this snapshot type must
207 specify the filesystem mount point as the
211 A slightly less trivial snapshot type: make the filesystem read-only
212 while the dump is in progress. Backups using this snapshot type must
213 specify the filesystem mount point as the
217 Create snapshots using LVM. The snapshot argument is interpreted as the
218 relevant volume group. The filesystem name is interpreted as the origin
219 volume name; the snapshot will be called
222 .IB SNAPDIR / fs \fR;
223 space will be allocated to it according to the
227 .BI "rfreezefs " client " " vg
228 This gets complicated. Suppose that a server has an LVM volume group,
229 and exports (somehow) a logical volume to a client. Examples are a host
230 providing a virtual disk to a guest, or a server providing
231 network-attached storage to a client. The server can create a snapshot
232 of the volume using LVM, but must synchronize with the client to ensure
233 that the filesystem image captured in the snapshot is clean. The
235 program should be installed on the client to perform this rather
236 delicate synchronization. Declare the server using the
238 command as usual; pass the client's name as the
241 server's volume group name as the
243 snapshot arguments. Finally, backups using this snapshot type must
244 specify the filesystem mount point (or, actually, any file in the
245 filesystem) on the client, as the
248 Additional snapshot types can be defined in the configuration file. A
249 snapshot type requires two shell functions.
251 .BI snap_ type " " snapargs " " fs " " fsarg
252 Create the snapshot, and write the mountpoint (on the client host) to
253 standard output, in a form suitable as an argument to
256 .BI unsnap_ type " " snapargs " " fs " " fsarg
259 There are a number of utility functions which can be used by snapshot
260 type handlers: please see the script for details. Please send the
261 author interesting snapshot handlers for inclusion in the main
263 .SS Archive structure
~mdw / rsync-backup / blob