issues.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>rsync current issues</TITLE>
   5 </HEAD>
   6 <!--#include virtual="header.html" -->
   7
   8 <H2 align="center">current issues and debugging</H2>
   9
  10 <ol>
  11
  12 <li><p><b>Q:</b>
  13
  14 Rsync appears hung -- what should I do?
  15
  16 <p><b>A:</b>
  17
  18 When experiencing a hang or freeze <b>please</b> gather the following
  19 information before killing the rsync process:
  20
  21 <ul>
  22
  23 <li> The state of the send/receive queues shown with netstat on the two ends.
  24
  25 <li> The system call that each of the 3 processes is stuck in (use truss on
  26 solaris, strace on Linux, etc.).
  27
  28 </ul>
  29
  30 <p>See the "rsync-debug" script below for an example of how to grab strace
  31 information from the remote rsync process(es).  If you need help, send email to
  32 the mailing list.
  33
  34 <li><p><b>Q:</b>
  35
  36 Why does my chrooted rsync daemon crash when doing an LDAP lookup for a user or
  37 group?
  38
  39 <p><b>A:</b>
  40
  41 There is a bug in some LDAP libraries (e.g. Fedora Core 3) where it crashes
  42 when someone looks up a name from inside a chrooted process (one that does not
  43 contain copies of the libraries to perform the lookup).  This is a bug that the
  44 LDAP libraries will need to fix, and is out of rsync's hands.  You can work
  45 around the problem by using the --numeric-ids option, turning chroot off, or
  46 getting rid of LDAP lookups.
  47
  48 <li><p><b>Q:</b>
  49
  50 Why does my transfer die with something like the following error?
  51
  52 <pre>rsync: error writing 4 unbuffered bytes - exiting: Broken pipe
  53 rsync error: error in rsync protocol data stream (code 12) at io.c(463)
  54 </pre>
  55
  56 <p>or
  57
  58 <pre>rsync: connection unexpectedly closed (24 bytes read so far)
  59 rsync error: error in rsync protocol data stream (code 12) at io.c(342)
  60 </pre>
  61
  62 <p><b>A:</b>
  63
  64 This error tells you that the local rsync was trying to talk to the remote
  65 rsync, but the connection to that rsync is now gone.  The thing you must
  66 figure out is <b>why</b>, and that can involve some investigative work.
  67
  68 <p>If the remote rsync is a daemon, your first step should be to look at
  69 the daemon's log file to see if it logged an error explaining why it
  70 aborted the transfer.
  71
  72 <p>Beginning with version 2.6.3, rsync now does a better job of retreiving
  73 the error from the remote
  74 process than older versions of rsync, so you may wish to try upgrading and
  75 see if you now get sent the error message from the remote rsync.
  76
  77 <p>There are several common causes for a remote rsync process going away:
  78
  79 <ul>
  80
  81 <li>The destination disk is full (remember that you need at least the
  82 size of the largest file that needs to be updated available in free
  83 disk space for the transfer to succeed).
  84
  85 <li>An idle connection caused a router or remote-shell server to close
  86 the connection.
  87
  88 <li>A network error caused the connection to be dropped.
  89
  90 <li>The remote rsync executable wasn't found.
  91
  92 <li>Your remote-shell setup isn't working right or isn't "clean"
  93 (i.e. it is sending spurious text to rsync).
  94
  95 </ul>
  96
  97 <p>If you think the problem might be an idle connection getting closed,
  98 you might be able to work around the problem by using a --timeout option
  99 (newer rsyncs send keep-alive messages during lulls).  You can also
 100 configure ssh to send keep-alive messages when using Protocol 2 (look for
 101 KeepAlive, ServerAliveInterval, ClientAliveInterval, ServerAliveCountMax,
 102 and ClientAliveCountMax).  You can also avoid some lulls by switching
 103 from --delete (aka --delete-before) to --del (aka --delete-during).
 104
 105 <p>If you can't figure out why the failure happened, there are steps
 106 you can take to debug the situation.  One way is to create a shell
 107 script on the remote system such as
 108 <a href="rsync-debug">this one named "rsync-debug"</a>.
 109 You would use the script like this:
 110
 111 <pre>rsync -av --rsync-path=/some/path/rsync-debug HOST:SOURCE DEST
 112 rsync -av --rsync-path=/some/path/rsync-debug SOURCE HOST:DEST
 113 </pre>
 114
 115 <p>This script enables core dumps and also logs all the OS system calls
 116 that lead up to the failure to a file in the /tmp dir.  You can use the
 117 resulting files to help figure out why the remote rsync failed.
 118
 119 <p>If you are rsyncing directly to an rsync daemon (without using a
 120 remote-shell transport), the above script won't have
 121 any effect.  Instead, halt the current daemon and run a debug version
 122 with core-dumps enabled and (if desired) using a
 123 system-call tracing utility such as <i>strace</i>, <i>truss</i>, or
 124 <i>tusc</i>.  For strace, you would do it like this (the -f option
 125 tells strace to follow the child processes too):
 126
 127 <pre>ulimit -c unlimited
 128 strace -f rsync --daemon --no-detach 2&gt;/tmp/rsync-$$.out
 129 </pre>
 130
 131 <p>Then, use a separate window to actually run the failing transfer, after
 132 which you can kill the debug rsync daemon (pressing Ctrl-C should do it).
 133
 134 <p>If you are using rsync under inetd, I'd suggest temporarily disabling
 135 that and using the above daemon approach to debug what is going on.
 136
 137 <li><p><b>Q:</b>
 138
 139 Why does my connection to an rsync daemon (using the "::" syntax)
 140 fail immediately with an error like the following?
 141
 142 <pre>rsync: connection unexpectedly closed (24 bytes read so far)
 143 rsync error: error in rsync protocol data stream (code 12) at io.c(342)
 144 </pre>
 145
 146 <p><b>A:</b>
 147
 148 Older rsync daemons (before 2.6.3) were unable to return errors that were
 149 generated during the option-parsing phase of the transfer.  Look in the
 150 logfile on the server to see if an error was reported, such as a "refused"
 151 option, an option that the server rsync doesn't support (e.g.  perhaps
 152 links are not supported by the server), or some other failure (such as
 153 trying to send data to a read-only module).  Upgrading the version of rsync
 154 that is running as a daemon to at least 2.6.3 will allow these errors to
 155 get returned to all rsync clients, old or new alike.
 156
 157 <li><p><b>Q:</b>
 158
 159 Why doesn't --dry-run (-n) show all the changed directories?
 160
 161 <p><b>A:</b>
 162
 163 This was a bug in versions prior to 2.6.4.  Upgrade both rsync versions (or at
 164 least the receiving side).
 165
 166 <li><p><b>Q:</b>
 167
 168 Aren't there more issues than this?
 169
 170 <p><b>A:</b>
 171
 172 Yes.  You can find some of them in the <a href="/ftp/rsync/TODO">TODO file</a> or
 173 <a href="https://bugzilla.samba.org/buglist.cgi?product=rsync&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED&bug_status=VERIFIED">search the bugzilla database</a>.
 174
 175 </ol>
 176
 177 <!--#include virtual="footer.html" -->