2 @setfilename rsync.info
8 @title rsync - fast, flexible file transfer program
12 @vskip 0pt plus 1filll
13 Copyright @copyright{} 2002 by Martin Pool @email{mbp@@samba.org}
15 Copyright @copyright{} 1996--2001 by Andrew Tridgell @email{tridge@@samba.org}
23 @node Top, Overview, (dir), (dir)
26 rsync is a flexible program for efficiently copying files or directory
29 This manual documents rsync 2.5. It is not yet complete and should be
30 consulted in conjunction with the rsync manual page.
32 Copyright @copyright{} 2002 by Martin Pool @email{mbp@@samba.org}.
34 Copyright @copyright{} 1996--2001 by Andrew Tridgell @email{tridge@@samba.org}.
37 * Overview:: Tutorial section
39 * Daemon mode:: rsync listens for connections on its own socket
47 @node Overview, Invoking rsync, Top, Top
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}.
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.
60 rsync's command line syntax is analogous to @command{cp},
61 @command{rcp} and @command{scp}:
64 rsync [@var{options}] @var{source} @var{destination}
67 Filenames may be prefixed by a hostname to indicate a remote file.
68 (@xref{Local and remote}.)
70 Some of the additional features of rsync are:
74 @item support for copying links, devices, owners, groups and permissions
76 @item exclude and exclude-from options similar to GNU tar
78 @item a CVS exclude mode for ignoring the same files that CVS would ignore
80 @item can use any transparent remote shell, including rsh or ssh
82 @item does not require root privileges
84 @item pipelining of file transfers to minimize latency costs
86 @item support for anonymous or authenticated rsync servers (ideal for
92 * Introductory example:: 60-second guide to rsync
93 * Local and remote:: Local, remote, and server mode
99 @node Introductory example, Local and remote, Overview, Overview
100 @section Introductory example
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}.
106 The most commonly used arguments for rsync are
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}.)
116 Be verbose. Primarily, display the name of each file as it is copied.
119 Compress network traffic, using a modified version of the
120 @command{zlib} library.
123 Display a progress indicator while files are transferred. This should
124 normally be ommitted if rsync is not run on a terminal.
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:
133 rsync -avP ~ foo.example.org:/bkup/mbp/
138 @node Local and remote, Setting up rsync, Introductory example, Overview
139 @comment node-name, next, previous, up
140 @section Local and remote
142 There are six different ways of using rsync. They are:
146 @item for copying local files. This is invoked when neither
147 source nor destination path contains a @code{:} separator
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.
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.
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.
162 @item for copying from the local machine to a remote rsync
163 server. This is invoked when the destination path contains a @code{::}
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
169 @cindex listing files
172 Note that in all cases (other than listing) at least one of the source
173 and destination paths must be local.
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.
179 @cindex network filesystems
180 @cindex remote filesystems
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.
188 @node Setting up rsync, , Local and remote, Overview
189 @comment node-name, next, previous, up
190 @section Setting up rsync
193 See the file @sc{install} that comes with the distribution for installation
196 @cindex @command{rsh}
197 @cindex @command{rsh}, alternatives to
198 @cindex @command{ssh}
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.
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.
208 One common substitute is to use @command{ssh}, which offers a high
211 Note that rsync must be installed on both the source and destination
216 @node Invoking rsync, Daemon mode, Overview, Top
217 @comment node-name, next, previous, up
218 @chapter Invoking rsync
222 * Controlling rsync messages::
223 * Attributes to copy::
229 @node Controlling rsync messages, Attributes to copy, Invoking rsync, Invoking rsync
230 @comment node-name, next, previous, up
231 @section Controlling rsync messages
237 Print the rsync version number and compilation information and exit
241 Print a short help page describing the options available and exit.
245 Print statistics about rsync perfomance.
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
261 @node Attributes to copy, Exit values, Controlling rsync messages, Invoking rsync
262 @comment node-name, next, previous, up
263 @section Attributes to copy
272 Preserve as much as possible of the structure and attributes of the
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.
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}.
294 @node Exit values, , Attributes to copy, Invoking rsync
295 @comment node-name, next, previous, up
301 rsync's exit code may be examined by shell scripts to determine
302 whether the transfer completed successfully or not.
307 Syntax or usage error
309 @item RERR_PROTOCOL 2
310 Protocol incompatibility
312 @item RERR_FILESELECT 3
313 Errors selecting input/output files, dirs
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
321 @item RERR_SOCKETIO 10
327 @item RERR_STREAMIO 12
328 Error in rsync protocol data stream
330 @item RERR_MESSAGEIO 13
331 Errors with program diagnostics
334 Error in @sc{ipc} code
337 Received @sc{sigusr1} or @sc{sigint}
339 @item RERR_WAITCHILD 21
340 Some error returned by @code{waitpid()}
343 Error allocating core memory buffers
345 @item RERR_TIMEOUT 30
346 Timeout in data send/receive
352 @node Daemon mode, Concept Index, Invoking rsync, Top
357 @cindex @command{rsyncd}
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.
368 @cindex @sc{tcp} port 873
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}
376 * Daemon mode security::
379 @node Daemon mode security, , Daemon mode, Daemon mode
380 @section Daemon mode security
382 @node Concept Index, Option Index, Daemon mode, Top
383 @comment node-name, next, previous, up
384 @unnumbered Concept Index
390 @node Option Index, , Concept Index, Top
391 @comment node-name, next, previous, up
392 @unnumbered Option Index