Point folks reading the first answer to the rsync-debug script mentioned
[rsync-web.git] / faqbody.html
1 <table><tr><td>
2 <a href="#1">HP compile</a><br>
3 <a href="#2">Read-only file system</a><br>
4 <a href="#3">copies every file</a><br>
5 <a href="#4">is your shell clean</a><br>
6 <a href="#5">memory usage</a><br>
7 <a href="#6">out of memory</a><br>
8 </td><td><ol>
9 <a href="#7">rsync 2.4.3 with rsh</a><br>
10 <a href="#8">rsync and cron</a><br>
11 <a href="#9">rsync: Command not found</a><br>
12 <a href="#10">spaces in filenames</a><br>
13 <a href="#11">stderr & stdout</a><br>
14 <a href="#12">subscribe</a><br>
15 </td></tr></table>
16 <h3><a name=1>HP compile</a></h3>
17 <pre><small>
18 For HPUX apparently you need to add the option -Ae to the CFLAGS. Edit
19 the Makefile and change CFLAGS to:
20
21  CFLAGS=-Ae -O
22 </small></pre><hr>
23 <h3><a name=2>Read-only file system</a></h3>
24 <pre><small>
25 if you get "Read-only file system" as an error when sending to a rsync
26 server then you probably forgot to set "read only = no" for that
27 module.
28 </small></pre><hr>
29 <h3><a name=3>copies every file</a></h3>
30 <pre><small>
31 Some people occasionally report that rsync copies every file when they 
32 expect it to copy only a small subset. In most cases the explanation
33 is that rsync is not in fact copying every file it is just trying
34 to update file permissions or ownership and this is failing for some
35 reason. rsync lists files with the -v option if it makes any change
36 to the file, including minor changes such as group changes.
37
38 If you think that rsync is erroneously copying every file then look
39 at the stats produced with -v and see if rsync is really sending all
40 the data. 
41
42
43 </small></pre><hr>
44 <h3><a name=4>is your shell clean</a></h3>
45 <pre><small>
46 The "is your shell clean" message and the "protocol mismatch"
47 message are usually caused by having some sort of program
48 in your .cshrc, .profile, .bashrc or equivalent file that
49 writes a message every time you connect. Data written
50 in this way corrupts the rsync data stream. rsync detects this
51 at startup and produces those error messages.
52
53 A good way to test this is something like:
54
55         rsh remotemachine /bin/true &gt; test.dat
56
57 you should get a file called test.dat created of 0 length. If
58 test.dat is not of zero length then your shell is not clean.
59 Look at the contents of test.dat to see what was sent. Look
60 at all the startup files on remotemachine to try and find the
61 problem.
62
63
64 </small></pre><hr>
65 <h3><a name=5>memory usage</a></h3>
66 <pre><small>
67 yes, rsync uses a lot of memory. The majority of the memory is used to
68 hole the list of files being transferred. This takes about 100 bytes
69 per file, so if you are transferring 800,000 files then rsync will consume
70 about 80M of memory. It will be higher if you use -H or --delete.
71
72 To fix this requires a major rewrite of rsync. I do plan on doing that, but
73 I don't know when I'll get to it.
74 </small></pre><hr>
75 <h3><a name=6>out of memory</a></h3>
76 <pre><small>
77 The usual reason for "out of memory" when running rsync is that you
78 are transferring a _very_ large number of files.  The size of the
79 files doesn't matter, only the total number of files.
80
81 As a rule of thumb you should expect rsync to consume about 100 bytes per
82 file in the file list. This happens because rsync builds a internal
83 file list structure containing all the vital details of each file. 
84 rsync needs to hold structure in memory because it is being constantly
85 traversed.
86
87 A future version of rsync could be built with an improved protocol that
88 transfers files in a more incremental fashion, which would require a lot
89 less memory.  Unfortunately, such an rsync does not yet exist.
90
91
92 </small></pre><hr>
93 <h3><a name=7>rsync 2.4.3 with rsh</a></h3>
94 <pre><small>
95 rsync 2.4.3 has a problem with some versions of rsh. The versions of rsh (such as the
96 one on Solaris) that don't handle non-blocking IO will cause all sorts of errors,
97 including "unexpected tag" "multiplexing overflow" etc.
98
99 The fix is to either use an earlier version of rsync or use ssh instead of rsh
100 or wait for rsync 2.4.4
101
102 </small></pre><hr>
103 <h3><a name=8>rsync and cron</a></h3>
104 <pre><small>
105 On some systems (notably SunOS4) cron supplies what looks like a
106 socket to rsync, so rsync thinks that stdin is a socket. This means
107 that if you start rsync with the --daemon switch from a cron job you
108 end up rsync thiking it has been started from inetd. The fix is simple
109 - just redirect stdin from /dev/null in your cron job.
110
111 </small></pre><hr>
112 <h3><a name=9>rsync: Command not found</a></h3>
113 <pre><small>
114 &gt; rsync: Command not found
115
116 This error is produced when the remote shell is unable to locate the rsync
117 binary in your path. There are 3 possible solutions:
118
119 1) install rsync in a "standard" location that is in your remote path. 
120
121 2) modify your .cshrc, .bashrc etc on the remote machine to include the path
122 that rsync is in
123
124 3) use the --rsync-path option to explicitly specify the path on the
125 remote machine where rsync is installed
126
127 You may echo find the command:
128
129         rsh samba 'echo $PATH'
130
131 for determining what your remote path is.
132
133
134 </small></pre><hr>
135 <h3><a name=10>spaces in filenames</a></h3>
136 <pre><small>
137 Jim wrote:
138 &gt; This seems to imply rsync can't copy files with names containing
139 &gt; spaces.  A couple quick greps through the man page suggests that
140 &gt; this limitation isn't mentioned.
141
142 Short answer: rsync can handle filenames with spaces
143
144 Long answer: 
145
146 rsync handles spaces just like any other unix command line application.
147 Within the code spaces are treated just like any other character so
148 a filename with a space is no different from a filename with any
149 other character in it.
150
151 The problem of spaces is in the argv processing done to interpret the
152 command line. As with any other unix application you have to escape
153 spaces in some way on the command line or they will be used to
154 separate arguments. 
155
156 It is slightly trickier in rsync because rsync sends a command line
157 to the remote system to launch the peer copy of rsync. The command
158 line is interpreted by the remote shell and thus the spaces need
159 to arrive on the remote system escaped so that the shell doesn't
160 split such filenames into multiple arguments.
161
162 For example:
163
164         rsync -av fjall:'a long filename' /tmp/
165
166 won't work because the remote shell gets an unquoted filename. Instead
167 you have to use:
168
169         rsync -av fjall:'"a long filename"' /tmp/
170
171 or a similar construct (there are lots of varients that work).
172
173 As long as you know that the remote filenames on the command line
174 are interpreted by the remote shell then it all works fine. 
175
176 I should probably provide the above examples in the docs :-)
177
178 Cheers, Andrew
179
180
181 </small></pre><hr>
182 <h3><a name=11>stderr & stdout</a></h3>
183 <small>
184 &gt; Why does rsync produce some things on stdout and some on stderr?
185
186 <p>All messages which originate from the remote computer are sent to stderr.
187 All informational messages from the local computer are sent to stdout.
188 All error messages from the local computer are sent to stderr.
189
190 <p>
191 There is a reason to this system, and it would be quite difficult to change.
192 The reason is that rsync uses a remote shell for execution. The remote
193 shell provides stderr/stdout. The stdout stream is used for the rsync 
194 protocol. Mixing error messages into this stdout stream would involve
195 lots of extra overhead and complexity in the protocol because each message
196 would need to be escaped, which means non-messages would need to be encoded
197 in some way. Instead rsync always sends remote messages to stderr. This means
198 they appear on stderr at the local computer. rsync can't intercept them.
199
200 <p>
201 If you have a problem with scripts or cron jobs that produce stderr then I
202 suggest you use your shell to redirect stderr and stdout. For example you
203 could do a cron line like this:
204
205 <p>
206 <pre>
207 0 0 * * * /usr/local/bin/rsync -avz /foobar /foo &gt; logfile 2&gt;&1 
208 </pre>
209
210 <p>
211 this would send both stderr and stdout to "logfile". The magic bit is the
212 "2&gt;&1" which says to redirect stderr to to the same descriptor to which
213 stdout is currently directed.
214
215
216 </small><hr>