Including my extern-squishing script, which just found an
[rsync/rsync.git] / csprotocol.txt
1 This is kind of informal and may be wrong, but it helped me.  It's
2 basically a summary of clientserver.c and authenticate.c.
3
4  -- Martin Pool <mbp@samba.org>
5
6 $Id$
7
8
9
10
11 This is the protocol used for rsync --daemon; i.e. connections to port
12 873 rather than invocations over a remote shell.
13
14 When the server accepts a connection, it prints a greeting
15
16   @RSYNCD: <version>
17
18 where <version> is the numeric version; currently 24.  It follows this
19 with a free text message-of-the-day.  It expects to see a similar
20 greeting back from the client.
21
22 The server is now in the connected state.  The client can either send
23 the command
24
25   #list
26
27 to get a listing of modules, or the name of a module.  After this, the
28 connection is now bound to a particular module.  Access per host for
29 this module is now checked, as is per-module connection limits.
30
31 If authentication is required to use this module, the server will say
32
33   @RSYNCD: AUTHREQD <challenge>
34
35 where <challenge> is a random string of base64 characters.  The client
36 must respond with
37
38   <user> <response>
39
40 where <user> is the username they claim to be, and <response> is the
41 base64 form of the MD4 hash of challenge+password.
42
43 At this point the server applies all remaining constraints before
44 handing control to the client, including switching uid/gid, setting up
45 include and exclude lists, moving to the root of the module, and doing
46 chroot.
47
48 If the login is acceptable, then the server will respond with
49
50   @RSYNCD: OK
51
52 The client now writes some rsync options, as if it were remotely
53 executing the command.  The server parses these arguments as if it had
54 just been invoked with them, but they're added to the existing state.
55 So if the client specifies a list of files to be included or excluded,
56 they'll defer to existing limits specified in the server
57 configuration.
58
59 At this point the client and server both switch to using a
60 multiplexing layer across the socket.  The main point of this is to
61 allow the server to asynchronously pass errors back, while still
62 allowing streamed and pipelined data.
63
64 Unfortunately, the multiplex protocol is not used at every stage.  We
65 start up in plain socket mode and then change over by calling
66 io_start_buffering.  Of course both the client and the server have to
67 do this at the same point.
68
69 The server then talks to the client as normal across the socket,
70 passing checksums, file lists and so on.  For documentation of that,
71 stay tuned (or write it yourself!).
72
73
74
75 ------------
76 Protocol version changes
77
78 25       (2001-08-20, 2.4.7pre2) 
79
80          Send an explicit "@RSYNC EXIT" command at the end of the
81          module listing.  We never intentionally end the transmission
82          by just closing the socket anymore.