Protocol

[Karlan Mitchell]

I am looking for someone who knows the rsync protocol byte specifics, so
I can write the documentation for the file list and file data transfer
parts of the protocol.  I have already written a simple explanation of
the protocol handshake, and I would really like for the end result to be
place with the code or on the website. 

I have attached what I have written so far, a rough draft of what I
currently know about the handshake....
-------------- next part --------------
	Karlan's dissection of the
	RSYNC protocol (Version 29)
---------------------------------------------
+----------+
| Preface: |
+----------+
	I created this document because
of the lack of documentation on the RSYNC 
protocol.  Do not expect this document to
go into the details of the mathematics at 
work in RSYNC protocol, this has already
been documented.  What I will be writing
about is the byte specifics of the RSYNC
protocol, from handshake to file transfer to
exit.

+---------------+
| Introduction: |
+---------------+
	The RSYNC protocol is not very pretty, 
doesn't contain definied packets, and is not easy 
to interface. RSYNC consists of a mix of plain-text
and binary data.  Basically, the handshake/option part
is plain-text seperated by [1]line-feeds (0x0A);
And after all options have been specified the
[usually] binary data is passed to the client.

+------------+
| Handshake: |
+------------+
	A RSYNC client upon connecting
should receive the ASCII string "@RSYNCD: 29"
ended by a [1]LF. Next the client should expect
the Message of the Day (MOTD), this is multiple
lines, again, seperated by a LF. The client should 
continue reading data until a [2]Empty Line is found.
Now the client should respond with "@RSYNCD: 29" 
terminated by a [1]LF.  Now the server is expecting
the name of a module teminated by a [1]LF;  
	 [I]If the client sends a LF with no module name, the
	    client should expect ASCII strings seperated by
	    [1]LFs, the client should terminate the connection
	    upon receiving "@RSYNCD: EXIT"(LF)
	[II]If the client sends a module name terminated by
	    LF, and the module is present, and doesn't require
            authentication, a "@RSYNCD: OK"(LF) is sent.  
	    If the modules is not present an "@ERROR: data"(LF) is 
	    sent to the client.  If authentication a "@RSYNCD: AUTHREQ <challenge>"
	    is sent, in which case the client must respond with 
            <user> <response> where 'response' is the MD4 hash of
	    password+challenge in base64.


Examples:
+====================================================================+
|   Modules Listing                                                  |
+--------------------------------------------------------------------+
| S: @RSYNCD: 29                                                     |
| S: MOTD:                                                           |
| S: MOTD: Message of the day                                        |
| S: MOTD:                                                           |
| S:                                                                 |
| C: @RSYNCD: 29                                                     |
| C:                                                                 |
| S: pub             /pub area, except mirrors and distributions     |
| S: dist            Locally published distibutions                  |
| S: all             The entire archive, bar nothing                 |
| S: @RSYNCD: EXIT                                                   |
+--------------------------------------------------------------------+

+====================================================================+
|   Handshake for module pub                                         |
+--------------------------------------------------------------------+
| S: @RSYNCD: 29                                                     |
| S: MOTD:                                                           |
| S: MOTD: Message of the day                                        |
| S: MOTD:                                                           |
| S:                                                                 |
| C: @RSYNCD: 29                                                     |
| C: pub                                                             |
| S: @RSYNCD: OK                                                     |
+--------------------------------------------------------------------+

+====================================================================+
|   Handshake for module pub, with AUTHREQ                           |
+--------------------------------------------------------------------+
| No Example, please see above in Handshake, section II...           |
+--------------------------------------------------------------------+




-------------------------+
| !!!! ROUGH DRAFT !!!!  |
| \/ \/ \/ \/ \/ \/ \/   |
+------------------------+
+----------+
| Options: |
+----------+
Send "--server[LF]" for the server function...
Send "--sender[LF]" for the sender function...
Send ".[LF]" to finish arguments...
Send "module/path[LF][LF]" to finish arguments...


+----------+
| NEXT...: |
+----------+
	This is where I don't yet understand the protocol, however
	I can tell you that you should expect a 32 bit value be sent
	by the server, this is time(NULL).  You are expected to send
	another 32 bit value, but I have no clue what is happening; The
	File list is seperated by (double?) zero bytes.

	karlanmitchell at gmail.com if you can help me here!

+------------------------+
| ^^^^^^^^^^^^^^^^^^^^^  |
| !!!! ROUGH DRAFT !!!!  |
+------------------------+
	



---------------------------------------------
---------------------------------------------
[1] LF = line-feed = 0A(hex) = 10(dec)
    Please note the RSYNC protocol uses only LF (0x0A).
    This is different from most protocols which use CRLF, 
    Most readline code should already support both
    sequences, however most programs(ie Ethereal) expect
    only a LF.  This has not been tested on the RSYNC daemon.

[2] LFLF = double LF
    ie. Empty Line
---------------------------------------------
---------------------------------------------

Some information was taken from csprotocol.txt 
in the RSYNC distro.

Karlan Mitchell (copy-left) 2006