Annotation of embedaddon/rsync/rsyncd.conf.5, revision 1.1.1.1
1.1 misho 1: .TH "rsyncd.conf" "5" "23 Sep 2011" "" ""
2: .SH "NAME"
3: rsyncd.conf \- configuration file for rsync in daemon mode
4: .SH "SYNOPSIS"
5:
6: .PP
7: rsyncd.conf
8: .PP
9: .SH "DESCRIPTION"
10:
11: .PP
12: The rsyncd.conf file is the runtime configuration file for rsync when
13: run as an rsync daemon.
14: .PP
15: The rsyncd.conf file controls authentication, access, logging and
16: available modules.
17: .PP
18: .SH "FILE FORMAT"
19:
20: .PP
21: The file consists of modules and parameters. A module begins with the
22: name of the module in square brackets and continues until the next
23: module begins. Modules contain parameters of the form \(dq\&name = value\(dq\&.
24: .PP
25: The file is line\-based \-\- that is, each newline\-terminated line represents
26: either a comment, a module name or a parameter.
27: .PP
28: Only the first equals sign in a parameter is significant. Whitespace before
29: or after the first equals sign is discarded. Leading, trailing and internal
30: whitespace in module and parameter names is irrelevant. Leading and
31: trailing whitespace in a parameter value is discarded. Internal whitespace
32: within a parameter value is retained verbatim.
33: .PP
34: Any line beginning with a hash (#) is ignored, as are lines containing
35: only whitespace.
36: .PP
37: Any line ending in a \e is \(dq\&continued\(dq\& on the next line in the
38: customary UNIX fashion.
39: .PP
40: The values following the equals sign in parameters are all either a string
41: (no quotes needed) or a boolean, which may be given as yes/no, 0/1 or
42: true/false. Case is not significant in boolean values, but is preserved
43: in string values.
44: .PP
45: .SH "LAUNCHING THE RSYNC DAEMON"
46:
47: .PP
48: The rsync daemon is launched by specifying the \fB\-\-daemon\fP option to
49: rsync.
50: .PP
51: The daemon must run with root privileges if you wish to use chroot, to
52: bind to a port numbered under 1024 (as is the default 873), or to set
53: file ownership. Otherwise, it must just have permission to read and
54: write the appropriate data, log, and lock files.
55: .PP
56: You can launch it either via inetd, as a stand\-alone daemon, or from
57: an rsync client via a remote shell. If run as a stand\-alone daemon then
58: just run the command \(dq\&\fBrsync \-\-daemon\fP\(dq\& from a suitable startup script.
59: .PP
60: When run via inetd you should add a line like this to /etc/services:
61: .PP
62: .nf
63: rsync 873/tcp
64: .fi
65:
66: .PP
67: and a single line something like this to /etc/inetd.conf:
68: .PP
69: .nf
70: rsync stream tcp nowait root /usr/bin/rsync rsyncd \-\-daemon
71: .fi
72:
73: .PP
74: Replace \(dq\&/usr/bin/rsync\(dq\& with the path to where you have rsync installed on
75: your system. You will then need to send inetd a HUP signal to tell it to
76: reread its config file.
77: .PP
78: Note that you should \fBnot\fP send the rsync daemon a HUP signal to force
79: it to reread the \f(CWrsyncd.conf\fP file. The file is re\-read on each client
80: connection.
81: .PP
82: .SH "GLOBAL PARAMETERS"
83:
84: .PP
85: The first parameters in the file (before a [module] header) are the
86: global parameters.
87: .PP
88: You may also include any module parameters in the global part of the
89: config file in which case the supplied value will override the
90: default for that parameter.
91: .PP
92: .IP "\fBmotd file\fP"
93: This parameter allows you to specify a
94: \(dq\&message of the day\(dq\& to display to clients on each connect. This
95: usually contains site information and any legal notices. The default
96: is no motd file.
97: .IP
98: .IP "\fBpid file\fP"
99: This parameter tells the rsync daemon to write
100: its process ID to that file. If the file already exists, the rsync
101: daemon will abort rather than overwrite the file.
102: .IP
103: .IP "\fBport\fP"
104: You can override the default port the daemon will listen on
105: by specifying this value (defaults to 873). This is ignored if the daemon
106: is being run by inetd, and is superseded by the \fB\-\-port\fP command\-line option.
107: .IP
108: .IP "\fBaddress\fP"
109: You can override the default IP address the daemon
110: will listen on by specifying this value. This is ignored if the daemon is
111: being run by inetd, and is superseded by the \fB\-\-address\fP command\-line option.
112: .IP
113: .IP "\fBsocket options\fP"
114: This parameter can provide endless fun for people
115: who like to tune their systems to the utmost degree. You can set all
116: sorts of socket options which may make transfers faster (or
117: slower!). Read the man page for the
118: \f(CWsetsockopt()\fP
119: system call for
120: details on some of the options you may be able to set. By default no
121: special socket options are set. These settings can also be specified
122: via the \fB\-\-sockopts\fP command\-line option.
123: .IP
124: .SH "MODULE PARAMETERS"
125:
126: .PP
127: After the global parameters you should define a number of modules, each
128: module exports a directory tree as a symbolic name. Modules are
129: exported by specifying a module name in square brackets [module]
130: followed by the parameters for that module.
131: The module name cannot contain a slash or a closing square bracket. If the
132: name contains whitespace, each internal sequence of whitespace will be
133: changed into a single space, while leading or trailing whitespace will be
134: discarded.
135: .PP
136: .IP "\fBcomment\fP"
137: This parameter specifies a description string
138: that is displayed next to the module name when clients obtain a list
139: of available modules. The default is no comment.
140: .IP
141: .IP "\fBpath\fP"
142: This parameter specifies the directory in the daemon\(cq\&s
143: filesystem to make available in this module. You must specify this parameter
144: for each module in \f(CWrsyncd.conf\fP.
145: .IP
146: It is fine if the path includes internal spaces \-\- they will be retained
147: verbatim (which means that you shouldn\(cq\&t try to escape them). If your final
148: directory has a trailing space (and this is somehow not something you wish to
149: fix), append a trailing slash to the path to avoid losing the trailing
150: whitespace.
151: .IP
152: .IP "\fBuse chroot\fP"
153: If \(dq\&use chroot\(dq\& is true, the rsync daemon will chroot
154: to the \(dq\&path\(dq\& before starting the file transfer with the client. This has
155: the advantage of extra protection against possible implementation security
156: holes, but it has the disadvantages of requiring super\-user privileges,
157: of not being able to follow symbolic links that are either absolute or outside
158: of the new root path, and of complicating the preservation of users and groups
159: by name (see below).
160: .IP
161: As an additional safety feature, you can specify a dot\-dir in the module\(cq\&s
162: \(dq\&path\(dq\& to indicate the point where the chroot should occur. This allows rsync
163: to run in a chroot with a non\-\(dq\&/\(dq\& path for the top of the transfer hierarchy.
164: Doing this guards against unintended library loading (since those absolute
165: paths will not be inside the transfer hierarchy unless you have used an unwise
166: pathname), and lets you setup libraries for the chroot that are outside of the
167: transfer. For example, specifying \(dq\&/var/rsync/./module1\(dq\& will chroot to the
168: \(dq\&/var/rsync\(dq\& directory and set the inside\-chroot path to \(dq\&/module1\(dq\&. If you
169: had omitted the dot\-dir, the chroot would have used the whole path, and the
170: inside\-chroot path would have been \(dq\&/\(dq\&.
171: .IP
172: When \(dq\&use chroot\(dq\& is false or the inside\-chroot path is not \(dq\&/\(dq\&, rsync will:
173: (1) munge symlinks by
174: default for security reasons (see \(dq\&munge symlinks\(dq\& for a way to turn this
175: off, but only if you trust your users), (2) substitute leading slashes in
176: absolute paths with the module\(cq\&s path (so that options such as
177: \fB\-\-backup\-dir\fP, \fB\-\-compare\-dest\fP, etc. interpret an absolute path as
178: rooted in the module\(cq\&s \(dq\&path\(dq\& dir), and (3) trim \(dq\&..\(dq\& path elements from
179: args if rsync believes they would escape the module hierarchy.
180: The default for \(dq\&use chroot\(dq\& is true, and is the safer choice (especially
181: if the module is not read\-only).
182: .IP
183: When this parameter is enabled, rsync will not attempt to map users and groups
184: by name (by default), but instead copy IDs as though \fB\-\-numeric\-ids\fP had
185: been specified. In order to enable name\-mapping, rsync needs to be able to
186: use the standard library functions for looking up names and IDs (i.e.
187: \f(CWgetpwuid()\fP
188: ,
189: \f(CWgetgrgid()\fP
190: ,
191: \f(CWgetpwname()\fP
192: , and
193: \f(CWgetgrnam()\fP
194: ).
195: This means the rsync
196: process in the chroot hierarchy will need to have access to the resources
197: used by these library functions (traditionally /etc/passwd and
198: /etc/group, but perhaps additional dynamic libraries as well).
199: .IP
200: If you copy the necessary resources into the module\(cq\&s chroot area, you
201: should protect them through your OS\(cq\&s normal user/group or ACL settings (to
202: prevent the rsync module\(cq\&s user from being able to change them), and then
203: hide them from the user\(cq\&s view via \(dq\&exclude\(dq\& (see how in the discussion of
204: that parameter). At that point it will be safe to enable the mapping of users
205: and groups by name using the \(dq\&numeric ids\(dq\& daemon parameter (see below).
206: .IP
207: Note also that you are free to setup custom user/group information in the
208: chroot area that is different from your normal system. For example, you
209: could abbreviate the list of users and groups.
210: .IP
211: .IP "\fBnumeric ids\fP"
212: Enabling this parameter disables the mapping
213: of users and groups by name for the current daemon module. This prevents
214: the daemon from trying to load any user/group\-related files or libraries.
215: This enabling makes the transfer behave as if the client had passed
216: the \fB\-\-numeric\-ids\fP command\-line option. By default, this parameter is
217: enabled for chroot modules and disabled for non\-chroot modules.
218: .IP
219: A chroot\-enabled module should not have this parameter enabled unless you\(cq\&ve
220: taken steps to ensure that the module has the necessary resources it needs
221: to translate names, and that it is not possible for a user to change those
222: resources.
223: .IP
224: .IP "\fBmunge symlinks\fP"
225: This parameter tells rsync to modify
226: all incoming symlinks in a way that makes them unusable but recoverable
227: (see below). This should help protect your files from user trickery when
228: your daemon module is writable. The default is disabled when \(dq\&use chroot\(dq\&
229: is on and the inside\-chroot path is \(dq\&/\(dq\&, otherwise it is enabled.
230: .IP
231: If you disable this parameter on a daemon that is not read\-only, there
232: are tricks that a user can play with uploaded symlinks to access
233: daemon\-excluded items (if your module has any), and, if \(dq\&use chroot\(dq\&
234: is off, rsync can even be tricked into showing or changing data that
235: is outside the module\(cq\&s path (as access\-permissions allow).
236: .IP
237: The way rsync disables the use of symlinks is to prefix each one with
238: the string \(dq\&/rsyncd\-munged/\(dq\&. This prevents the links from being used
239: as long as that directory does not exist. When this parameter is enabled,
240: rsync will refuse to run if that path is a directory or a symlink to
241: a directory. When using the \(dq\&munge symlinks\(dq\& parameter in a chroot area
242: that has an inside\-chroot path of \(dq\&/\(dq\&, you should add \(dq\&/rsyncd\-munged/\(dq\&
243: to the exclude setting for the module so that
244: a user can\(cq\&t try to create it.
245: .IP
246: Note: rsync makes no attempt to verify that any pre\-existing symlinks in
247: the module\(cq\&s hierarchy are as safe as you want them to be (unless, of
248: course, it just copied in the whole hierarchy). If you setup an rsync
249: daemon on a new area or locally add symlinks, you can manually protect your
250: symlinks from being abused by prefixing \(dq\&/rsyncd\-munged/\(dq\& to the start of
251: every symlink\(cq\&s value. There is a perl script in the support directory
252: of the source code named \(dq\&munge\-symlinks\(dq\& that can be used to add or remove
253: this prefix from your symlinks.
254: .IP
255: When this parameter is disabled on a writable module and \(dq\&use chroot\(dq\& is off
256: (or the inside\-chroot path is not \(dq\&/\(dq\&),
257: incoming symlinks will be modified to drop a leading slash and to remove \(dq\&..\(dq\&
258: path elements that rsync believes will allow a symlink to escape the module\(cq\&s
259: hierarchy. There are tricky ways to work around this, though, so you had
260: better trust your users if you choose this combination of parameters.
261: .IP
262: .IP "\fBcharset\fP"
263: This specifies the name of the character set in which the
264: module\(cq\&s filenames are stored. If the client uses an \fB\-\-iconv\fP option,
265: the daemon will use the value of the \(dq\&charset\(dq\& parameter regardless of the
266: character set the client actually passed. This allows the daemon to
267: support charset conversion in a chroot module without extra files in the
268: chroot area, and also ensures that name\-translation is done in a consistent
269: manner. If the \(dq\&charset\(dq\& parameter is not set, the \fB\-\-iconv\fP option is
270: refused, just as if \(dq\&iconv\(dq\& had been specified via \(dq\&refuse options\(dq\&.
271: .IP
272: If you wish to force users to always use \fB\-\-iconv\fP for a particular
273: module, add \(dq\&no\-iconv\(dq\& to the \(dq\&refuse options\(dq\& parameter. Keep in mind
274: that this will restrict access to your module to very new rsync clients.
275: .IP
276: .IP "\fBmax connections\fP"
277: This parameter allows you to
278: specify the maximum number of simultaneous connections you will allow.
279: Any clients connecting when the maximum has been reached will receive a
280: message telling them to try later. The default is 0, which means no limit.
281: A negative value disables the module.
282: See also the \(dq\&lock file\(dq\& parameter.
283: .IP
284: .IP "\fBlog file\fP"
285: When the \(dq\&log file\(dq\& parameter is set to a non\-empty
286: string, the rsync daemon will log messages to the indicated file rather
287: than using syslog. This is particularly useful on systems (such as AIX)
288: where
289: \f(CWsyslog()\fP
290: doesn\(cq\&t work for chrooted programs. The file is
291: opened before
292: \f(CWchroot()\fP
293: is called, allowing it to be placed outside
294: the transfer. If this value is set on a per\-module basis instead of
295: globally, the global log will still contain any authorization failures
296: or config\-file error messages.
297: .IP
298: If the daemon fails to open the specified file, it will fall back to
299: using syslog and output an error about the failure. (Note that the
300: failure to open the specified log file used to be a fatal error.)
301: .IP
302: .IP "\fBsyslog facility\fP"
303: This parameter allows you to
304: specify the syslog facility name to use when logging messages from the
305: rsync daemon. You may use any standard syslog facility name which is
306: defined on your system. Common names are auth, authpriv, cron, daemon,
307: ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0,
308: local1, local2, local3, local4, local5, local6 and local7. The default
309: is daemon. This setting has no effect if the \(dq\&log file\(dq\& setting is a
310: non\-empty string (either set in the per\-modules settings, or inherited
311: from the global settings).
312: .IP
313: .IP "\fBmax verbosity\fP"
314: This parameter allows you to control
315: the maximum amount of verbose information that you\(cq\&ll allow the daemon to
316: generate (since the information goes into the log file). The default is 1,
317: which allows the client to request one level of verbosity.
318: .IP
319: .IP "\fBlock file\fP"
320: This parameter specifies the file to use to
321: support the \(dq\&max connections\(dq\& parameter. The rsync daemon uses record
322: locking on this file to ensure that the max connections limit is not
323: exceeded for the modules sharing the lock file.
324: The default is \f(CW/var/run/rsyncd.lock\fP.
325: .IP
326: .IP "\fBread only\fP"
327: This parameter determines whether clients
328: will be able to upload files or not. If \(dq\&read only\(dq\& is true then any
329: attempted uploads will fail. If \(dq\&read only\(dq\& is false then uploads will
330: be possible if file permissions on the daemon side allow them. The default
331: is for all modules to be read only.
332: .IP
333: .IP "\fBwrite only\fP"
334: This parameter determines whether clients
335: will be able to download files or not. If \(dq\&write only\(dq\& is true then any
336: attempted downloads will fail. If \(dq\&write only\(dq\& is false then downloads
337: will be possible if file permissions on the daemon side allow them. The
338: default is for this parameter to be disabled.
339: .IP
340: .IP "\fBlist\fP"
341: This parameter determines if this module should be
342: listed when the client asks for a listing of available modules. By
343: setting this to false you can create hidden modules. The default is
344: for modules to be listable.
345: .IP
346: .IP "\fBuid\fP"
347: This parameter specifies the user name or user ID that
348: file transfers to and from that module should take place as when the daemon
349: was run as root. In combination with the \(dq\&gid\(dq\& parameter this determines what
350: file permissions are available. The default is uid \-2, which is normally
351: the user \(dq\&nobody\(dq\&.
352: .IP
353: .IP "\fBgid\fP"
354: This parameter specifies the group name or group ID that
355: file transfers to and from that module should take place as when the daemon
356: was run as root. This complements the \(dq\&uid\(dq\& parameter. The default is gid \-2,
357: which is normally the group \(dq\&nobody\(dq\&.
358: .IP
359: .IP "\fBfake super\fP"
360: Setting \(dq\&fake super = yes\(dq\& for a module causes the
361: daemon side to behave as if the \fB\-\-fake\-super\fP command\-line option had
362: been specified. This allows the full attributes of a file to be stored
363: without having to have the daemon actually running as root.
364: .IP
365: .IP "\fBfilter\fP"
366: The daemon has its own filter chain that determines what files
367: it will let the client access. This chain is not sent to the client and is
368: independent of any filters the client may have specified. Files excluded by
369: the daemon filter chain (\fBdaemon\-excluded\fP files) are treated as non\-existent
370: if the client tries to pull them, are skipped with an error message if the
371: client tries to push them (triggering exit code 23), and are never deleted from
372: the module. You can use daemon filters to prevent clients from downloading or
373: tampering with private administrative files, such as files you may add to
374: support uid/gid name translations.
375: .IP
376: The daemon filter chain is built from the \(dq\&filter\(dq\&, \(dq\&include from\(dq\&, \(dq\&include\(dq\&,
377: \(dq\&exclude from\(dq\&, and \(dq\&exclude\(dq\& parameters, in that order of priority. Anchored
378: patterns are anchored at the root of the module. To prevent access to an
379: entire subtree, for example, \(dq\&/secret\(dq\&, you \fImust\fP exclude everything in the
380: subtree; the easiest way to do this is with a triple\-star pattern like
381: \(dq\&/secret/***\(dq\&.
382: .IP
383: The \(dq\&filter\(dq\& parameter takes a space\-separated list of daemon filter rules,
384: though it is smart enough to know not to split a token at an internal space in
385: a rule (e.g. \(dq\&\- /foo \- /bar\(dq\& is parsed as two rules). You may specify one or
386: more merge\-file rules using the normal syntax. Only one \(dq\&filter\(dq\& parameter can
387: apply to a given module in the config file, so put all the rules you want in a
388: single parameter. Note that per\-directory merge\-file rules do not provide as
389: much protection as global rules, but they can be used to make \fB\-\-delete\fP work
390: better during a client download operation if the per\-dir merge files are
391: included in the transfer and the client requests that they be used.
392: .IP
393: .IP "\fBexclude\fP"
394: This parameter takes a space\-separated list of daemon
395: exclude patterns. As with the client \fB\-\-exclude\fP option, patterns can be
396: qualified with \(dq\&\- \(dq\& or \(dq\&+ \(dq\& to explicitly indicate exclude/include. Only one
397: \(dq\&exclude\(dq\& parameter can apply to a given module. See the \(dq\&filter\(dq\& parameter
398: for a description of how excluded files affect the daemon.
399: .IP
400: .IP "\fBinclude\fP"
401: Use an \(dq\&include\(dq\& to override the effects of the \(dq\&exclude\(dq\&
402: parameter. Only one \(dq\&include\(dq\& parameter can apply to a given module. See the
403: \(dq\&filter\(dq\& parameter for a description of how excluded files affect the daemon.
404: .IP
405: .IP "\fBexclude from\fP"
406: This parameter specifies the name of a file
407: on the daemon that contains daemon exclude patterns, one per line. Only one
408: \(dq\&exclude from\(dq\& parameter can apply to a given module; if you have multiple
409: exclude\-from files, you can specify them as a merge file in the \(dq\&filter\(dq\&
410: parameter. See the \(dq\&filter\(dq\& parameter for a description of how excluded files
411: affect the daemon.
412: .IP
413: .IP "\fBinclude from\fP"
414: Analogue of \(dq\&exclude from\(dq\& for a file of daemon include
415: patterns. Only one \(dq\&include from\(dq\& parameter can apply to a given module. See
416: the \(dq\&filter\(dq\& parameter for a description of how excluded files affect the
417: daemon.
418: .IP
419: .IP "\fBincoming chmod\fP"
420: This parameter allows you to specify a set of
421: comma\-separated chmod strings that will affect the permissions of all
422: incoming files (files that are being received by the daemon). These
423: changes happen after all other permission calculations, and this will
424: even override destination\-default and/or existing permissions when the
425: client does not specify \fB\-\-perms\fP.
426: See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
427: manpage for information on the format of this string.
428: .IP
429: .IP "\fBoutgoing chmod\fP"
430: This parameter allows you to specify a set of
431: comma\-separated chmod strings that will affect the permissions of all
432: outgoing files (files that are being sent out from the daemon). These
433: changes happen first, making the sent permissions appear to be different
434: than those stored in the filesystem itself. For instance, you could
435: disable group write permissions on the server while having it appear to
436: be on to the clients.
437: See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
438: manpage for information on the format of this string.
439: .IP
440: .IP "\fBauth users\fP"
441: This parameter specifies a comma and
442: space\-separated list of usernames that will be allowed to connect to
443: this module. The usernames do not need to exist on the local
444: system. The usernames may also contain shell wildcard characters. If
445: \(dq\&auth users\(dq\& is set then the client will be challenged to supply a
446: username and password to connect to the module. A challenge response
447: authentication protocol is used for this exchange. The plain text
448: usernames and passwords are stored in the file specified by the
449: \(dq\&secrets file\(dq\& parameter. The default is for all users to be able to
450: connect without a password (this is called \(dq\&anonymous rsync\(dq\&).
451: .IP
452: See also the section entitled \(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE
453: SHELL CONNECTION\(dq\& in \fBrsync\fP(1) for information on how handle an
454: rsyncd.conf\-level username that differs from the remote\-shell\-level
455: username when using a remote shell to connect to an rsync daemon.
456: .IP
457: .IP "\fBsecrets file\fP"
458: This parameter specifies the name of
459: a file that contains the username:password pairs used for
460: authenticating this module. This file is only consulted if the \(dq\&auth
461: users\(dq\& parameter is specified. The file is line based and contains
462: username:password pairs separated by a single colon. Any line starting
463: with a hash (#) is considered a comment and is skipped. The passwords
464: can contain any characters but be warned that many operating systems
465: limit the length of passwords that can be typed at the client end, so
466: you may find that passwords longer than 8 characters don\(cq\&t work.
467: .IP
468: There is no default for the \(dq\&secrets file\(dq\& parameter, you must choose a name
469: (such as \f(CW/etc/rsyncd.secrets\fP). The file must normally not be readable
470: by \(dq\&other\(dq\&; see \(dq\&strict modes\(dq\&.
471: .IP
472: .IP "\fBstrict modes\fP"
473: This parameter determines whether or not
474: the permissions on the secrets file will be checked. If \(dq\&strict modes\(dq\& is
475: true, then the secrets file must not be readable by any user ID other
476: than the one that the rsync daemon is running under. If \(dq\&strict modes\(dq\& is
477: false, the check is not performed. The default is true. This parameter
478: was added to accommodate rsync running on the Windows operating system.
479: .IP
480: .IP "\fBhosts allow\fP"
481: This parameter allows you to specify a
482: list of patterns that are matched against a connecting clients
483: hostname and IP address. If none of the patterns match then the
484: connection is rejected.
485: .IP
486: Each pattern can be in one of five forms:
487: .IP
488: .RS
489: .IP o
490: a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address
491: of the form a:b:c::d:e:f. In this case the incoming machine\(cq\&s IP address
492: must match exactly.
493: .IP o
494: an address/mask in the form ipaddr/n where ipaddr is the IP address
495: and n is the number of one bits in the netmask. All IP addresses which
496: match the masked IP address will be allowed in.
497: .IP o
498: an address/mask in the form ipaddr/maskaddr where ipaddr is the
499: IP address and maskaddr is the netmask in dotted decimal notation for IPv4,
500: or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
501: addresses which match the masked IP address will be allowed in.
502: .IP o
503: a hostname. The hostname as determined by a reverse lookup will
504: be matched (case insensitive) against the pattern. Only an exact
505: match is allowed in.
506: .IP o
507: a hostname pattern using wildcards. These are matched using the
508: same rules as normal unix filename matching. If the pattern matches
509: then the client is allowed in.
510: .RE
511:
512: .IP
513: Note IPv6 link\-local addresses can have a scope in the address specification:
514: .IP
515: .RS
516: \f(CW fe80::1%link1\fP
517: .br
518: \f(CW fe80::%link1/64\fP
519: .br
520: \f(CW fe80::%link1/ffff:ffff:ffff:ffff::\fP
521: .br
522: .RE
523:
524: .IP
525: You can also combine \(dq\&hosts allow\(dq\& with a separate \(dq\&hosts deny\(dq\&
526: parameter. If both parameters are specified then the \(dq\&hosts allow\(dq\& parameter is
527: checked first and a match results in the client being able to
528: connect. The \(dq\&hosts deny\(dq\& parameter is then checked and a match means
529: that the host is rejected. If the host does not match either the
530: \(dq\&hosts allow\(dq\& or the \(dq\&hosts deny\(dq\& patterns then it is allowed to
531: connect.
532: .IP
533: The default is no \(dq\&hosts allow\(dq\& parameter, which means all hosts can connect.
534: .IP
535: .IP "\fBhosts deny\fP"
536: This parameter allows you to specify a
537: list of patterns that are matched against a connecting clients
538: hostname and IP address. If the pattern matches then the connection is
539: rejected. See the \(dq\&hosts allow\(dq\& parameter for more information.
540: .IP
541: The default is no \(dq\&hosts deny\(dq\& parameter, which means all hosts can connect.
542: .IP
543: .IP "\fBignore errors\fP"
544: This parameter tells rsyncd to
545: ignore I/O errors on the daemon when deciding whether to run the delete
546: phase of the transfer. Normally rsync skips the \fB\-\-delete\fP step if any
547: I/O errors have occurred in order to prevent disastrous deletion due
548: to a temporary resource shortage or other I/O error. In some cases this
549: test is counter productive so you can use this parameter to turn off this
550: behavior.
551: .IP
552: .IP "\fBignore nonreadable\fP"
553: This tells the rsync daemon to completely
554: ignore files that are not readable by the user. This is useful for
555: public archives that may have some non\-readable files among the
556: directories, and the sysadmin doesn\(cq\&t want those files to be seen at all.
557: .IP
558: .IP "\fBtransfer logging\fP"
559: This parameter enables per\-file
560: logging of downloads and uploads in a format somewhat similar to that
561: used by ftp daemons. The daemon always logs the transfer at the end, so
562: if a transfer is aborted, no mention will be made in the log file.
563: .IP
564: If you want to customize the log lines, see the \(dq\&log format\(dq\& parameter.
565: .IP
566: .IP "\fBlog format\fP"
567: This parameter allows you to specify the
568: format used for logging file transfers when transfer logging is enabled.
569: The format is a text string containing embedded single\-character escape
570: sequences prefixed with a percent (%) character. An optional numeric
571: field width may also be specified between the percent and the escape
572: letter (e.g. \(dq\&\fB%\-50n %8l %07p\fP\(dq\&).
573: .IP
574: The default log format is \(dq\&%o %h [%a] %m (%u) %f %l\(dq\&, and a \(dq\&%t [%p] \(dq\&
575: is always prefixed when using the \(dq\&log file\(dq\& parameter.
576: (A perl script that will summarize this default log format is included
577: in the rsync source code distribution in the \(dq\&support\(dq\& subdirectory:
578: rsyncstats.)
579: .IP
580: The single\-character escapes that are understood are as follows:
581: .IP
582: .RS
583: .IP o
584: %a the remote IP address
585: .IP o
586: %b the number of bytes actually transferred
587: .IP o
588: %B the permission bits of the file (e.g. rwxrwxrwt)
589: .IP o
590: %c the total size of the block checksums received for the basis file (only when sending)
591: .IP o
592: %f the filename (long form on sender; no trailing \(dq\&/\(dq\&)
593: .IP o
594: %G the gid of the file (decimal) or \(dq\&DEFAULT\(dq\&
595: .IP o
596: %h the remote host name
597: .IP o
598: %i an itemized list of what is being updated
599: .IP o
600: %l the length of the file in bytes
601: .IP o
602: %L the string \(dq\& \-> SYMLINK\(dq\&, \(dq\& => HARDLINK\(dq\&, or \(dq\&\(dq\& (where \fBSYMLINK\fP or \fBHARDLINK\fP is a filename)
603: .IP o
604: %m the module name
605: .IP o
606: %M the last\-modified time of the file
607: .IP o
608: %n the filename (short form; trailing \(dq\&/\(dq\& on dir)
609: .IP o
610: %o the operation, which is \(dq\&send\(dq\&, \(dq\&recv\(dq\&, or \(dq\&del.\(dq\& (the latter includes the trailing period)
611: .IP o
612: %p the process ID of this rsync session
613: .IP o
614: %P the module path
615: .IP o
616: %t the current date time
617: .IP o
618: %u the authenticated username or an empty string
619: .IP o
620: %U the uid of the file (decimal)
621: .RE
622:
623: .IP
624: For a list of what the characters mean that are output by \(dq\&%i\(dq\&, see the
625: \fB\-\-itemize\-changes\fP option in the rsync manpage.
626: .IP
627: Note that some of the logged output changes when talking with older
628: rsync versions. For instance, deleted files were only output as verbose
629: messages prior to rsync 2.6.4.
630: .IP
631: .IP "\fBtimeout\fP"
632: This parameter allows you to override the
633: clients choice for I/O timeout for this module. Using this parameter you
634: can ensure that rsync won\(cq\&t wait on a dead client forever. The timeout
635: is specified in seconds. A value of zero means no timeout and is the
636: default. A good choice for anonymous rsync daemons may be 600 (giving
637: a 10 minute timeout).
638: .IP
639: .IP "\fBrefuse options\fP"
640: This parameter allows you to
641: specify a space\-separated list of rsync command line options that will
642: be refused by your rsync daemon.
643: You may specify the full option name, its one\-letter abbreviation, or a
644: wild\-card string that matches multiple options.
645: For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various
646: delete options:
647: .IP
648: .RS
649: \f(CW refuse options = c delete\fP
650: .RE
651:
652: .IP
653: The reason the above refuses all delete options is that the options imply
654: \fB\-\-delete\fP, and implied options are refused just like explicit options.
655: As an additional safety feature, the refusal of \(dq\&delete\(dq\& also refuses
656: \fBremove\-source\-files\fP when the daemon is the sender; if you want the latter
657: without the former, instead refuse \(dq\&delete\-*\(dq\& \-\- that refuses all the
658: delete modes without affecting \fB\-\-remove\-source\-files\fP.
659: .IP
660: When an option is refused, the daemon prints an error message and exits.
661: To prevent all compression when serving files,
662: you can use \(dq\&dont compress = *\(dq\& (see below)
663: instead of \(dq\&refuse options = compress\(dq\& to avoid returning an error to a
664: client that requests compression.
665: .IP
666: .IP "\fBdont compress\fP"
667: This parameter allows you to select
668: filenames based on wildcard patterns that should not be compressed
669: when pulling files from the daemon (no analogous parameter exists to
670: govern the pushing of files to a daemon).
671: Compression is expensive in terms of CPU usage, so it
672: is usually good to not try to compress files that won\(cq\&t compress well,
673: such as already compressed files.
674: .IP
675: The \(dq\&dont compress\(dq\& parameter takes a space\-separated list of
676: case\-insensitive wildcard patterns. Any source filename matching one
677: of the patterns will not be compressed during transfer.
678: .IP
679: See the \fB\-\-skip\-compress\fP parameter in the \fBrsync\fP(1) manpage for the list
680: of file suffixes that are not compressed by default. Specifying a value
681: for the \(dq\&dont compress\(dq\& parameter changes the default when the daemon is
682: the sender.
683: .IP
684: .IP "\fBpre\-xfer exec\fP, \fBpost\-xfer exec\fP"
685: You may specify a command to be run
686: before and/or after the transfer. If the \fBpre\-xfer exec\fP command fails, the
687: transfer is aborted before it begins.
688: .IP
689: The following environment variables will be set, though some are
690: specific to the pre\-xfer or the post\-xfer environment:
691: .IP
692: .RS
693: .IP o
694: \fBRSYNC_MODULE_NAME\fP: The name of the module being accessed.
695: .IP o
696: \fBRSYNC_MODULE_PATH\fP: The path configured for the module.
697: .IP o
698: \fBRSYNC_HOST_ADDR\fP: The accessing host\(cq\&s IP address.
699: .IP o
700: \fBRSYNC_HOST_NAME\fP: The accessing host\(cq\&s name.
701: .IP o
702: \fBRSYNC_USER_NAME\fP: The accessing user\(cq\&s name (empty if no user).
703: .IP o
704: \fBRSYNC_PID\fP: A unique number for this transfer.
705: .IP o
706: \fBRSYNC_REQUEST\fP: (pre\-xfer only) The module/path info specified
707: by the user (note that the user can specify multiple source files,
708: so the request can be something like \(dq\&mod/path1 mod/path2\(dq\&, etc.).
709: .IP o
710: \fBRSYNC_ARG#\fP: (pre\-xfer only) The pre\-request arguments are set
711: in these numbered values. RSYNC_ARG0 is always \(dq\&rsyncd\(dq\&, and the last
712: value contains a single period.
713: .IP o
714: \fBRSYNC_EXIT_STATUS\fP: (post\-xfer only) the server side\(cq\&s exit value.
715: This will be 0 for a successful run, a positive value for an error that the
716: server generated, or a \-1 if rsync failed to exit properly. Note that an
717: error that occurs on the client side does not currently get sent to the
718: server side, so this is not the final exit status for the whole transfer.
719: .IP o
720: \fBRSYNC_RAW_STATUS\fP: (post\-xfer only) the raw exit value from
721: \f(CWwaitpid()\fP
722: \&.
723: .RE
724:
725: .IP
726: Even though the commands can be associated with a particular module, they
727: are run using the permissions of the user that started the daemon (not the
728: module\(cq\&s uid/gid setting) without any chroot restrictions.
729: .IP
730: .SH "AUTHENTICATION STRENGTH"
731:
732: .PP
733: The authentication protocol used in rsync is a 128 bit MD4 based
734: challenge response system. This is fairly weak protection, though (with
735: at least one brute\-force hash\-finding algorithm publicly available), so
736: if you want really top\-quality security, then I recommend that you run
737: rsync over ssh. (Yes, a future version of rsync will switch over to a
738: stronger hashing method.)
739: .PP
740: Also note that the rsync daemon protocol does not currently provide any
741: encryption of the data that is transferred over the connection. Only
742: authentication is provided. Use ssh as the transport if you want
743: encryption.
744: .PP
745: Future versions of rsync may support SSL for better authentication and
746: encryption, but that is still being investigated.
747: .PP
748: .SH "EXAMPLES"
749:
750: .PP
751: A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
752: \f(CW/home/ftp\fP would be:
753: .PP
754: .nf
755:
756: [ftp]
757: path = /home/ftp
758: comment = ftp export area
759:
760: .fi
761:
762: .PP
763: A more sophisticated example would be:
764: .PP
765: .nf
766:
767: uid = nobody
768: gid = nobody
769: use chroot = yes
770: max connections = 4
771: syslog facility = local5
772: pid file = /var/run/rsyncd.pid
773:
774: [ftp]
775: path = /var/ftp/./pub
776: comment = whole ftp area (approx 6.1 GB)
777:
778: [sambaftp]
779: path = /var/ftp/./pub/samba
780: comment = Samba ftp area (approx 300 MB)
781:
782: [rsyncftp]
783: path = /var/ftp/./pub/rsync
784: comment = rsync ftp area (approx 6 MB)
785:
786: [sambawww]
787: path = /public_html/samba
788: comment = Samba WWW pages (approx 240 MB)
789:
790: [cvs]
791: path = /data/cvs
792: comment = CVS repository (requires authentication)
793: auth users = tridge, susan
794: secrets file = /etc/rsyncd.secrets
795:
796: .fi
797:
798: .PP
799: The /etc/rsyncd.secrets file would look something like this:
800: .PP
801: .RS
802: \f(CWtridge:mypass\fP
803: .br
804: \f(CWsusan:herpass\fP
805: .br
806: .RE
807:
808: .PP
809: .SH "FILES"
810:
811: .PP
812: /etc/rsyncd.conf or rsyncd.conf
813: .PP
814: .SH "SEE ALSO"
815:
816: .PP
817: \fBrsync\fP(1)
818: .PP
819: .SH "DIAGNOSTICS"
820:
821: .PP
822: .SH "BUGS"
823:
824: .PP
825: Please report bugs! The rsync bug tracking system is online at
826: http://rsync.samba.org/
827: .PP
828: .SH "VERSION"
829:
830: .PP
831: This man page is current for version 3.0.9 of rsync.
832: .PP
833: .SH "CREDITS"
834:
835: .PP
836: rsync is distributed under the GNU public license. See the file
837: COPYING for details.
838: .PP
839: The primary ftp site for rsync is
840: ftp://rsync.samba.org/pub/rsync.
841: .PP
842: A WEB site is available at
843: http://rsync.samba.org/
844: .PP
845: We would be delighted to hear from you if you like this program.
846: .PP
847: This program uses the zlib compression library written by Jean\-loup
848: Gailly and Mark Adler.
849: .PP
850: .SH "THANKS"
851:
852: .PP
853: Thanks to Warren Stanley for his original idea and patch for the rsync
854: daemon. Thanks to Karsten Thygesen for his many suggestions and
855: documentation!
856: .PP
857: .SH "AUTHOR"
858:
859: .PP
860: rsync was written by Andrew Tridgell and Paul Mackerras.
861: Many people have later contributed to it.
862: .PP
863: Mailing lists for support and development are available at
864: http://lists.samba.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rsyncd.conf.5 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync