Moved the faq's body here (since it's not a plain-text file
[rsync-web.git] / FAQ.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>rsync FAQ</TITLE>
5 </HEAD>
6 <!--#include virtual="header.html" -->
7
8 <H2 align="center">Frequently Asked Questions</H2>
9
10 <table><tr valign=top><td><ul>
11 <li><a href="#1">the transfer fails to finish</a><br>
12 <li><a href="#2">copies every file</a><br>
13 <li><a href="#3">is your shell clean</a><br>
14 <li><a href="#4">memory usage</a><br>
15 <li><a href="#5">out of memory</a><br>
16 <li><a href="#6">rsync through a firewall</a><br>
17 </ul></td><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td><ul>
18 <li><a href="#7">rsync and cron</a><br>
19 <li><a href="#8">rsync: Command not found</a><br>
20 <li><a href="#9">spaces in filenames</a><br>
21 <li><a href="#10">ignore "vanished files" warning</a><br>
22 <li><a href="#11">read-only file system</a><br>
23 </ul></td></tr></table>
24
25 <hr>
26 <h3><a name=1>the transfer fails to finish</a></h3>
27
28 <p>If you get an error like one of these:
29
30 <pre>rsync: error writing 4 unbuffered bytes - exiting: Broken pipe
31 rsync error: error in rsync protocol data stream (code 12) at io.c(463)
32 </pre>
33
34 <p>or
35
36 <pre>rsync: connection unexpectedly closed (24 bytes read so far)
37 rsync error: error in rsync protocol data stream (code 12) at io.c(342)
38 </pre>
39
40 <p>please read the <a href="issues.html">issues and debugging page</a>
41 for details on how you can try to figure out what is going wrong.
42
43 <hr>
44 <h3><a name=2>copies every file</a></h3>
45
46 <p>Some people occasionally report that rsync copies every file when they
47 expect it to copy only a small subset. In most cases the explanation is
48 that you forgot to include the --times (-t) option in the original copy,
49 so rsync is forced to check every file to see if it has changed (because
50 the modified time and size do not match).
51
52 <p>If you think that rsync is erroneously copying every file then look at
53 the stats produced with -v and see if rsync is really sending all the data. 
54 See also the --checksum (-c) option for one way to avoid the extra copying
55 without synchronizing the modified times.
56
57 <hr>
58 <h3><a name=3>is your shell clean</a></h3>
59
60 <p>The "is your shell clean" message and the "protocol mismatch" message
61 are usually caused by having some sort of program in your .cshrc, .profile,
62 .bashrc or equivalent file that writes a message every time you connect
63 using a remote-shell program (such as ssh or rsh).  Data written in this
64 way corrupts the rsync data stream. rsync detects this at startup and
65 produces those error messages.  However, if you are using rsync-daemon
66 syntax (host::path or rsync://) without using a remote-shell program (no
67 --rsh or -e option), there is not remote-shell program involved, and the
68 problem is probably caused by an error on the daemon side (so check the
69 daemon logs).
70
71 <p>A good way to test if your remote-shell connection is clean is to try
72 something like this (use ssh or rsh, as appropriate):
73
74 <blockquote><pre>ssh remotesystem /bin/true &gt; test.dat</pre></blockquote>
75
76 <p>That should create a file called test.dat with nothing in it. If
77 test.dat is not of zero length then your shell is not clean.  Look at the
78 contents of test.dat to see what was sent. Look at all the startup files on
79 remotesystem to try and find the problem.
80
81 <hr>
82 <h3><a name=4>memory usage</a></h3>
83
84 <p>Yes, rsync uses a lot of memory. The majority of the memory is used to
85 hold the list of files being transferred. This takes about 100 bytes per
86 file, so if you are transferring 800,000 files then rsync will consume
87 about 80M of memory. It will be higher if you use -H or --delete.
88
89 <p>To fix this requires a major rewrite of rsync, which my or may not
90 happen.
91
92 <hr>
93 <h3><a name=5>out of memory</a></h3>
94
95 <p>The usual reason for "out of memory" when running rsync is that you are
96 transferring a _very_ large number of files.  The size of the files doesn't
97 matter, only the total number of files.
98
99 <p>As a rule of thumb you should expect rsync to consume about 100 bytes
100 per file in the file list. This happens because rsync builds a internal
101 file list structure containing all the vital details of each file.  rsync
102 needs to hold structure in memory because it is being constantly traversed.
103
104 <p>A future version of rsync could be built with an improved protocol that
105 transfers files in a more incremental fashion, which would require a lot
106 less memory.  Unfortunately, such an rsync does not yet exist.
107
108 <hr>
109 <h3><a name=6>rsync through a firewall</a></h3>
110
111 <p>If you have a setup where there is no way to directly connect two
112 systems for an rsync transfer, there are several ways to get a firewall
113 system to act as an intermediary in the transfer.  You'll find full details
114 on the <a href="firewall.html">firewall methods</a> page.
115
116 <hr>
117 <h3><a name=7>rsync and cron</a></h3>
118
119 <p>On some systems (notably SunOS4) cron supplies what looks like a socket
120 to rsync, so rsync thinks that stdin is a socket. This means that if you
121 start rsync with the --daemon switch from a cron job you end up rsync
122 thinking it has been started from inetd. The fix is simple&mdash;just
123 redirect stdin from /dev/null in your cron job.
124
125 <hr>
126 <h3><a name=8>rsync: Command not found</a></h3>
127
128 <p>This error is produced when the remote shell is unable to locate the rsync
129 binary in your path. There are 3 possible solutions:
130
131 <ol>
132
133 <li>install rsync in a "standard" location that is in your remote path. 
134
135 <li>modify your .cshrc, .bashrc etc on the remote system to include the path
136 that rsync is in
137
138 <li>use the --rsync-path option to explicitly specify the path on the
139 remote system where rsync is installed
140
141 </ol>
142
143 <p>You may echo find the command:
144
145 <blockquote><pre>ssh host 'echo $PATH'</pre></blockquote>
146
147 <p>for determining what your remote path is.
148
149 <hr>
150 <h3><a name=9>spaces in filenames</a></h3>
151
152 <p>Can rsync copy files with spaces in them?
153
154 <p>Short answer: Yes, rsync can handle filenames with spaces.
155
156 <p>Long answer: 
157
158 <p>Rsync handles spaces just like any other unix command line application.
159 Within the code spaces are treated just like any other character so a
160 filename with a space is no different from a filename with any other
161 character in it.
162
163 <p>The problem of spaces is in the argv processing done to interpret the
164 command line.  As with any other unix application you have to escape spaces
165 in some way on the command line or they will be used to separate arguments. 
166
167 <p>It is slightly trickier in rsync (and other remote-copy programs like
168 scp) because rsync sends a command line to the remote system to launch the
169 peer copy of rsync (this assumes that we're not talking about daemon mode,
170 which is not affected by this problem because no remote shell is involved
171 in the reception of the filenames).  The command line is interpreted by the
172 remote shell and thus the spaces need to arrive on the remote system
173 escaped so that the shell doesn't split such filenames into multiple
174 arguments.
175
176 <p>For example:
177
178 <blockquote><pre>rsync -av host:'a long filename' /tmp/</pre></blockquote>
179
180 <p>This is usually a request for rsync to copy 3 files from the remote
181 system, "a", "long", and "filename" (the only exception to this is for a
182 system running a shell that does not word-split arguments in its commands,
183 and that is exceedingly rare).  If you wanted to request a single file with
184 spaces, you need to get some kind of space-quoting characters to the remote
185 shell that is running the remote rsync command.  The following commands
186 should all work:
187
188 <blockquote><pre>rsync -av host:'"a long filename"' /tmp/
189 rsync -av host:'a\ long\ filename' /tmp/
190 rsync -av host:a\\\ long\\\ filename /tmp/</pre></blockquote>
191
192 <p>You might also like to use a '?' in place of a space as long as there
193 are no other matching filenames than the one with spaces (since '?' matches
194 any character):
195
196 <blockquote><pre>rsync -av host:a?long?filename /tmp/</pre></blockquote>
197
198 <p>As long as you know that the remote filenames on the command line
199 are interpreted by the remote shell then it all works fine. 
200
201 <hr>
202 <h3><a name=10>ignore "vanished files" warning</a></h3>
203
204 <p>Some folks would like to ignore the "vanished files" warning, which
205 manifests as an exit-code 24.  The easiest way to do this is to create
206 a shell script wrapper.  For instance, name this something like
207 "rsync-no24":
208
209 <blockquote><pre>#!/bin/sh
210 rsync "$@"
211 e=$?
212 if test $e = 24; then
213     exit 0
214 fi
215 exit $e</pre></blockquote>
216
217 <hr>
218 <h3><a name=11>read-only file system</a></h3>
219
220 <p>If you get "Read-only file system" as an error when sending to a rsync
221 daemon then you probably forgot to set "read only = no" for that module.
222
223 <hr>
224
225
226
227 <!--#include virtual="footer.html" -->