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 This is the protocol used for rsync --daemon; i.e. connections to port
   8 873 rather than invocations over a remote shell.
   9
  10 When the server accepts a connection, it prints a newline-terminated
  11 greeting line:
  12
  13   @RSYNCD: <version>.<subprotocol> <digest1> <digestN>
  14
  15 The <version> is the numeric version (see PROTOCOL_VERSION in rsync.h)
  16 The <subprotocol> is the numeric subprotocol version (which is 0 for a
  17 final protocol version, as the SUBPROTOCOL_VERSION define discusses).
  18 The <digestN> names are the authentication digest algorithms that the
  19 daemon supports, listed in order of preference.
  20
  21 An rsync prior to 3.2.7 omits the digest names.  An rsync prior to 3.0.0
  22 also omits the period and the <subprotocol> value.  Since a final
  23 protocol has a subprotocol value of 0, a missing subprotocol value is
  24 assumed to be 0 for any protocol prior to 30.  It is considered a fatal
  25 error for protocol 30 and above to omit it.  It is considered a fatal
  26 error for protocol 32 and above to omit the digest name list (currently
  27 31 is the newest protocol).
  28
  29 The daemon expects to see a similar greeting line back from the client.
  30 Once received, the daemon follows the opening line with a free-format
  31 text message-of-the-day (if any is defined).
  32
  33 The server is now in the connected state.  The client can either send
  34 the command:
  35
  36   #list
  37
  38 (to get a listing of modules) or the name of a module.  After this, the
  39 connection is now bound to a particular module.  Access per host for
  40 this module is now checked, as is per-module connection limits.
  41
  42 If authentication is required to use this module, the server will say:
  43
  44   @RSYNCD: AUTHREQD <challenge>
  45
  46 where <challenge> is a random string of base64 characters.  The client
  47 must respond with:
  48
  49   <user> <response>
  50
  51 The <user> is the username they claim to be. The <response> is the
  52 base64 form of the digest hash of the challenge+password string. The
  53 chosen digest method is the most preferred client method that is also in
  54 the server's list.  If no digest list was explicitly provided, the side
  55 expecting a list assumes the other side provided either the single name
  56 "md5" (for a negotiated protocol 30), or the single name "md4" (for an
  57 older protocol).
  58
  59 At this point the server applies all remaining constraints before
  60 handing control to the client, including switching uid/gid, setting up
  61 include and exclude lists, moving to the root of the module, and doing
  62 chroot.
  63
  64 If the login is acceptable, then the server will respond with
  65
  66   @RSYNCD: OK
  67
  68 The client now writes some rsync options, as if it were remotely
  69 executing the command.  The server parses these arguments as if it had
  70 just been invoked with them, but they're added to the existing state.
  71 So if the client specifies a list of files to be included or excluded,
  72 they'll defer to existing limits specified in the server
  73 configuration.
  74
  75 At this point the client and server both switch to using a
  76 multiplexing layer across the socket.  The main point of this is to
  77 allow the server to asynchronously pass errors back, while still
  78 allowing streamed and pipelined data.
  79
  80 Unfortunately, the multiplex protocol is not used at every stage.  We
  81 start up in plain socket mode and then change over by calling
  82 io_start_buffering.  Of course both the client and the server have to
  83 do this at the same point.
  84
  85 The server then talks to the client as normal across the socket,
  86 passing checksums, file lists and so on.  For documentation of that,
  87 stay tuned (or write it yourself!).
  88
  89
  90
  91 ------------
  92 Protocol version changes
  93
  94 31      (2022-09-10, 3.2.7dev)
  95
  96         The use of a suffixed list of digest names was added as an
  97         optional suffix to the greeting line.
  98
  99 30      (2007-10-04, 3.0.0pre1)
 100
 101         The use of a ".<subprotocol>" number was added to
 102         @RSYNCD: <version>.<subprotocol>
 103
 104 25      (2001-08-20, 2.4.7pre2)
 105
 106         Send an explicit "@RSYNC EXIT" command at the end of the
 107         module listing.  We never intentionally end the transmission
 108         by just closing the socket anymore.