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">rsync recopies the same files</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 <li><a href="#7">rsync and cron</a><br>
  18 </ul></td><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td><ul>
  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 <li><a href="#12">multiplexing overflow 101:7104843</a><br>
  24 <li><a href="#13">inflate (token) returned -5</a><br>
  25 </ul></td></tr></table>
  26
  27 <hr>
  28 <h3><a name=1>the transfer fails to finish</a></h3>
  29
  30 <p>If you get an error like one of these:
  31
  32 <pre>rsync: error writing 4 unbuffered bytes - exiting: Broken pipe
  33 rsync error: error in rsync protocol data stream (code 12) at io.c(463)
  34 </pre>
  35
  36 <p>or
  37
  38 <pre>rsync: connection unexpectedly closed (24 bytes read so far)
  39 rsync error: error in rsync protocol data stream (code 12) at io.c(342)
  40 </pre>
  41
  42 <p>please read the <a href="issues.html">issues and debugging page</a>
  43 for details on how you can try to figure out what is going wrong.
  44
  45 <hr>
  46 <h3><a name=2>rsync recopies the same files</a></h3>
  47
  48 <p>Some people occasionally report that rsync copies too many files when
  49 they expect it to copy only a few. In most cases the explanation is
  50 that you forgot to include the --times (-t) option in the original copy,
  51 so rsync is forced to (efficiently) transfer every file that differs in
  52 its modified time to discover what data (if any) has changed.
  53
  54 <p>Another common cause involves sending files to an Microsoft filesystem:
  55 if the file's modified time is an odd value but the receiving filesystem
  56 can only store even values, then rsync will re-transfer too many files.
  57 You can avoid this by specifying the --modify-window=1 option.
  58
  59 <p>Yet another periodic case can happen when daylight-savings time
  60 changes if your OS+filesystem saves file times in local time instead of
  61 UTC.  For a full explanation of this and some suggestions on how to
  62 avoid them problem, see <a href="daylight-savings.html">this document</a>.
  63
  64 <p>Something else that can trip up rsync is a filesystem changeing the
  65 filename behind the scenes.  This can happen when a filesystem changes
  66 an all-uppercase name into lowercase, or when it decomposes UTF-8 behind
  67 your back.
  68
  69 <blockquote>
  70
  71 <p>An example of the latter can occur with HFS+ on Mac OS X:  if you
  72 copy a directory with a file that has a UTF-8 character sequence in it,
  73 say a 2-byte umlaut-u (\0303\0274), the file will get that character
  74 stored by the filesystem using 3 bytes (\0165\0314\0210), and rsync will
  75 not know that these differing filenames are the same file (it will, in
  76 fact, remove a prior copy of the file if --delete is enabled, and then
  77 recreate it).
  78
  79 <p>You can avoid a charset problem by passing an appropriate --iconv
  80 option to rsync that tells it what character-set the source files are,
  81 and what character-set the destination files get stored in.  For
  82 instance, the above Mac OS X problem would be dealt with by using
  83 --iconv=UTF-8,UTF8-MAC (UTF8-MAC is a pseudo-charset recognized by Mac
  84 OS X iconv in which all characters are decomposed).
  85
  86 </blockquote>
  87
  88 <p>If you think that rsync is copying too many files, look at the
  89 itemized output (-i) to see why rsync is doing the update (e.g. the 't'
  90 flag indicates that the time differs, or all pluses indicates that rsync
  91 thinks the file doesn't exist).  You can also look at the stats produced
  92 with -v and see if rsync is really sending all the data.  See also the
  93 --checksum (-c) option for one way to avoid the extra copying of files
  94 that don't have synchronized modified times (but keep in mind that the
  95 -c option eats lots of disk I/O, and can be rather slow).
  96
  97 <hr>
  98 <h3><a name=3>is your shell clean</a></h3>
  99
 100 <p>The "is your shell clean" message and the "protocol mismatch" message
 101 are usually caused by having some sort of program in your .cshrc, .profile,
 102 .bashrc or equivalent file that writes a message every time you connect
 103 using a remote-shell program (such as ssh or rsh).  Data written in this
 104 way corrupts the rsync data stream. rsync detects this at startup and
 105 produces those error messages.  However, if you are using rsync-daemon
 106 syntax (host::path or rsync://) without using a remote-shell program (no
 107 --rsh or -e option), there is not remote-shell program involved, and the
 108 problem is probably caused by an error on the daemon side (so check the
 109 daemon logs).
 110
 111 <p>A good way to test if your remote-shell connection is clean is to try
 112 something like this (use ssh or rsh, as appropriate):
 113
 114 <blockquote><pre>ssh remotesystem /bin/true &gt; test.dat</pre></blockquote>
 115
 116 <p>That should create a file called test.dat with nothing in it. If
 117 test.dat is not of zero length then your shell is not clean.  Look at the
 118 contents of test.dat to see what was sent. Look at all the startup files on
 119 remotesystem to try and find the problem.
 120
 121 <hr>
 122 <h3><a name=4>memory usage</a></h3>
 123
 124 <p>Rsync versions before 3.0.0 always build the entire list of files to be
 125 transferred at the beginning and hold it in memory for the entire run.  Rsync
 126 needs about 100 bytes to store all the relevant information for one file,
 127 so (for example) a run with 800,000 files would consume about 80M of
 128 memory.  -H and --delete increase the memory usage further.
 129
 130 <p>Version 3.0.0 slightly reduced the memory used per file by not storing fields
 131 not needed for a particular file.  It also introduced an incremental recursion
 132 mode that builds the file list in chunks and holds each chunk in memory only as
 133 long as it is needed.  This mode dramatically reduces memory usage, but it
 134 only works provided that both sides are 3.0.0 or newer and certain options that
 135 rsync currently can't handle in this mode are not being used.
 136
 137 <hr>
 138 <h3><a name=5>out of memory</a></h3>
 139
 140 <p>The usual reason for "out of memory" when running rsync is that you are
 141 transferring a _very_ large number of files.  The size of the files doesn't
 142 matter, only the total number of files.  If memory is a problem, first try to
 143 use the incremental recursion mode: upgrade both sides to rsync 3.0.0 or
 144 newer and avoid options that disable incremental recursion (e.g., use
 145 <tt>--delete-delay</tt> instead of <tt>--delete-after</tt>).  If this is not
 146 possible, you can break the rsync run into smaller chunks operating on
 147 individual subdirectories using <tt>--relative</tt> and/or exclude rules.
 148
 149 <hr>
 150 <h3><a name=6>rsync through a firewall</a></h3>
 151
 152 <p>If you have a setup where there is no way to directly connect two
 153 systems for an rsync transfer, there are several ways to get a firewall
 154 system to act as an intermediary in the transfer.  You'll find full details
 155 on the <a href="firewall.html">firewall methods</a> page.
 156
 157 <hr>
 158 <h3><a name=7>rsync and cron</a></h3>
 159
 160 <p>On some systems (notably SunOS4) cron supplies what looks like a socket
 161 to rsync, so rsync thinks that stdin is a socket. This means that if you
 162 start rsync with the --daemon switch from a cron job you end up rsync
 163 thinking it has been started from inetd. The fix is simple&mdash;just
 164 redirect stdin from /dev/null in your cron job.
 165
 166 <hr>
 167 <h3><a name=8>rsync: Command not found</a></h3>
 168
 169 <p>This error is produced when the remote shell is unable to locate the rsync
 170 binary in your path. There are 3 possible solutions:
 171
 172 <ol>
 173
 174 <li>install rsync in a "standard" location that is in your remote path.
 175
 176 <li>modify your .cshrc, .bashrc etc on the remote system to include the path
 177 that rsync is in
 178
 179 <li>use the --rsync-path option to explicitly specify the path on the
 180 remote system where rsync is installed
 181
 182 </ol>
 183
 184 <p>You may echo find the command:
 185
 186 <blockquote><pre>ssh host 'echo $PATH'</pre></blockquote>
 187
 188 <p>for determining what your remote path is.
 189
 190 <hr>
 191 <h3><a name=9>spaces in filenames</a></h3>
 192
 193 <p>Can rsync copy files with spaces in them?
 194
 195 <p>Short answer: Yes, rsync can handle filenames with spaces.
 196
 197 <p>Long answer:
 198
 199 <p>Rsync handles spaces just like any other unix command line application.
 200 Within the code spaces are treated just like any other character so a
 201 filename with a space is no different from a filename with any other
 202 character in it.
 203
 204 <p>The problem of spaces is in the argv processing done to interpret the
 205 command line.  As with any other unix application you have to escape spaces
 206 in some way on the command line or they will be used to separate arguments.
 207
 208 <p>It is slightly trickier in rsync (and other remote-copy programs like
 209 scp) because rsync sends a command line to the remote system to launch the
 210 peer copy of rsync (this assumes that we're not talking about daemon mode,
 211 which is not affected by this problem because no remote shell is involved
 212 in the reception of the filenames).  The command line is interpreted by the
 213 remote shell and thus the spaces need to arrive on the remote system
 214 escaped so that the shell doesn't split such filenames into multiple
 215 arguments.
 216
 217 <p>For example:
 218
 219 <blockquote><pre>rsync -av host:'a long filename' /tmp/</pre></blockquote>
 220
 221 <p>This is usually a request for rsync to copy 3 files from the remote
 222 system, "a", "long", and "filename" (the only exception to this is for a
 223 system running a shell that does not word-split arguments in its commands,
 224 and that is exceedingly rare).  If you wanted to request a single file with
 225 spaces, you need to get some kind of space-quoting characters to the remote
 226 shell that is running the remote rsync command.  The following commands
 227 should all work:
 228
 229 <blockquote><pre>rsync -av host:'"a long filename"' /tmp/
 230 rsync -av host:'a\ long\ filename' /tmp/
 231 rsync -av host:a\\\ long\\\ filename /tmp/</pre></blockquote>
 232
 233 <p>You might also like to use a '?' in place of a space as long as there
 234 are no other matching filenames than the one with spaces (since '?' matches
 235 any character):
 236
 237 <blockquote><pre>rsync -av host:a?long?filename /tmp/</pre></blockquote>
 238
 239 <p>As long as you know that the remote filenames on the command line
 240 are interpreted by the remote shell then it all works fine.
 241
 242 <hr>
 243 <h3><a name=10>ignore "vanished files" warning</a></h3>
 244
 245 <p>Some folks would like to ignore the "vanished files" warning, which
 246 manifests as an exit-code 24.  The easiest way to do this is to create
 247 a shell script wrapper.  For instance, name this something like
 248 "rsync-no24":
 249
 250 <blockquote><pre>#!/bin/sh
 251 rsync "$@"
 252 e=$?
 253 if test $e = 24; then
 254     exit 0
 255 fi
 256 exit $e</pre></blockquote>
 257
 258 <hr>
 259 <h3><a name=11>read-only file system</a></h3>
 260
 261 <p>If you get "Read-only file system" as an error when sending to a rsync
 262 daemon then you probably forgot to set "read only = no" for that module.
 263
 264 <hr>
 265 <h3><a name=12>multiplexing overflow 101:7104843</a></h3>
 266
 267 <p>This mysterious error, or the similar "invalid message 101:7104843", can
 268 happen if one of the rsync processes is killed for some reason and a message
 269 beginning with the four characters "Kill" gets inserted into the protocol
 270 stream as a result.  To solve the problem, you'll need to figure out why rsync
 271 is being killed.
 272 See <a href="https://bugzilla.samba.org/show_bug.cgi?id=5727">this bug report</a>.
 273
 274 <hr>
 275 <h3><a name=13>inflate (token) returned -5</a></h3>
 276
 277 This error means that rsync failed to handle an expected error from the
 278 compression code for a file that happened to be transferred with a block size
 279 of 32816 bytes.  You can avoid this issue for the affected file by transferring
 280 it with a manually-set block size (e.g. --block-size=33000), or by upgrading
 281 the receiving side to rsync 3.0.7.
 282
 283 <hr>
 284
 285 <!--#include virtual="footer.html" -->