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