.\"	$OpenBSD: rsyncd.5,v 1.2 2019/02/10 23:24:14 benno Exp $
.\"
.\" Copyright (c) 2019 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: February 10 2019 $
.Dt RSYNCD 5
.Os
.Sh NAME
.Nm rsyncd
.Nd rsyncd wire protocol
.Sh DESCRIPTION
The
.Nm
protocol described in this relates to the BSD-licensed
.Xr openrsync 1 ,
a re-implementation of the GPL-licensed reference utility
.Xr rsync 1 .
It is compatible with version 27 of the reference.
.Pp
The
.Nm
protocol is an envelope protocol for
.Xr rsync 5
between a client and an rsync://-capable server.
It provides a means to exchange capabilities information prior to file
transfer.
.Pp
In this document,
.Qq client
refers to the
.Xr openrsync 1
utility making the request.
It follows that
.Qq server
refers to the daemon servicing the request.
.Pp
A connection between a client and server consists of host, a module, and
zero or more paths.
.Pp
.Dl openrsync rsync://host/module/path1 rsync://host/path2... dest
.Pp
At this time, operating in sender mode (with the rsync:// host receiving
information) is not described in this document.
.Ss Data types
These are the same as in
.Xr rsync 5 .
A newline is always a standalone \en.
.Ss Client process
After initialising a connection, the client and server exchange the
following information, in order.
This portion of the process is
.Em not
multiplexed.
.Pp
.Bl -enum -compact
.It
client sends requested module followed by newline
.It
server responds with preamble followed by standalone newline
.El
.Pp
The requested module must have non-zero length.
The preamble consists in a sequence of lines.
Each line either contains free-form text sent by the server as a
.Qq motd
.Pq message of the day
or a command:
.Pp
.Dl @RSYNCD: command\en
.Pp
The only supported command is the server protocol specification:
.Pp
.Dl @RSYNCD: xx[.yy]\en
.Pp
The optional component is the submodule, which may be discarded.
The version may only be specified once.
Both the motd and commands end in the special termination command:
.Pp
.Dl @RSYNCD: OK\en
.Pp
Following that, the client must send the command-line arguments that
would otherwise be used to start a
.Xr openrsync 1
server.
Each argument must be specified on its own line, e.g.,
.Pp
.Dl --server\en--sender\en-r\en-t\en.\enpath1\enpath2
.Pp
This must be followed by a standalone newline.
.Pp
If the server does not understand or accept any of the command-line
arguments, it will exit at this point.
.Pp
Following this, the client must read the integer-length session checksum
seed.
Multiplexing is subsequently enabled.
.Pp
The sequence that follows is stipulated in
.Xr rsync 5
following the handshake.
.\" The following requests should be uncommented and used where appropriate.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.\" .Sh EXAMPLES
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr openrsync 1 ,
.Xr rsync 5
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh CAVEATS
.\" .Sh BUGS