Commit | Line | Data |
---|---|---|
6f039cc2 MP |
1 | \input texinfo |
2 | @setfilename rsync.info | |
3 | @settitle rsync | |
4 | @c %** end of header | |
5 | ||
6 | @titlepage | |
7 | @sp 10 | |
8 | @title rsync - fast, flexible file transfer program | |
9 | ||
10 | @c The copyright page | |
11 | @page | |
12 | @vskip 0pt plus 1filll | |
13 | Copyright @copyright{} 2002 by Martin Pool @email{mbp@@samba.org} | |
14 | ||
15 | Copyright @copyright{} 1996--2001 by Andrew Tridgell @email{tridge@@samba.org} | |
16 | @end titlepage | |
17 | ||
18 | @iftex | |
19 | @contents | |
20 | @end iftex | |
21 | ||
22 | @ifnottex | |
23 | @node Top, Overview, (dir), (dir) | |
24 | @top rsync | |
25 | ||
26 | rsync is a flexible program for efficiently copying files or directory | |
27 | trees. | |
28 | ||
29 | This manual documents rsync 2.5. It is not yet complete and should be | |
30 | consulted in conjunction with the rsync manual page. | |
31 | ||
32 | Copyright @copyright{} 2002 by Martin Pool @email{mbp@@samba.org}. | |
33 | ||
34 | Copyright @copyright{} 1996--2001 by Andrew Tridgell @email{tridge@@samba.org}. | |
35 | ||
36 | @menu | |
37 | * Overview:: Tutorial section | |
38 | * Invoking rsync:: | |
39 | * Daemon mode:: rsync listens for connections on its own socket | |
40 | ||
41 | * Concept Index:: | |
42 | * Option Index:: | |
43 | @end menu | |
44 | ||
45 | @end ifnottex | |
46 | ||
47 | @node Overview, Invoking rsync, Top, Top | |
48 | @chapter Overview | |
49 | ||
50 | rsync is a program for efficiently copying files or directory trees. | |
51 | rsync has many options to select which files will be copied and how | |
52 | they are to be transferred. It may be used as an alternative to @sc{ftp}, | |
53 | @sc{http}, @command{scp} or @command{rcp}. | |
54 | ||
55 | The rsync remote-update protocol allows rsync to transfer just the | |
56 | differences between two sets of files across the network link, using | |
57 | an efficient checksum-search algorithm described in the technical | |
58 | report that accompanies this package. | |
59 | ||
60 | rsync's command line syntax is analogous to @command{cp}, | |
61 | @command{rcp} and @command{scp}: | |
62 | ||
63 | @example | |
64 | rsync [@var{options}] @var{source} @var{destination} | |
65 | @end example | |
66 | ||
67 | Filenames may be prefixed by a hostname to indicate a remote file. | |
68 | (@xref{Local and remote}.) | |
69 | ||
70 | Some of the additional features of rsync are: | |
71 | ||
72 | @itemize @bullet | |
73 | ||
74 | @item support for copying links, devices, owners, groups and permissions | |
75 | ||
76 | @item exclude and exclude-from options similar to GNU tar | |
77 | ||
78 | @item a CVS exclude mode for ignoring the same files that CVS would ignore | |
79 | ||
80 | @item can use any transparent remote shell, including rsh or ssh | |
81 | ||
82 | @item does not require root privileges | |
83 | ||
84 | @item pipelining of file transfers to minimize latency costs | |
85 | ||
86 | @item support for anonymous or authenticated rsync servers (ideal for | |
87 | mirroring) | |
88 | ||
89 | @end itemize | |
90 | ||
91 | @menu | |
92 | * Introductory example:: 60-second guide to rsync | |
93 | * Local and remote:: Local, remote, and server mode | |
94 | * Setting up rsync:: | |
95 | @end menu | |
96 | ||
97 | ||
98 | ||
99 | @node Introductory example, Local and remote, Overview, Overview | |
100 | @section Introductory example | |
101 | ||
102 | Probably the most common case of rsync usage is to copy files to or | |
103 | from a remote machine using @command{ssh} as a network transport. In | |
104 | this situation rsync is a good alternative to @command{scp}. | |
105 | ||
106 | The most commonly used arguments for rsync are | |
107 | ||
108 | @table @code | |
109 | ||
110 | @item -a | |
111 | Reproduce the structure and attributes of the origin files as exactly | |
112 | as possible: this includes copying subdirectories, symlinks, special | |
113 | files, ownership and permissions. (@xref{Attributes to copy}.) | |
114 | ||
115 | @item -v | |
116 | Be verbose. Primarily, display the name of each file as it is copied. | |
117 | ||
118 | @item -z | |
119 | Compress network traffic, using a modified version of the | |
120 | @command{zlib} library. | |
121 | ||
122 | @item -P | |
123 | Display a progress indicator while files are transferred. This should | |
124 | normally be ommitted if rsync is not run on a terminal. | |
125 | ||
126 | @end table | |
127 | ||
128 | To make a backup of your home directory to the @file{/bkup/mbp/} | |
129 | remote machine @file{foo.example.org}, preserving the directory | |
130 | structure, use this command: | |
131 | ||
132 | @example | |
133 | rsync -avP ~ foo.example.org:/bkup/mbp/ | |
134 | @end example | |
135 | ||
136 | ||
137 | ||
138 | @node Local and remote, Setting up rsync, Introductory example, Overview | |
139 | @comment node-name, next, previous, up | |
140 | @section Local and remote | |
141 | ||
142 | There are six different ways of using rsync. They are: | |
143 | ||
144 | @enumerate | |
145 | ||
146 | @item for copying local files. This is invoked when neither | |
147 | source nor destination path contains a @code{:} separator | |
148 | ||
149 | @item for copying from the local machine to a remote machine using | |
150 | a remote shell program as the transport (such as rsh or | |
151 | ssh). This is invoked when the destination path contains a | |
152 | single @code{:} separator. | |
153 | ||
154 | @item for copying from a remote machine to the local machine | |
155 | using a remote shell program. This is invoked when the source | |
156 | contains a @code{:} separator. | |
157 | ||
158 | @item for copying from a remote rsync server to the local | |
159 | machine. This is invoked when the source path contains a @code{::} | |
160 | separator or a @code{rsync://} URL. | |
161 | ||
162 | @item for copying from the local machine to a remote rsync | |
163 | server. This is invoked when the destination path contains a @code{::} | |
164 | separator. | |
165 | ||
166 | @item for listing files on a remote machine. This is done the | |
167 | same way as rsync transfers except that you leave off the | |
168 | local destination. | |
169 | @cindex listing files | |
170 | @end enumerate | |
171 | ||
172 | Note that in all cases (other than listing) at least one of the source | |
173 | and destination paths must be local. | |
174 | ||
175 | Any one invocation of rsync makes a copy in a single direction. rsync | |
176 | currently has no equivalent of @command{ftp}'s interactive mode. | |
177 | ||
178 | @cindex @sc{nfs} | |
179 | @cindex network filesystems | |
180 | @cindex remote filesystems | |
181 | ||
182 | rsync's network protocol is generally faster at copying files than | |
183 | network filesystems such as @sc{nfs} or @sc{cifs}. It is better to | |
184 | run rsync on the file server either as a daemon or over ssh than | |
185 | running rsync giving the network directory. | |
186 | ||
187 | ||
188 | @node Setting up rsync, , Local and remote, Overview | |
189 | @comment node-name, next, previous, up | |
190 | @section Setting up rsync | |
191 | ||
192 | @cindex installation | |
193 | See the file @sc{install} that comes with the distribution for installation | |
194 | instructions. | |
195 | ||
196 | @cindex @command{rsh} | |
197 | @cindex @command{rsh}, alternatives to | |
198 | @cindex @command{ssh} | |
199 | ||
200 | Once installed you can use rsync to any machine that you can use | |
201 | @command{rsh} to. rsync uses @command{rsh} for its communications, | |
202 | unless both the source and destination are local. | |
203 | ||
204 | You can also specify an alternative to rsh, either by using the | |
205 | @option{-e} command line option, or by setting the | |
206 | @var{@sc{rsync_rsh}} environment variable. | |
207 | ||
208 | One common substitute is to use @command{ssh}, which offers a high | |
209 | degree of security. | |
210 | ||
211 | Note that rsync must be installed on both the source and destination | |
212 | machines. | |
213 | ||
214 | ||
215 | ||
216 | @node Invoking rsync, Daemon mode, Overview, Top | |
217 | @comment node-name, next, previous, up | |
218 | @chapter Invoking rsync | |
219 | ||
220 | ||
221 | @menu | |
222 | * Controlling rsync messages:: | |
223 | * Attributes to copy:: | |
224 | * Exit values:: | |
225 | @end menu | |
226 | ||
227 | ||
228 | ||
229 | @node Controlling rsync messages, Attributes to copy, Invoking rsync, Invoking rsync | |
230 | @comment node-name, next, previous, up | |
231 | @section Controlling rsync messages | |
232 | ||
233 | @table @option | |
234 | ||
235 | @item --version | |
236 | @vindex --version | |
237 | Print the rsync version number and compilation information and exit | |
238 | ||
239 | @item --help | |
240 | @vindex --help | |
241 | Print a short help page describing the options available and exit. | |
242 | ||
243 | @item --stats | |
244 | @vindex --stats | |
245 | Print statistics about rsync perfomance. | |
246 | ||
247 | @item -v | |
248 | @itemx --verbose | |
249 | @vindex -v | |
250 | @vindex --verbose | |
251 | This option increases the amount of information you are given during | |
252 | the transfer. By default, rsync works silently. A single -v will | |
253 | give you information about what files are being transferred and a | |
254 | brief summary at the end. Two -v flags will give you information on | |
255 | network connections, files skipped, and slightly more information at | |
256 | the end. More than two -v flags should only be used if you are | |
257 | debugging rsync. | |
258 | @end table | |
259 | ||
260 | ||
261 | @node Attributes to copy, Exit values, Controlling rsync messages, Invoking rsync | |
262 | @comment node-name, next, previous, up | |
263 | @section Attributes to copy | |
264 | ||
265 | @table @option | |
266 | ||
267 | @item -a | |
268 | @vindex -a | |
269 | @vindex --archive | |
270 | @cindex archive mode | |
271 | ||
272 | Preserve as much as possible of the structure and attributes of the | |
273 | origin directory. | |
274 | ||
275 | On many systems, only the superuser can set the ownership of files, | |
276 | and users can only put files into a group to which that user belongs. | |
277 | rsync works within the operating system security model. So on such a | |
278 | system, if you copy a file which you can read but that does not belong | |
279 | to you, the destination file will be owned by you. The only way to | |
280 | change this behaviour is to copy the file as the superuser, or to | |
281 | adjust your operating system's security model if that is possible. | |
282 | ||
283 | @quotation | |
284 | @strong{Please note:} @option{--archive} does not detect files with | |
285 | multiple names. If any exist, they will become multiple identical | |
286 | files on the destination. To make the names all refer to the same | |
287 | file, use @option{--hard-links}. | |
288 | @end quotation | |
289 | ||
290 | @end table | |
291 | ||
292 | ||
293 | ||
294 | @node Exit values, , Attributes to copy, Invoking rsync | |
295 | @comment node-name, next, previous, up | |
296 | @section Exit values | |
297 | ||
298 | @cindex exit code | |
299 | @cindex return code | |
300 | ||
301 | rsync's exit code may be examined by shell scripts to determine | |
302 | whether the transfer completed successfully or not. | |
303 | ||
304 | @table @code | |
305 | ||
306 | @item RERR_SYNTAX 1 | |
307 | Syntax or usage error | |
308 | ||
309 | @item RERR_PROTOCOL 2 | |
310 | Protocol incompatibility | |
311 | ||
312 | @item RERR_FILESELECT 3 | |
313 | Errors selecting input/output files, dirs | |
314 | ||
315 | @item RERR_UNSUPPORTED 4 | |
316 | Requested action not supported: an attempt | |
317 | was made to manipulate 64-bit files on a platform that cannot support | |
318 | them; or an option was speciifed that is supported by the client and | |
319 | not by the server. | |
320 | ||
321 | @item RERR_SOCKETIO 10 | |
322 | Error in socket IO | |
323 | ||
324 | @item RERR_FILEIO 11 | |
325 | Error in file IO | |
326 | ||
327 | @item RERR_STREAMIO 12 | |
328 | Error in rsync protocol data stream | |
329 | ||
330 | @item RERR_MESSAGEIO 13 | |
331 | Errors with program diagnostics | |
332 | ||
333 | @item RERR_IPC 14 | |
334 | Error in @sc{ipc} code | |
335 | ||
336 | @item RERR_SIGNAL 20 | |
337 | Received @sc{sigusr1} or @sc{sigint} | |
338 | ||
339 | @item RERR_WAITCHILD 21 | |
340 | Some error returned by @code{waitpid()} | |
341 | ||
342 | @item RERR_MALLOC 22 | |
343 | Error allocating core memory buffers | |
344 | ||
345 | @item RERR_TIMEOUT 30 | |
346 | Timeout in data send/receive | |
347 | ||
348 | @end table | |
349 | ||
350 | ||
351 | ||
352 | @node Daemon mode, Concept Index, Invoking rsync, Top | |
353 | @chapter Daemon mode | |
354 | ||
355 | @cindex daemon mode | |
356 | @cindex demon mode | |
357 | @cindex @command{rsyncd} | |
358 | @vindex --daemon | |
359 | ||
360 | Configuring rsync as a server is entirely optional. If you just want | |
361 | to copy your own files between local directories or machines, then | |
362 | using rsync over @command{ssh} may well be sufficient. Daemon mode | |
363 | may be useful if you wish to distribute files to a number of machines | |
364 | on a network, or to the public. | |
365 | ||
366 | @vindex --port | |
367 | @cindex port 873 | |
368 | @cindex @sc{tcp} port 873 | |
369 | ||
370 | @sc{Tcp} port 873 is reserved for rsync by the Internet Assigned | |
371 | Numbers Authority (@sc{iana}) and has the service name @code{rsync}. | |
372 | However, rsync may be run on any other port using the @option{--port} | |
373 | option. | |
374 | ||
375 | @menu | |
376 | * Daemon mode security:: | |
377 | @end menu | |
378 | ||
379 | @node Daemon mode security, , Daemon mode, Daemon mode | |
380 | @section Daemon mode security | |
381 | ||
382 | @node Concept Index, Option Index, Daemon mode, Top | |
383 | @comment node-name, next, previous, up | |
384 | @unnumbered Concept Index | |
385 | ||
386 | @printindex cp | |
387 | ||
388 | ||
389 | ||
390 | @node Option Index, , Concept Index, Top | |
391 | @comment node-name, next, previous, up | |
392 | @unnumbered Option Index | |
393 | ||
394 | @printindex vr | |
395 | ||
396 | @bye |