summaryrefslogtreecommitdiff
path: root/rdiff-backup/rdiff-backup.1
blob: 1c4a5899d396936209a6200935632024ed18fbbb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
.TH RDIFF-BACKUP 1 "AUGUST 2001" "Version 0.2.1" "User Manuals" \" -*- nroff -*-
.SH NAME
rdiff-backup \- rsync-like incremental backup utility
.SH SYNOPSIS
.B rdiff-backup
.BI [ options ]
.BI [[[ user@ ] host1.foo ]:: source_directory ]
.BI [[[ user@ ] host2.foo ]:: destination_directory ]


.SH DESCRIPTION
.B rdiff-backup
is a script, written in
.BR python (1) ,
that uses the
.BR rdiff (1)
program to back up one directory to another.  The target directory
ends up a copy of the source directory, but extra reverse diffs are
stored in the target directory, so you can still recover files lost
some time ago.  The idea is to combine the best features of a mirror
and an incremental backup.  rdiff-backup also preserves symlinks,
special files, permissions, uid/gid ownership (if it is running as
root), and modification times.

.B rdiff-backup
can also operate
in a bandwidth efficient manner over a pipe, like
.BR rsync (1).
Thus you can use ssh and rdiff-backup to securely back a hard drive up
to a remote location, and only the differences will be transmitted.
Using the default settings, rdiff-backup requires that the remote
system accept ssh connections, and that
.B rdiff-backup
is installed in the user's PATH on the remote system.  For information
on other options, see the section on
.B REMOTE OPERATION.


.SH OPTIONS
.TP
.B -b, --backup-mode
Force backup mode even if first argument appears to be an increment file.
.TP
.B --change-source-perms
If this option is set, rdiff-backup will try to change the mode of any
unreadable files or unreadable/unexecutable directories in the source
directory so it can back them up.  It will then restore their original
permissions and mtimes afterwards.
.TP
.BI "--checkpoint-interval " seconds
This option controls every how many seconds rdiff-backup checkpoints
its current status.  The default is 20.
.TP
.BI "--exclude " regexp
Exclude files matching regexp.  This argument can be used multiple times.
.TP
.B "--exclude-device-files"
Exclude all device files.  This can be useful for security/permissions
reasons or if rdiff-backup is not handling device files correctly.
.TP
.BI "--exclude-mirror " regexp
Exclude files in the mirror area matching regexp.  This argument can
be used multiple times.  The rdiff-backup-data directory is
automatically excluded.
.TP
.B --force
Authorize overwriting of a destination directory.  rdiff-backup will
generally tell you if it needs this.
.TP
.B "-l, --list-increments"
List the number and date of partial incremental backups contained in
the specified destination directory.
.TP
.B "-m, --mirror-only"
Do not create an rdiff-backup-data directory or make any increments.
In this mode rdiff-backup is similar to rsync (but usually
slower).
.TP
.B --no-resume
Do not resume last aborted backup even if it falls within the resume
window.
.TP
.BI "--remote-cmd " command
This command has been depreciated as of version 0.4.1.  Use
--remote-schema instead.
.TP
.BI "--remote-schema " schema
Specify an alternate method of connecting to a remote computer.  This
is necessary to get rdiff-backup not to use ssh for remote backups, or
if, for instance, rdiff-backup is not in the PATH on the remote side.
See the
.B REMOTE OPERATION
section for more information.
.TP
.BI "--remove-older-than " time_interval
Remove the incremental backups in the destination directory that have
been around longer than time_interval.  The time interval is an
integer followed by the character s, m, h, D, M, or Y, indicating
seconds, minutes, hours, days, months, or years respectively.  Thus
32m means 32 minutes, while 1M means one month (30 days).
.TP
.B --resume
Resume the last aborted backup.  If no aborted backups are found, exit
with error.
.TP
.BI "--resume-window " seconds
Resume the last aborted backup if it started less than the specified
number of seconds ago.  Otherwise start a new backup.  The default is
7200 (2 hours).
.TP
.B --server
Enter server mode (not to be invoked directly, but instead used by
another rdiff-backup process on a remote computer).
.TP
.BI "--terminal-verbosity " [0-9]
Select which messages will be displayed to the terminal.  If missing
the level defaults to the verbosity level.
.TP
.B --test-server
Test for the presence of a compatible rdiff-backup server as specified
in the following host::filename argument(s).  The filename section
will be ignored.
.TP
.BI -v [0-9] ", --verbosity " [0-9]
Specify verbosity level (0 is totally silent, 3 is the default, and 9
is noisiest).  This determines how much is written to the log file.
.TP
.B "-V, --version"
Print the current version and exit
.TP
.B --windows-time-format
If this option is present, use underscores instead of colons in
increment files, so 2001-07-15T04:09:38-07:00 becomes
2001-07-15T04_09_38-07_00.  This option may be useful under MS windows
NT, which prohibits colons in filenames.

.SH EXAMPLES
Simplest case---backup directory foo to directory bar, with increments
in bar/rdiff-backup-data:
.PP
.RS
rdiff-backup foo bar
.PP
.RE
This is exactly the same as previous example because trailing slashes
are ignored:
.PP
.RS
rdiff-backup foo/ bar/
.PP
.RE
Back files up from /home/bob to /mnt/backup, leaving increments in /mnt/backup/rdiff-backup-data.  Do not back up directory /home/bob/tmp or any files in it.
.PP
.RS
rdiff-backup --exclude /home/bob/tmp /home/bob /mnt/backup
.PP
.RE
You can also use regular expressions in the --exclude statements.
This will skip any files whose full pathnames contain the word
"cache", or any files whose name is "tmp" or "temp".
.PP
.RS
rdiff-backup --exclude '.*cache.*' --exclude '.*/te?mp' /home/bob /mnt/backup
.PP
.RE
After the previous command was completed, this command will list the
backups present on the destination disk:
.PP
.RS
rdiff-backup --list-increments /mnt/backup
.PP
.RE
If space is running out on the /mnt/backup directory, older
incremental backups can be erased.  The following command erases
backup information older than a week:
.PP
.RS
rdiff-backup --remove-older-than 7D /mnt/backup
.PP
.RE
The following reads the file
important-data.2001-07-15T04:09:38-07:00.dir and restores the
resulting directory important-data as it was on Februrary 14, 2001,
calling the new directory "temp".  Note that rdiff-backup goes into
restore mode because it recognizes the suffix of the file.  The -v9
means keep lots of logging information.
.PP
.RS
rdiff-backup -v9 important-data.2001-07-15T04:09:38-07:00.dir temp
.PP
.RE
This command causes rdiff-backup to backup the directory
/some/local-dir to the directory /whatever/remote-dir on the machine
hostname.net.  It uses ssh to open the necessary pipe to the remote
copy of rdiff-backup.  Here the username on the local machine and on
hostname.net are the same.
.PP
.RS
rdiff-backup /some/local-dir hostname.net::/whatever/remote-dir
.PP
.RE
This command logs into hostname.net as smith and restores the remote
increment old-file on a remote computer to the current directory on
the local computer:
.PP
.RS
rdiff-backup smith@hostname.net::/foo/rdiff-backup-data/increments/bar/old-file.2001-11-09T12:43:53-04:00.diff
.PP
.RE
Backup foo on one remote machine to bar on another.  This will
probably be slower than running rdiff-backup from either machine.
.PP
.RS
rdiff-backup smith@host1::foo jones@host2::bar
.PP
.RE
Test to see if the specified ssh command really opens up a working
rdiff-backup server on the remote side.
.RS
rdiff-backup --test-server hostname.net::/this/is/ignored

.SH REMOTE OPERATION
In order to access remote files, rdiff-backup opens up a pipe to a
copy of rdiff-backup running on the remote machine.  Thus rdiff-backup
must be installed on both ends.  To open this pipe, rdiff-backup first
splits the filename into host_info::pathname.  It then substitutes
host_info into the remote schema, and runs the resulting command,
reading its input and output.
.PP
The default remote schema is 'ssh %s rdiff-backup --server' meaning if
the host_info is user@host.net, then rdiff-backup runs 'ssh
user@host.net rdiff-backup --server'.  The '%s' keyword is substituted
with the host_info.  Using --remote-schema, rdiff-backup can invoke an
arbitrary command in order to open up a remote pipe.  For instance,
.RS
rdiff-backup --remote-schema 'cd /usr; %s' foo 'rdiff-backup
--server'::bar
.RE
is basically equivalent to (but slower than)
.RS
rdiff-backup foo /usr/bar
.RE
.PP
Concerning quoting, if for some reason you need to put two consecutive
colons in the host_info section of a host_info::pathname argument, or
in the pathname of a local file, you can quote one of them by
prepending a backslash.  So in 'a\\::b::c', host_info is 'a::b' and
the pathname is 'c'.  Similarly, if you want to refer to a local file
whose filename contains two consecutive colons, like 'strange::file',
you'll have to quote one of the colons as in 'strange\\::file'.
Because the backslash is a quote character in these circumstances, it
too must be quoted to get a literal backslash, so 'foo\\::\\\\bar'
evaluates to 'foo::\\bar'.  To make things more complicated, because
the backslash is also a common shell quoting character, you may need
to type in '\\\\\\\\' at the shell prompt to get a literal backslash
(if it makes you feel better, I had to type in 8 backslashes to get
that in this man page...).  And finally, to include a literal % in the
string specified by --remote-schema, quote it with another %, as in
%%.

.SH BUGS
Hard linking is not preserved.

rdiff-backup uses the shell command
.BR mknod (1)
to backup device files (e.g. /dev/ttyS0), so device files won't be
handled correctly on systems with non-standard mknod syntax.

.SH AUTHOR
Ben Escoto <bescoto@stanford.edu>
.PP
Feel free to ask me questions or send me bug reports, but also check
out the mailing list mentioned below.

.SH SEE ALSO
.BR python (1),
.BR rdiff (1),
.BR rsync (1),
.BR ssh (1).
The main rdiff-backup web page is at
.IR http://www.stanford.edu/~bescoto/rdiff-backup .
There also a mailing list described at
.IR http://keywest.Stanford.EDU/mailman/listinfo/rdiff-backup .