Ensure that the generator gets notified about an I/O error for the dir
[rsync.git] / doc / rsync.sgml
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2 <book id="rsync">
3   <bookinfo>
4     <title>rsync</title>
5     <copyright>
6       <year>1996 -- 2002</year>
7       <holder>Martin Pool</holder>
8       <holder>Andrew Tridgell</holder>
9     </copyright>
10     <author>
11       <firstname>Martin</firstname>
12       <surname>Pool</surname>
13     </author>
14   </bookinfo>
15
16   <chapter>
17     <title>Introduction</title>
18
19     <para>rsync is a flexible program for efficiently copying files or
20       directory trees.
21
22     <para>rsync has many options to select which files will be copied
23       and how they are to be transferred.  It may be used as an
24       alternative to ftp, http, scp or rcp.
25
26     <para>The rsync remote-update protocol allows rsync to transfer just
27       the differences between two sets of files across the network link,
28       using an efficient checksum-search algorithm described in the
29       technical report that accompanies this package.</para>
30
31     <para>Some of the additional features of rsync are:</para>
32
33     <itemizedlist>
34       
35       <listitem>
36         <para>support for copying links, devices, owners, groups and
37           permissions
38         </para>
39       </listitem>
40       
41       <listitem>
42         <para>
43           exclude and exclude-from options similar to GNU tar
44         </para>
45       </listitem>
46
47       <listitem>
48         <para>
49           a CVS exclude mode for ignoring the same files that CVS would ignore
50       </listitem>
51
52       <listitem>
53         <para>
54           can use any transparent remote shell, including rsh or ssh
55       </listitem>
56
57       <listitem>
58         <para>
59           does not require root privileges
60       </listitem>
61
62       <listitem>
63         <para>
64           pipelining of file transfers to minimize latency costs
65       </listitem>
66                 
67       <listitem>
68         <para>
69           support for anonymous or authenticated rsync servers (ideal for
70           mirroring)
71         </para>
72       </listitem>
73     </itemizedlist>
74   </chapter>
75
76
77
78   <chapter>
79     <title>Using rsync</title>
80     <section>
81       <title>
82         Introductory example
83       </title>
84       
85       <para>
86         Probably the most common case of rsync usage is to copy files
87         to or from a remote machine using
88         <application>ssh</application> as a network transport.  In
89         this situation rsync is a good alternative to
90         <application>scp</application>.
91       </para>
92
93       <para>
94         The most commonly used arguments for rsync are
95       </para>
96
97       <variablelist>
98         <varlistentry>
99           <term><option>-v</option></term>
100           <listitem>
101             <para>Be verbose.  Primarily, display the name of each file as it is copied.</para>
102           </listitem>
103         </varlistentry>
104
105
106         <varlistentry>
107           <term><option>-a</option></term>
108           <listitem>
109             <para>
110               Reproduce the structure and attributes of the origin files as exactly
111               as possible: this includes copying subdirectories, symlinks, special
112               files, ownership and permissions.  (@xref{Attributes to
113               copy}.)
114             </para>
115           </listitem>
116         </varlistentry>
117       </variablelist>
118
119
120         
121       <para><option>-v </option>
122       
123       <para><option>-z</option>
124         Compress network traffic, using a modified version of the
125         @command{zlib} library.</para>
126       
127       <para><option>-P</option>
128         Display a progress indicator while files are transferred.  This should
129         normally be ommitted if rsync is not run on a terminal.
130       </para>
131     </section>
132
133
134
135
136     <section>
137       <title>Local and remote</title>
138       
139       <para>There are six different ways of using rsync. They
140       are:</para>
141
142       
143
144       <!-- one of (CALLOUTLIST GLOSSLIST ITEMIZEDLIST ORDEREDLIST SEGMENTEDLIST SIMPLELIST VARIABLELIST CAUTION IMPORTANT NOTE TIP WARNING LITERALLAYOUT PROGRAMLISTING PROGRAMLISTINGCO SCREEN SCREENCO SCREENSHOT SYNOPSIS CMDSYNOPSIS FUNCSYNOPSIS CLASSSYNOPSIS FIELDSYNOPSIS CONSTRUCTORSYNOPSIS DESTRUCTORSYNOPSIS METHODSYNOPSIS FORMALPARA PARA SIMPARA ADDRESS BLOCKQUOTE GRAPHIC GRAPHICCO MEDIAOBJECT MEDIAOBJECTCO INFORMALEQUATION INFORMALEXAMPLE INFORMALFIGURE INFORMALTABLE EQUATION EXAMPLE FIGURE TABLE MSGSET PROCEDURE SIDEBAR QANDASET ANCHOR BRIDGEHEAD REMARK HIGHLIGHTS ABSTRACT AUTHORBLURB EPIGRAPH INDEXTERM REFENTRY SECTION) -->
145       <orderedlist>
146         <listitem>
147           <para>
148             for copying local files. This is invoked when neither
149             source nor destination path contains a @code{:} separator
150
151         <listitem>
152           <para>
153             for copying from the local machine to a remote machine using
154             a remote shell program as the transport (such as rsh or
155             ssh). This is invoked when the destination path contains a
156             single @code{:} separator.
157
158         <listitem>
159           <para>
160             for copying from a remote machine to the local machine
161             using a remote shell program. This is invoked when the source
162             contains a @code{:} separator.
163
164         <listitem>
165           <para>
166             for copying from a remote rsync server to the local
167             machine. This is invoked when the source path contains a @code{::}
168             separator or a @code{rsync://} URL.
169
170         <listitem>
171           <para>
172             for copying from the local machine to a remote rsync
173             server. This is invoked when the destination path contains a @code{::}
174             separator.
175
176         <listitem>
177           <para>
178             for listing files on a remote machine. This is done the
179             same way as rsync transfers except that you leave off the
180             local destination.  
181
182         </listitem>
183       </orderedlist>
184           <para>
185 Note that in all cases (other than listing) at least one of the source
186 and destination paths must be local.
187
188           <para>
189 Any one invocation of rsync makes a copy in a single direction.  rsync
190 currently has no equivalent of @command{ftp}'s interactive mode.
191
192 @cindex @sc{nfs}
193 @cindex network filesystems
194 @cindex remote filesystems
195
196           <para>
197 rsync's network protocol is generally faster at copying files than
198 network filesystems such as @sc{nfs} or @sc{cifs}.  It is better to
199 run rsync on the file server either as a daemon or over ssh than
200 running rsync giving the network directory.
201       </para>
202     </section>
203   </chapter>
204
205
206
207   <chapter>
208     <title>Frequently asked questions</title>
209
210     
211     <!-- one of (CALLOUTLIST GLOSSLIST ITEMIZEDLIST ORDEREDLIST SEGMENTEDLIST SIMPLELIST VARIABLELIST CAUTION IMPORTANT NOTE TIP WARNING LITERALLAYOUT PROGRAMLISTING PROGRAMLISTINGCO SCREEN SCREENCO SCREENSHOT SYNOPSIS CMDSYNOPSIS FUNCSYNOPSIS CLASSSYNOPSIS FIELDSYNOPSIS CONSTRUCTORSYNOPSIS DESTRUCTORSYNOPSIS METHODSYNOPSIS FORMALPARA PARA SIMPARA ADDRESS BLOCKQUOTE GRAPHIC GRAPHICCO MEDIAOBJECT MEDIAOBJECTCO INFORMALEQUATION INFORMALEXAMPLE INFORMALFIGURE INFORMALTABLE EQUATION EXAMPLE FIGURE TABLE MSGSET PROCEDURE SIDEBAR QANDASET ANCHOR BRIDGEHEAD REMARK HIGHLIGHTS ABSTRACT AUTHORBLURB EPIGRAPH INDEXTERM SECTION SIMPLESECT REFENTRY SECT1) -->
212     <qandaset>
213       <!-- one of (QANDADIV QANDAENTRY) -->
214
215       <qandaentry>
216         <question>
217           <!-- one of (CALLOUTLIST GLOSSLIST ITEMIZEDLIST ORDEREDLIST
218           SEGMENTEDLIST SIMPLELIST VARIABLELIST CAUTION IMPORTANT NOTE
219           TIP WARNING LITERALLAYOUT PROGRAMLISTING PROGRAMLISTINGCO
220           SCREEN SCREENCO SCREENSHOT SYNOPSIS CMDSYNOPSIS FUNCSYNOPSIS
221           CLASSSYNOPSIS FIELDSYNOPSIS CONSTRUCTORSYNOPSIS
222           DESTRUCTORSYNOPSIS METHODSYNOPSIS FORMALPARA PARA SIMPARA
223           ADDRESS BLOCKQUOTE GRAPHIC GRAPHICCO MEDIAOBJECT
224           MEDIAOBJECTCO INFORMALEQUATION INFORMALEXAMPLE
225           INFORMALFIGURE INFORMALTABLE EQUATION EXAMPLE FIGURE TABLE
226           PROCEDURE ANCHOR BRIDGEHEAD REMARK HIGHLIGHTS INDEXTERM) -->
227           <para>Are there mailing lists for rsync?
228         </question>
229
230         <answer>
231           <para>Yes, and you can subscribe and unsubscribe through a
232           web interface at
233             <ulink
234               url="http://lists.samba.org/">http://lists.samba.org/</ulink>
235           </para>
236
237           <para>
238             If you are having trouble with the mailing list, please
239             send mail to the administrator
240             
241             <email>rsync-admin@lists.samba.org</email>
242
243             not to the list itself.
244           </para>
245
246           <para>
247             The mailing list archives are searchable.  Use 
248             <ulink url="http://google.com/">Google</ulink> and prepend
249             the search with <userinput>site:lists.samba.org
250             rsync</userinput>, plus relevant keywords.
251           </para>
252         </answer>
253       </qandaentry>
254
255
256       <qandaentry>
257         <question>
258           <para>
259             Why is rsync so much bigger when I build it with
260             <command>gcc</command>?
261           </para>
262         </question>
263         <answer>
264           <para>
265             On gcc, rsync builds by default with debug symbols
266             included.  If you strip both executables, they should end
267             up about the same size.  (Use <command>make
268             install-strip</command>.)
269           </para>
270         </answer>
271       </qandaentry>
272
273       
274       <qandaentry>
275         <question>
276           <para>Is rsync useful for a single large file like an ISO image?</para>
277         </question>
278         <answer>
279           <para>
280             Yes, but note the following:
281
282           <para>
283    Background: A common use of rsync is to update a file (or set of files) in one location from a more
284    correct or up-to-date copy in another location, taking advantage of portions of the files that are
285    identical to speed up the process. (Note that rsync will transfer a file in its entirety if no copy
286    exists at the destination.)
287
288           <para>
289    (This discussion is written in terms of updating a local copy of a file from a correct file in a
290    remote location, although rsync can work in either direction.)
291
292           <para>
293    The file to be updated (the local file) must be in a destination directory that has enough space for
294    two copies of the file. (In addition, keep an extra copy of the file to be updated in a different
295    location for safety -- see the discussion (below) about rsync's behavior when the rsync process is
296    interrupted before completion.)
297
298           <para>
299    The local file must have the same name as the remote file being sync'd to (I think?). If you are
300    trying to upgrade an iso from, for example, beta1 to beta2, rename the local file to the same name
301    as the beta2 file. *(This is a useful thing to do -- only the changed portions will be
302    transmitted.)*
303
304           <para>
305    The extra copy of the local file kept in a different location is because of rsync's behavior if
306    interrupted before completion:
307
308           <para>
309    * If you specify the --partial option and rsync is interrupted, rsync will save the partially
310    rsync'd file and throw away the original local copy. (The partially rsync'd file is correct but
311    truncated.) If rsync is restarted, it will not have a local copy of the file to check for duplicate
312    blocks beyond the section of the file that has already been rsync'd, thus the remainder of the rsync
313    process will be a "pure transfer" of the file rather than taking advantage of the rsync algorithm.
314
315           <para>
316    * If you don't specify the --partial option and rsync is interrupted, rsync will throw away the
317    partially rsync'd file, and, when rsync is restarted starts the rsync process over from the
318    beginning.
319
320           <para>
321    Which of these is most desirable depends on the degree of commonality between the local and remote
322    copies of the file *and how much progress was made before the interruption*.
323
324           <para>
325    The ideal approach after an interruption would be to create a new file by taking the original file
326    and deleting a portion equal in size to the portion already rsync'd and then appending *the
327    remaining* portion to the portion of the file that has already been rsync'd. (There has been some
328    discussion about creating an option to do this automatically.)
329
330    The --compare-dest option is useful when transferring multiple files, but is of no benefit in
331    transferring a single file. (AFAIK)
332
333    *Other potentially useful information can be found at:
334    -[3]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFile
335
336    This answer, formatted with "real" bullets, can be found at:
337    -[4]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFileFAQ*
338
339           </para>
340         </answer>
341       </qandaentry>
342     </qandaset>
343   </chapter>
344
345
346   <appendix>
347     <title>Other Resources</title>
348     
349     <para><ulink url="http://www.ccp14.ac.uk/ccp14admin/rsync/"></ulink></para>
350   </appendix>
351 </book>