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