Mention John Langford's thesis.
[rsync-web.git] / 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> If you need help, send email to the mailing list. 
31
32 <li><p><b>Q:</b>
33
34 Why does my chrooted rsync daemon crash when doing an LDAP lookup for a user or
35 group?
36
37 <p><b>A:</b>
38
39 There is a bug in some LDAP libraries (e.g. Fedora Core 3) where it crashes
40 when someone looks up a name from inside a chrooted process (one that does not
41 contain copies of the libraries to perform the lookup).  This is a bug that the
42 LDAP libraries will need to fix, and is out of rsync's hands.  You can work
43 around the problem by using the --numeric-ids option, turning chroot off, or
44 getting rid of LDAP lookups.
45
46 <li><p><b>Q:</b>
47
48 Why does my transfer die with something like the following error?
49
50 <pre>rsync: error writing 4 unbuffered bytes - exiting: Broken pipe
51 rsync error: error in rsync protocol data stream (code 12) at io.c(463)
52 </pre>
53
54 <p>or
55
56 <pre>rsync: connection unexpectedly closed (24 bytes read so far)
57 rsync error: error in rsync protocol data stream (code 12) at io.c(342)
58 </pre>
59
60 <p><b>A:</b>
61
62 This error tells you that the local rsync was trying to talk to the remote
63 rsync, but the connection to that rsync is now gone.  The thing you must
64 figure out is <b>why</b>, and that can involve some investigative work.
65
66 <p>If the remote rsync is a daemon, your first step should be to look at
67 the daemon's log file to see if it logged an error explaining why it
68 aborted the transfer.
69
70 <p>Beginning with version 2.6.3, rsync now does a better job of retreiving
71 the error from the remote
72 process than older versions of rsync, so you may wish to try upgrading and
73 see if you now get sent the error message from the remote rsync.
74
75 <p>There are several common causes for a remote rsync process going away:
76
77 <ul>
78
79 <li>The destination disk is full (remember that you need at least the
80 size of the largest file that needs to be updated available in free
81 disk space for the transfer to succeed).
82
83 <li>A network error caused the connection to be dropped.
84
85 <li>The remote rsync executable wasn't found.
86
87 <li>Your remote-shell setup isn't working right or isn't "clean"
88 (i.e. it is sending spurious text to rsync).
89
90 </ul>
91
92 <p>If you can't figure out why the failure happened, there are steps
93 you can take to debug the situation.  One way is to create a shell
94 script on the remote system such as
95 <a href="rsync-debug">this one named "rsync-debug"</a>.
96 You would use the script like this:
97
98 <pre>rsync -av --rsync-path=/some/path/rsync-debug HOST:SOURCE DEST
99 rsync -av --rsync-path=/some/path/rsync-debug SOURCE HOST:DEST
100 </pre>
101
102 <p>This script enables core dumps and also logs all the OS system calls
103 that lead up to the failure to a file in the /tmp dir.  You can use the
104 resulting files to help figure out why the remote rsync failed.
105
106 <p>If you are rsyncing to an rsync daemon, the above script won't have
107 any effect.  Instead, halt the current daemon and run a debug version
108 with core-dumps enabled and (if desired) using a
109 system-call tracing utility such as <i>strace</i>, <i>truss</i>, or
110 <i>tusc</i>.  For strace, you would do it like this (the -f option
111 tells strace to follow the child processes too):
112
113 <pre>ulimit -c unlimited
114 strace -f rsync --daemon --no-detach 2&gt;/tmp/rsync-$$.out
115 </pre>
116
117 <p>Then, use a separate window to actually run the failing transfer, after
118 which you can kill the debug rsync daemon (pressing Ctrl-C should do it).
119
120 <p>If you are using rsync under inetd, I'd suggest temporarily disabling
121 that and using the above daemon approach to debug what is going on.
122
123 <li><p><b>Q:</b>
124
125 Why does my connection to an rsync daemon (using the "::" syntax)
126 fail immediately with an error like the following?
127
128 <pre>rsync: connection unexpectedly closed (24 bytes read so far)
129 rsync error: error in rsync protocol data stream (code 12) at io.c(342)
130 </pre>
131
132 <p><b>A:</b>
133
134 Older rsync daemons (before 2.6.3) were unable to return errors that were
135 generated during the option-parsing phase of the transfer.  Look in the
136 logfile on the server to see if an error was reported, such as a "refused"
137 option, an option that the server rsync doesn't support (e.g.  perhaps
138 links are not supported by the server), or some other failure (such as
139 trying to send data to a read-only module).  Upgrading the version of rsync
140 that is running as a daemon to at least 2.6.3 will allow these errors to
141 get returned to all rsync clients, old or new alike.
142
143 <li><p><b>Q:</b>
144
145 Why doesn't --dry-run (-n) show all the changed directories?
146
147 <p><b>A:</b>
148
149 This was a bug in versions prior to 2.6.4.  Upgrade both rsync versions (or at
150 least the receiving side).
151
152 <li><p><b>Q:</b>
153
154 Aren't there more issues than this?
155
156 <p><b>A:</b>
157
158 Yes.  You can find some of them in the <a href="/ftp/rsync/TODO">TODO file</a> or
159 <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>.
160
161 </ol>
162
163 <!--#include virtual="footer.html" -->