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 greeting
  11
  12   @RSYNCD: <version>.<subprotocol>
  13
  14 where <version> is the numeric version (see PROTOCOL_VERSION in rsync.h)
  15 '.' is a literal period, and <subprotocol> is the numeric subprotocol
  16 version (see SUBPROTOCOL_VERSION -- it will be 0 for final releases).
  17 Protocols prior to 30 only output <version> alone.  The daemon expects
  18 to see a similar greeting back from the client.  For protocols prior to
  19 30, an absent ".<subprotocol>" value is assumed to be 0.  For protocol
  20 30, an absent value is a fatal error.  The daemon then follows this line
  21 with a free-format text message-of-the-day (if any is defined).
  22
  23 The server is now in the connected state.  The client can either send
  24 the command
  25
  26   #list
  27
  28 to get a listing of modules, or the name of a module.  After this, the
  29 connection is now bound to a particular module.  Access per host for
  30 this module is now checked, as is per-module connection limits.
  31
  32 If authentication is required to use this module, the server will say
  33
  34   @RSYNCD: AUTHREQD <challenge>
  35
  36 where <challenge> is a random string of base64 characters.  The client
  37 must respond with
  38
  39   <user> <response>
  40
  41 where <user> is the username they claim to be, and <response> is the
  42 base64 form of the MD4 hash of challenge+password.
  43
  44 At this point the server applies all remaining constraints before
  45 handing control to the client, including switching uid/gid, setting up
  46 include and exclude lists, moving to the root of the module, and doing
  47 chroot.
  48
  49 If the login is acceptable, then the server will respond with
  50
  51   @RSYNCD: OK
  52
  53 The client now writes some rsync options, as if it were remotely
  54 executing the command.  The server parses these arguments as if it had
  55 just been invoked with them, but they're added to the existing state.
  56 So if the client specifies a list of files to be included or excluded,
  57 they'll defer to existing limits specified in the server
  58 configuration.
  59
  60 At this point the client and server both switch to using a
  61 multiplexing layer across the socket.  The main point of this is to
  62 allow the server to asynchronously pass errors back, while still
  63 allowing streamed and pipelined data.
  64
  65 Unfortunately, the multiplex protocol is not used at every stage.  We
  66 start up in plain socket mode and then change over by calling
  67 io_start_buffering.  Of course both the client and the server have to
  68 do this at the same point.
  69
  70 The server then talks to the client as normal across the socket,
  71 passing checksums, file lists and so on.  For documentation of that,
  72 stay tuned (or write it yourself!).
  73
  74
  75
  76 ------------
  77 Protocol version changes
  78
  79 30      (2007-10-04, 3.0.0pre1)
  80
  81         The use of a ".<subprotocol>" number was added to
  82         @RSYNCD: <version>.<subprotocol>
  83
  84 25      (2001-08-20, 2.4.7pre2)
  85
  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.