<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
-<TITLE>rsync's current issues</TITLE>
+<TITLE>rsync current issues</TITLE>
</HEAD>
<!--#include virtual="header.html" -->
-<H2 align="center">Current issues</H2>
+<H2 align="center">current issues and debugging</H2>
<ol>
-<li><b>Q:</b>
+<li><p><b>Q:</b>
+
+Rsync appears hung -- what should I do?
+
+<p><b>A:</b>
+
+When experiencing a hang or freeze <b>please</b> gather the following
+information before killing the rsync process:
+
+<ul>
+
+<li> The state of the send/receive queues shown with netstat on the two ends.
+
+<li> The system call that each of the 3 processes is stuck in (use truss on
+solaris, strace on Linux, etc.).
+
+</ul>
+
+<p>See the "rsync-debug" script below for an example of how to grab strace
+information from the remote rsync process(es). If you need help, send email to
+the mailing list.
+
+<li><p><b>Q:</b>
+
+Why does my chrooted rsync daemon crash when doing an LDAP lookup for a user or
+group?
+
+<p><b>A:</b>
+
+There is a bug in some LDAP libraries (e.g. Fedora Core 3) where it crashes
+when someone looks up a name from inside a chrooted process (one that does not
+contain copies of the libraries to perform the lookup). This is a bug that the
+LDAP libraries will need to fix, and is out of rsync's hands. You can work
+around the problem by using the --numeric-ids option, turning chroot off, or
+getting rid of LDAP lookups.
+
+<li><p><b>Q:</b>
+
+Why does my transfer die with something like the following error?
-Transfers die with something like
<pre>rsync: error writing 4 unbuffered bytes - exiting: Broken pipe
-rsync error: error in rsync protocol data stream (code 12) at ../src/io.c(463)
+rsync error: error in rsync protocol data stream (code 12) at io.c(463)
+</pre>
+
+<p>or
+
+<pre>rsync: connection unexpectedly closed (24 bytes read so far)
+rsync error: error in rsync protocol data stream (code 12) at io.c(342)
</pre>
<p><b>A:</b>
- Sometimes fatal error messages from the remote machine can
- be lost on the way to the client; you should investigate on
- the server for something stopping the transmission. Several
- common causes:
+This error tells you that the local rsync was trying to talk to the remote
+rsync, but the connection to that rsync is now gone. The thing you must
+figure out is <b>why</b>, and that can involve some investigative work.
+
+<p>If the remote rsync is a daemon, your first step should be to look at
+the daemon's log file to see if it logged an error explaining why it
+aborted the transfer.
+
+<p>Beginning with version 2.6.3, rsync now does a better job of retreiving
+the error from the remote
+process than older versions of rsync, so you may wish to try upgrading and
+see if you now get sent the error message from the remote rsync.
+
+<p>There are several common causes for a remote rsync process going away:
<ul>
-<li>The destination disk is full.
+
+<li>The destination disk is full (remember that you need at least the
+size of the largest file that needs to be updated available in free
+disk space for the transfer to succeed).
+
+<li>A network error caused the connection to be dropped.
+
<li>The remote rsync executable wasn't found.
+
<li>Your remote-shell setup isn't working right or isn't "clean"
-(i.e. is sending spurious text to rsync).
+(i.e. it is sending spurious text to rsync).
+
</ul>
-<li><b>Q:</b>
+<p>If you can't figure out why the failure happened, there are steps
+you can take to debug the situation. One way is to create a shell
+script on the remote system such as
+<a href="rsync-debug">this one named "rsync-debug"</a>.
+You would use the script like this:
+
+<pre>rsync -av --rsync-path=/some/path/rsync-debug HOST:SOURCE DEST
+rsync -av --rsync-path=/some/path/rsync-debug SOURCE HOST:DEST
+</pre>
+
+<p>This script enables core dumps and also logs all the OS system calls
+that lead up to the failure to a file in the /tmp dir. You can use the
+resulting files to help figure out why the remote rsync failed.
+
+<p>If you are rsyncing directly to an rsync daemon (without using a
+remote-shell transport), the above script won't have
+any effect. Instead, halt the current daemon and run a debug version
+with core-dumps enabled and (if desired) using a
+system-call tracing utility such as <i>strace</i>, <i>truss</i>, or
+<i>tusc</i>. For strace, you would do it like this (the -f option
+tells strace to follow the child processes too):
+
+<pre>ulimit -c unlimited
+strace -f rsync --daemon --no-detach 2>/tmp/rsync-$$.out
+</pre>
+
+<p>Then, use a separate window to actually run the failing transfer, after
+which you can kill the debug rsync daemon (pressing Ctrl-C should do it).
+
+<p>If you are using rsync under inetd, I'd suggest temporarily disabling
+that and using the above daemon approach to debug what is going on.
+
+<li><p><b>Q:</b>
+
+Why does my connection to an rsync daemon (using the "::" syntax)
+fail immediately with an error like the following?
+
+<pre>rsync: connection unexpectedly closed (24 bytes read so far)
+rsync error: error in rsync protocol data stream (code 12) at io.c(342)
+</pre>
+
+<p><b>A:</b>
+
+Older rsync daemons (before 2.6.3) were unable to return errors that were
+generated during the option-parsing phase of the transfer. Look in the
+logfile on the server to see if an error was reported, such as a "refused"
+option, an option that the server rsync doesn't support (e.g. perhaps
+links are not supported by the server), or some other failure (such as
+trying to send data to a read-only module). Upgrading the version of rsync
+that is running as a daemon to at least 2.6.3 will allow these errors to
+get returned to all rsync clients, old or new alike.
+
+<li><p><b>Q:</b>
+
+Why doesn't --dry-run (-n) show all the changed directories?
+
+<p><b>A:</b>
+
+This was a bug in versions prior to 2.6.4. Upgrade both rsync versions (or at
+least the receiving side).
+
+<li><p><b>Q:</b>
-Using --dry-run (-n) doesn't show all changed directories.
+Aren't there more issues than this?
<p><b>A:</b>
-Correct. Rsync shows all other changes, but some directory changes are
-not currently described in --dry-run mode. Hopefully a future version
-will fix this.
+Yes. You can find some of them in the <a href="/ftp/rsync/TODO">TODO file</a> or
+<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>.
</ol>
git.samba.org / rsync-web.git / blobdiff