Annotation of src/usr.bin/rsync/rsyncd.5, Revision 1.2
1.1 benno 1: .\" $OpenBSD$
2: .\"
3: .\" Copyright (c) 2019 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
17: .Dd $Mdocdate$
18: .Dt RSYNCD 5
19: .Os
20: .Sh NAME
21: .Nm rsyncd
22: .Nd rsyncd wire protocol
23: .Sh DESCRIPTION
24: The
25: .Nm
26: protocol described in this relates to the BSD-licensed
27: .Xr openrsync 1 ,
28: a re-implementation of the GPL-licensed reference utility
29: .Xr rsync 1 .
30: It is compatible with version 27 of the reference.
31: .Pp
32: The
33: .Nm
34: protocol is an envelope protocol for
35: .Xr rsync 5
36: between a client and an rsync://-capable server.
37: It provides a means to exchange capabilities information prior to file
38: transfer.
39: .Pp
40: In this document,
41: .Qq client
42: refers to the
43: .Xr openrsync 1
44: utility making the request.
45: It follows that
46: .Qq server
47: refers to the daemon servicing the request.
48: .Pp
49: A connection between a client and server consists of host, a module, and
50: zero or more paths.
51: .Pp
52: .Dl openrsync rsync://host/module/path1 rsync://host/path2... dest
53: .Pp
54: At this time, operating in sender mode (with the rsync:// host receiving
55: information) is not described in this document.
56: .Ss Data types
57: These are the same as in
58: .Xr rsync 5 .
59: A newline is always a standalone \en.
60: .Ss Client process
61: After initialising a connection, the client and server exchange the
62: following information, in order.
63: This portion of the process is
64: .Em not
65: multiplexed.
66: .Pp
67: .Bl -enum -compact
68: .It
69: client sends requested module followed by newline
70: .It
71: server responds with preamble followed by standalone newline
72: .El
73: .Pp
74: The requested module must have non-zero length.
75: The preamble consists in a sequence of lines.
76: Each line either contains free-form text sent by the server as a
77: .Qq motd
78: .Pq message of the day
79: or a command:
80: .Pp
81: .Dl @RSYNCD: command\en
82: .Pp
83: The only supported command is the server protocol specification:
84: .Pp
85: .Dl @RSYNCD: xx[.yy]\en
86: .Pp
87: The optional component is the submodule, which may be discarded.
88: The version may only be specified once.
89: Both the motd and commands end in the special termination command:
90: .Pp
91: .Dl @RSYNCD: OK\en
92: .Pp
93: Following that, the client must send the command-line arguments that
94: would otherwise be used to start a
95: .Xr openrsync 1
96: server.
97: Each argument must be specified on its own line, e.g.,
98: .Pp
99: .Dl --server\en--sender\en-r\en-t\en.\enpath1\enpath2
100: .Pp
101: This must be followed by a standalone newline.
102: .Pp
103: If the server does not understand or accept any of the command-line
104: arguments, it will exit at this point.
105: .Pp
106: Following this, the client must read the integer-length session checksum
107: seed.
108: Multiplexing is subsequently enabled.
109: .Pp
110: The sequence that follows is stipulated in
111: .Xr rsync 5
112: following the handshake.
113: .\" The following requests should be uncommented and used where appropriate.
114: .\" .Sh CONTEXT
115: .\" For section 9 functions only.
116: .\" .Sh RETURN VALUES
117: .\" For sections 2, 3, and 9 function return values only.
118: .\" .Sh ENVIRONMENT
119: .\" For sections 1, 6, 7, and 8 only.
120: .\" .Sh FILES
121: .\" .Sh EXIT STATUS
122: .\" For sections 1, 6, and 8 only.
123: .\" .Sh EXAMPLES
124: .\" .Sh DIAGNOSTICS
125: .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
126: .\" .Sh ERRORS
127: .\" For sections 2, 3, 4, and 9 errno settings only.
128: .Sh SEE ALSO
129: .Xr openrsync 1 ,
130: .Xr rsync 5
131: .\" .Sh STANDARDS
132: .\" .Sh HISTORY
133: .\" .Sh AUTHORS
134: .\" .Sh CAVEATS
135: .\" .Sh BUGS