Draft documentation of the client-server protocol.
[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
7
8
9 This is the protocol used for rsync --daemon; i.e. connections to port
10 873 rather than invocations over a remote shell.
11
12 When the server accepts a connection, it prints a greeting
13
14   @RSYNCD: <version>
15
16 where <version> is the numeric version; currently 24.  It follows this
17 with a free text message-of-the-day.  It expects to see a similar
18 greeting back from the client.
19
20 The server is now in the connected state.  The client can either send
21 the command
22
23   #list
24
25 to get a listing of modules, or the name of a module.  After this, the
26 connection is now bound to a particular module.  Access per host for
27 this module is now checked, as is per-module connection limits.
28
29 If authentication is required to use this module, the server will say
30
31   @RSYNCD: AUTHREQD <challenge>
32
33 where <challenge> is a random string of base64 characters.  The client
34 must respond with
35
36   <user> <response>
37
38 where <user> is the username they claim to be, and <response> is the
39 base64 form of the MD4 hash of challenge+password.
40
41 At this point the server applies all remaining constraints before
42 handing control to the client, including switching uid/gid, setting up
43 include and exclude lists, moving to the root of the module, and doing
44 chroot.
45
46 If the login is acceptable, then the server will respond with
47
48   @RSYNCD: OK
49
50 The client now writes some rsync options, as if it were remotely
51 executing the command.  The server parses these arguments as if it had
52 just been invoked with them, but they're added to the existing state.
53 So if the client specifies a list of files to be included or excluded,
54 they'll defer to existing limits specified in the server
55 configuration.
56
57 The server then talks to the client as normal across the socket,
58 passing checksums, file lists and so on.  For documentation of that,
59 stay tuned (or write it yourself!).
60