1: .TH "rsyncd.conf" "5" "06 Aug 2020" "rsyncd.conf 3.2.3" "User Commands"
2: .P
3: .SH "NAME"
4: .P
5: rsyncd.conf \- configuration file for rsync in daemon mode
6: .P
7: .SH "SYNOPSIS"
8: .P
9: rsyncd.conf
10: .P
11: .SH "DESCRIPTION"
12: .P
13: The rsyncd.conf file is the runtime configuration file for rsync when run as an
14: rsync daemon.
15: .P
16: The rsyncd.conf file controls authentication, access, logging and available
17: modules.
18: .P
19: .SH "FILE FORMAT"
20: .P
21: The file consists of modules and parameters. A module begins with the name of
22: the module in square brackets and continues until the next module begins.
23: Modules contain parameters of the form \fBname\ =\ value\fP.
24: .P
25: The file is line-based\ \-\- that is, each newline-terminated line represents
26: either a comment, a module name or a parameter.
27: .P
28: Only the first equals sign in a parameter is significant. Whitespace before or
29: after the first equals sign is discarded. Leading, trailing and internal
30: whitespace in module and parameter names is irrelevant. Leading and trailing
31: whitespace in a parameter value is discarded. Internal whitespace within a
32: parameter value is retained verbatim.
33: .P
34: Any line \fBbeginning\fP with a hash (\fB#\fP) is ignored, as are lines containing
35: only whitespace. (If a hash occurs after anything other than leading
36: whitespace, it is considered a part of the line's content.)
37: .P
38: Any line ending in a \fB\\\fP is "continued" on the next line in the customary UNIX
39: fashion.
40: .P
41: The values following the equals sign in parameters are all either a string (no
42: quotes needed) or a boolean, which may be given as yes/no, 0/1 or true/false.
43: Case is not significant in boolean values, but is preserved in string values.
44: .P
45: .SH "LAUNCHING THE RSYNC DAEMON"
46: .P
47: The rsync daemon is launched by specifying the \fB\-\-daemon\fP option to
48: rsync.
49: .P
50: The daemon must run with root privileges if you wish to use chroot, to bind to
51: a port numbered under 1024 (as is the default 873), or to set file ownership.
52: Otherwise, it must just have permission to read and write the appropriate data,
53: log, and lock files.
54: .P
55: You can launch it either via inetd, as a stand-alone daemon, or from an rsync
56: client via a remote shell. If run as a stand-alone daemon then just run the
57: command "\fBrsync\ \-\-daemon\fP" from a suitable startup script.
58: .P
59: When run via inetd you should add a line like this to /etc/services:
60: .RS 4
61: .P
62: .nf
63: rsync 873/tcp
64: .fi
65: .RE
66: .P
67: and a single line something like this to /etc/inetd.conf:
68: .RS 4
69: .P
70: .nf
71: rsync stream tcp nowait root /usr/bin/rsync rsyncd --daemon
72: .fi
73: .RE
74: .P
75: Replace "/usr/bin/rsync" with the path to where you have rsync installed on
76: your system. You will then need to send inetd a HUP signal to tell it to
77: reread its config file.
78: .P
79: Note that you should \fBnot\fP send the rsync daemon a HUP signal to force it to
80: reread the \fBrsyncd.conf\fP file. The file is re-read on each client connection.
81: .P
82: .SH "GLOBAL PARAMETERS"
83: .P
84: The first parameters in the file (before a [module] header) are the global
85: parameters. Rsync also allows for the use of a "[global]" module name to
86: indicate the start of one or more global-parameter sections (the name must be
87: lower case).
88: .P
89: You may also include any module parameters in the global part of the config
90: file in which case the supplied value will override the default for that
91: parameter.
92: .P
93: You may use references to environment variables in the values of parameters.
94: String parameters will have %VAR% references expanded as late as possible (when
95: the string is first used in the program), allowing for the use of variables
96: that rsync sets at connection time, such as RSYNC_USER_NAME. Non-string
97: parameters (such as true/false settings) are expanded when read from the config
98: file. If a variable does not exist in the environment, or if a sequence of
99: characters is not a valid reference (such as an un-paired percent sign), the
100: raw characters are passed through unchanged. This helps with backward
101: compatibility and safety (e.g. expanding a non-existent %VAR% to an empty
102: string in a path could result in a very unsafe path). The safest way to insert
103: a literal % into a value is to use %%.
104: .P
105: .IP "\fBmotd\ file\fP"
106: This parameter allows you to specify a "message of the day" to display to
107: clients on each connect. This usually contains site information and any
108: legal notices. The default is no motd file. This can be overridden by the
109: \fB\-\-dparam=motdfile=FILE\fP command-line option when starting the daemon.
110: .IP "\fBpid\ file\fP"
111: This parameter tells the rsync daemon to write its process ID to that file.
112: The rsync keeps the file locked so that it can know when it is safe to
113: overwrite an existing file.
114: .IP
115: The filename can be overridden by the \fB\-\-dparam=pidfile=FILE\fP command-line
116: option when starting the daemon.
117: .IP "\fBport\fP"
118: You can override the default port the daemon will listen on by specifying
119: this value (defaults to 873). This is ignored if the daemon is being run
120: by inetd, and is superseded by the \fB\-\-port\fP command-line option.
121: .IP "\fBaddress\fP"
122: You can override the default IP address the daemon will listen on by
123: specifying this value. This is ignored if the daemon is being run by
124: inetd, and is superseded by the \fB\-\-address\fP command-line option.
125: .IP "\fBsocket\ options\fP"
126: This parameter can provide endless fun for people who like to tune their
127: systems to the utmost degree. You can set all sorts of socket options which
128: may make transfers faster (or slower!). Read the man page for the
129: \fBsetsockopt()\fP system call for details on some of the options you may be
130: able to set. By default no special socket options are set. These settings
131: can also be specified via the \fB\-\-sockopts\fP command-line option.
132: .IP "\fBlisten\ backlog\fP"
133: You can override the default backlog value when the daemon listens for
134: connections. It defaults to 5.
135: .IP "\fBuse\ slp\fP"
136: You can enable Service Location Protocol support by enabling this global
137: parameter. The default is "false".
138: .IP "\fBslp\ refresh\fP"
139: This parameter is used to determine how long service advertisements are
140: valid (measured in seconds), and is only applicable if you have Service
141: Location Protocol support compiled in. If this is not set or is set to
142: zero, then service advertisements never time out. If this is set to less
143: than 120 seconds, then 120 seconds is used. If it is set to more than
144: 65535, then 65535 is used (which is a limitation of SLP). Using 3600
145: (one hour) is a good number if you tend to change your configuration.
146: .P
147: .SH "MODULE PARAMETERS"
148: .P
149: After the global parameters you should define a number of modules, each module
150: exports a directory tree as a symbolic name. Modules are exported by specifying
151: a module name in square brackets [module] followed by the parameters for that
152: module. The module name cannot contain a slash or a closing square bracket.
153: If the name contains whitespace, each internal sequence of whitespace will be
154: changed into a single space, while leading or trailing whitespace will be
155: discarded. Also, the name cannot be "global" as that exact name indicates that
156: global parameters follow (see above).
157: .P
158: As with GLOBAL PARAMETERS, you may use references to environment variables in
159: the values of parameters. See the GLOBAL PARAMETERS section for more details.
160: .P
161: .IP "\fBcomment\fP"
162: This parameter specifies a description string that is displayed next to the
163: module name when clients obtain a list of available modules. The default is
164: no comment.
165: .IP "\fBpath\fP"
166: This parameter specifies the directory in the daemon's filesystem to make
167: available in this module. You must specify this parameter for each module
168: in \fBrsyncd.conf\fP.
169: .IP
170: You may base the path's value off of an environment variable by surrounding
171: the variable name with percent signs. You can even reference a variable
172: that is set by rsync when the user connects. For example, this would use
173: the authorizing user's name in the path:
174: .RS 4
175: .IP
176: .nf
177: path = /home/%RSYNC_USER_NAME%
178: .fi
179: .RE
180: .IP
181: It is fine if the path includes internal spaces\ \-\- they will be retained
182: verbatim (which means that you shouldn't try to escape them). If your
183: final directory has a trailing space (and this is somehow not something you
184: wish to fix), append a trailing slash to the path to avoid losing the
185: trailing whitespace.
186: .IP "\fBuse\ chroot\fP"
187: If "use chroot" is true, the rsync daemon will chroot to the "path" before
188: starting the file transfer with the client. This has the advantage of
189: extra protection against possible implementation security holes, but it has
190: the disadvantages of requiring super-user privileges, of not being able to
191: follow symbolic links that are either absolute or outside of the new root
192: path, and of complicating the preservation of users and groups by name (see
193: below).
194: .IP
195: As an additional safety feature, you can specify a dot-dir in the module's
196: "path" to indicate the point where the chroot should occur. This allows
197: rsync to run in a chroot with a non-"/" path for the top of the transfer
198: hierarchy. Doing this guards against unintended library loading (since
199: those absolute paths will not be inside the transfer hierarchy unless you
200: have used an unwise pathname), and lets you setup libraries for the chroot
201: that are outside of the transfer. For example, specifying
202: "/var/rsync/./module1" will chroot to the "/var/rsync" directory and set
203: the inside-chroot path to "/module1". If you had omitted the dot-dir, the
204: chroot would have used the whole path, and the inside-chroot path would
205: have been "/".
206: .IP
207: When both "use chroot" and "daemon chroot" are false, OR the inside-chroot
208: path of "use chroot" is not "/", rsync will: (1) munge symlinks by default
209: for security reasons (see "munge symlinks" for a way to turn this off, but
210: only if you trust your users), (2) substitute leading slashes in absolute
211: paths with the module's path (so that options such as \fB\-\-backup-dir\fP,
212: \fB\-\-compare-dest\fP, etc. interpret an absolute path as rooted in the module's
213: "path" dir), and (3) trim ".." path elements from args if rsync believes
214: they would escape the module hierarchy. The default for "use chroot" is
215: true, and is the safer choice (especially if the module is not read-only).
216: .IP
217: When this parameter is enabled \fIand\fP the "name converter" parameter is
218: \fInot\fP set, the "numeric ids" parameter will default to being enabled
219: (disabling name lookups). This means that if you manually setup
220: name-lookup libraries in your chroot (instead of using a name converter)
221: that you need to explicitly set \fBnumeric\ ids\ =\ false\fP for rsync to do name
222: lookups.
223: .IP
224: If you copy library resources into the module's chroot area, you should
225: protect them through your OS's normal user/group or ACL settings (to
226: prevent the rsync module's user from being able to change them), and then
227: hide them from the user's view via "exclude" (see how in the discussion of
228: that parameter). However, it's easier and safer to setup a name converter.
229: .IP "\fBdaemon\ chroot\fP"
230: This parameter specifies a path to which the daemon will chroot before
231: beginning communication with clients. Module paths (and any "use chroot"
232: settings) will then be related to this one. This lets you choose if you
233: want the whole daemon to be chrooted (with this setting), just the
234: transfers to be chrooted (with "use chroot"), or both. Keep in mind that
235: the "daemon chroot" area may need various OS/lib/etc files installed to
236: allow the daemon to function. By default the daemon runs without any
237: chrooting.
238: .IP "\fBproxy\ protocol\fP"
239: When this parameter is enabled, all incoming connections must start with a
240: V1 or V2 proxy protocol header. If the header is not found, the connection
241: is closed.
242: .IP
243: Setting this to \fBtrue\fP requires a proxy server to forward source IP
244: information to rsync, allowing you to log proper IP/host info and make use
245: of client-oriented IP restrictions. The default of \fBfalse\fP means that the
246: IP information comes directly from the socket's metadata. If rsync is not
247: behind a proxy, this should be disabled.
248: .IP
249: \fICAUTION\fP: using this option can be dangerous if you do not ensure that
250: only the proxy is allowed to connect to the rsync port. If any non-proxied
251: connections are allowed through, the client will be able to use a modified
252: rsync to spoof any remote IP address that they desire. You can lock this
253: down using something like iptables \fB\-uid-owner\ root\fP rules (for strict
254: localhost access), various firewall rules, or you can require password
255: authorization so that any spoofing by users will not grant extra access.
256: .IP
257: This setting is global. If you need some modules to require this and not
258: others, then you will need to setup multiple rsync daemon processes on
259: different ports.
260: .IP "\fBname\ converter\fP"
261: This parameter lets you specify a program that will be run by the rsync
262: daemon to do user & group conversions between names & ids. This script
263: is started prior to any chroot being setup, and runs as the daemon user
264: (not the transfer user). You can specify a fully qualified pathname or
265: a program name that is on the $PATH.
266: .IP
267: The program can be used to do normal user & group lookups without having to
268: put any extra files into the chroot area of the module \fIor\fP you can do
269: customized conversions.
270: .IP
271: The nameconvert program has access to all of the environment variables that
272: are described in the section on \fBpre-xfer\ exec\fP. This is useful if you
273: want to customize the conversion using information about the module and/or
274: the copy request.
275: .IP
276: There is a sample python script in the support dir named "nameconvert" that
277: implements the normal user & group lookups. Feel free to customize it or
278: just use it as documentation to implement your own.
279: .IP "\fBnumeric\ ids\fP"
280: Enabling this parameter disables the mapping of users and groups by name
281: for the current daemon module. This prevents the daemon from trying to
282: load any user/group-related files or libraries. This enabling makes the
283: transfer behave as if the client had passed the \fB\-\-numeric-ids\fP
284: command-line option. By default, this parameter is enabled for chroot
285: modules and disabled for non-chroot modules. Also keep in mind that
286: uid/gid preservation requires the module to be running as root (see "uid")
287: or for "fake super" to be configured.
288: .IP
289: A chroot-enabled module should not have this parameter set to false unless
290: you're using a "name converter" program \fIor\fP you've taken steps to ensure
291: that the module has the necessary resources it needs to translate names and
292: that it is not possible for a user to change those resources.
293: .IP "\fBmunge\ symlinks\fP"
294: This parameter tells rsync to modify all symlinks in the same way as the
295: (non-daemon-affecting) \fB\-\-munge-links\fP command-line option (using a method
296: described below). This should help protect your files from user trickery
297: when your daemon module is writable. The default is disabled when
298: "use chroot" is on with an inside-chroot path of "/", OR if "daemon chroot"
299: is on, otherwise it is enabled.
300: .IP
301: If you disable this parameter on a daemon that is not read-only, there are
302: tricks that a user can play with uploaded symlinks to access
303: daemon-excluded items (if your module has any), and, if "use chroot" is
304: off, rsync can even be tricked into showing or changing data that is
305: outside the module's path (as access-permissions allow).
306: .IP
307: The way rsync disables the use of symlinks is to prefix each one with the
308: string "/rsyncd-munged/". This prevents the links from being used as long
309: as that directory does not exist. When this parameter is enabled, rsync
310: will refuse to run if that path is a directory or a symlink to a directory.
311: When using the "munge symlinks" parameter in a chroot area that has an
312: inside-chroot path of "/", you should add "/rsyncd-munged/" to the exclude
313: setting for the module so that a user can't try to create it.
314: .IP
315: Note: rsync makes no attempt to verify that any pre-existing symlinks in
316: the module's hierarchy are as safe as you want them to be (unless, of
317: course, it just copied in the whole hierarchy). If you setup an rsync
318: daemon on a new area or locally add symlinks, you can manually protect your
319: symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
320: every symlink's value. There is a perl script in the support directory of
321: the source code named "munge-symlinks" that can be used to add or remove
322: this prefix from your symlinks.
323: .IP
324: When this parameter is disabled on a writable module and "use chroot" is
325: off (or the inside-chroot path is not "/"), incoming symlinks will be
326: modified to drop a leading slash and to remove ".." path elements that
327: rsync believes will allow a symlink to escape the module's hierarchy.
328: There are tricky ways to work around this, though, so you had better trust
329: your users if you choose this combination of parameters.
330: .IP "\fBcharset\fP"
331: This specifies the name of the character set in which the module's
332: filenames are stored. If the client uses an \fB\-\-iconv\fP option, the daemon
333: will use the value of the "charset" parameter regardless of the character
334: set the client actually passed. This allows the daemon to support charset
335: conversion in a chroot module without extra files in the chroot area, and
336: also ensures that name-translation is done in a consistent manner. If the
337: "charset" parameter is not set, the \fB\-\-iconv\fP option is refused, just as if
338: "iconv" had been specified via "refuse options".
339: .IP
340: If you wish to force users to always use \fB\-\-iconv\fP for a particular module,
341: add "no-iconv" to the "refuse options" parameter. Keep in mind that this
342: will restrict access to your module to very new rsync clients.
343: .IP "\fBmax\ connections\fP"
344: This parameter allows you to specify the maximum number of simultaneous
345: connections you will allow. Any clients connecting when the maximum has
346: been reached will receive a message telling them to try later. The default
347: is 0, which means no limit. A negative value disables the module. See
348: also the "lock file" parameter.
349: .IP "\fBlink\ by\ hash\ dir\fP"
350: When the "link by hash dir" parameter is set to a non-empty string,
351: received files will be hard linked into \fBDIR\fP, a link farm arranged by
352: MD5 file hash. See the \fB\-\-link-by-hash\fP option for a full explanation.
353: .IP
354: The \fBDIR\fP must be accessible inside any chroot restrictions for the
355: module, but can exist outside the transfer location if there is an
356: inside-the-chroot path to the module (see "use chroot"). Note that a
357: user-specified option does not allow this outside-the-transfer-area
358: placement.
359: .IP
360: If this parameter is set, it will disable the \fB\-\-link-by-hash\fP command-line
361: option for copies into the module.
362: .P
363: The default is for this parameter to be unset.
364: .P
365: .IP "\fBlog\ file\fP"
366: When the "log file" parameter is set to a non-empty string, the rsync
367: daemon will log messages to the indicated file rather than using syslog.
368: This is particularly useful on systems (such as AIX) where \fBsyslog()\fP
369: doesn't work for chrooted programs. The file is opened before \fBchroot()\fP
370: is called, allowing it to be placed outside the transfer. If this value is
371: set on a per-module basis instead of globally, the global log will still
372: contain any authorization failures or config-file error messages.
373: .IP
374: If the daemon fails to open the specified file, it will fall back to using
375: syslog and output an error about the failure. (Note that the failure to
376: open the specified log file used to be a fatal error.)
377: .IP
378: This setting can be overridden by using the \fB\-\-log-file=FILE\fP or
379: \fB\-\-dparam=logfile=FILE\fP command-line options. The former overrides all the
380: log-file parameters of the daemon and all module settings. The latter sets
381: the daemon's log file and the default for all the modules, which still
382: allows modules to override the default setting.
383: .IP "\fBsyslog\ facility\fP"
384: This parameter allows you to specify the syslog facility name to use when
385: logging messages from the rsync daemon. You may use any standard syslog
386: facility name which is defined on your system. Common names are auth,
387: authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user,
388: uucp, local0, local1, local2, local3, local4, local5, local6 and local7.
389: The default is daemon. This setting has no effect if the "log file"
390: setting is a non-empty string (either set in the per-modules settings, or
391: inherited from the global settings).
392: .IP "\fBsyslog\ tag\fP"
393: This parameter allows you to specify the syslog tag to use when logging
394: messages from the rsync daemon. The default is "rsyncd". This setting has
395: no effect if the "log file" setting is a non-empty string (either set in
396: the per-modules settings, or inherited from the global settings).
397: .IP
398: For example, if you wanted each authenticated user's name to be included in
399: the syslog tag, you could do something like this:
400: .RS 4
401: .IP
402: .nf
403: syslog tag = rsyncd.%RSYNC_USER_NAME%
404: .fi
405: .RE
406: .IP "\fBmax\ verbosity\fP"
407: This parameter allows you to control the maximum amount of verbose
408: information that you'll allow the daemon to generate (since the information
409: goes into the log file). The default is 1, which allows the client to
410: request one level of verbosity.
411: .IP
412: This also affects the user's ability to request higher levels of \fB\-\-info\fP
413: and \fB\-\-debug\fP logging. If the max value is 2, then no info and/or debug
414: value that is higher than what would be set by \fB\-vv\fP will be honored by the
415: daemon in its logging. To see how high of a verbosity level you need to
416: accept for a particular info/debug level, refer to \fBrsync\ \-\-info=help\fP and
417: \fBrsync\ \-\-debug=help\fP. For instance, it takes max-verbosity 4 to be able to
418: output debug TIME2 and FLIST3.
419: .IP "\fBlock\ file\fP"
420: This parameter specifies the file to use to support the "max connections"
421: parameter. The rsync daemon uses record locking on this file to ensure that
422: the max connections limit is not exceeded for the modules sharing the lock
423: file. The default is \fB/var/run/rsyncd.lock\fP.
424: .IP "\fBchecksum\ files\fP"
425: This parameter tells rsync to make use of any cached checksum information
426: it finds in per-directory .rsyncsums files when the current transfer is
427: using the \fB\-\-checksum\fP option. The value can be set to either "lax",
428: "strict", "+lax", "+strict", "++lax", "++strict", or +"none". See the
429: client's \fB\-\-sumfiles\fP option for what these choices do.
430: .IP
431: Note also that the client's command-line option, \fB\-\-sumfiles\fP, has no
432: effect on a daemon. A daemon will only access checksum files if this
433: config option tells it to. You can configure updating of the .rsyncsums
434: files even if the module itself is configured to be read-only. See also
435: the \fBexclude\fP directive for a way to hide the .rsyncsums files from the
436: user.
437: .IP "\fBread\ only\fP"
438: This parameter determines whether clients will be able to upload files or
439: not. If "read only" is true then any attempted uploads will fail. If
440: "read only" is false then uploads will be possible if file permissions on
441: the daemon side allow them. The default is for all modules to be read only.
442: .IP
443: Note that "auth users" can override this setting on a per-user basis.
444: .IP "\fBwrite\ only\fP"
445: This parameter determines whether clients will be able to download files or
446: not. If "write only" is true then any attempted downloads will fail. If
447: "write only" is false then downloads will be possible if file permissions
448: on the daemon side allow them. The default is for this parameter to be
449: disabled.
450: .IP
451: Helpful hint: you probably want to specify "refuse options = delete" for a
452: write-only module.
453: .IP "\fBopen\ noatime\fP"
454: When set to True, this parameter tells the rsync daemon to open files with
455: the O_NOATIME flag
456: (on systems that support it) to avoid changing the access time of the files
457: that are being transferred. If your OS does not support the O_NOATIME flag
458: then rsync will silently ignore this option. Note also that some
459: filesystems are mounted to avoid updating the atime on read access even
460: without the O_NOATIME flag being set.
461: .IP
462: When set to False, this parameters ensures that files on the server are not
463: opened with O_NOATIME.
464: .IP
465: When set to Unset (the default) the user controls the setting via
466: \fB\-\-open-noatime\fP.
467: .IP "\fBlist\fP"
468: This parameter determines whether this module is listed when the client
469: asks for a listing of available modules. In addition, if this is false,
470: the daemon will pretend the module does not exist when a client denied by
471: "hosts allow" or "hosts deny" attempts to access it. Realize that if
472: "reverse lookup" is disabled globally but enabled for the module, the
473: resulting reverse lookup to a potentially client-controlled DNS server may
474: still reveal to the client that it hit an existing module. The default is
475: for modules to be listable.
476: .IP "\fBuid\fP"
477: This parameter specifies the user name or user ID that file transfers to
478: and from that module should take place as when the daemon was run as root.
479: In combination with the "gid" parameter this determines what file
480: permissions are available. The default when run by a super-user is to
481: switch to the system's "nobody" user. The default for a non-super-user is
482: to not try to change the user. See also the "gid" parameter.
483: .IP
484: The RSYNC_USER_NAME environment variable may be used to request that rsync
485: run as the authorizing user. For example, if you want a rsync to run as
486: the same user that was received for the rsync authentication, this setup is
487: useful:
488: .RS 4
489: .IP
490: .nf
491: uid = %RSYNC_USER_NAME%
492: gid = *
493: .fi
494: .RE
495: .IP "\fBgid\fP"
496: This parameter specifies one or more group names/IDs that will be used when
497: accessing the module. The first one will be the default group, and any
498: extra ones be set as supplemental groups. You may also specify a "\fB*\fP" as
499: the first gid in the list, which will be replaced by all the normal groups
500: for the transfer's user (see "uid"). The default when run by a super-user
501: is to switch to your OS's "nobody" (or perhaps "nogroup") group with no
502: other supplementary groups. The default for a non-super-user is to not
503: change any group attributes (and indeed, your OS may not allow a
504: non-super-user to try to change their group settings).
505: .IP
506: The specified list is normally split into tokens based on spaces and
507: commas. However, if the list starts with a comma, then the list is only
508: split on commas, which allows a group name to contain a space. In either
509: case any leading and/or trailing whitespace is removed from the tokens and
510: empty tokens are ignored.
511: .IP "\fBdaemon\ uid\fP"
512: This parameter specifies a uid under which the daemon will run. The daemon
513: usually runs as user root, and when this is left unset the user is left
514: unchanged. See also the "uid" parameter.
515: .IP "\fBdaemon\ gid\fP"
516: This parameter specifies a gid under which the daemon will run. The daemon
517: usually runs as group root, and when this is left unset, the group is left
518: unchanged. See also the "gid" parameter.
519: .IP "\fBfake\ super\fP"
520: Setting "fake super = yes" for a module causes the daemon side to behave as
521: if the \fB\-\-fake-super\fP command-line option had been specified. This allows
522: the full attributes of a file to be stored without having to have the
523: daemon actually running as root.
524: .IP "\fBfilter\fP"
525: The daemon has its own filter chain that determines what files it will let
526: the client access. This chain is not sent to the client and is independent
527: of any filters the client may have specified. Files excluded by the daemon
528: filter chain (\fBdaemon-excluded\fP files) are treated as non-existent if the
529: client tries to pull them, are skipped with an error message if the client
530: tries to push them (triggering exit code 23), and are never deleted from
531: the module. You can use daemon filters to prevent clients from downloading
532: or tampering with private administrative files, such as files you may add
533: to support uid/gid name translations.
534: .IP
535: The daemon filter chain is built from the "filter", "include from",
536: "include", "exclude from", and "exclude" parameters, in that order of
537: priority. Anchored patterns are anchored at the root of the module. To
538: prevent access to an entire subtree, for example, "\fB/secret\fP", you \fBmust\fP
539: exclude everything in the subtree; the easiest way to do this is with a
540: triple-star pattern like "\fB/secret/***\fP".
541: .IP
542: The "filter" parameter takes a space-separated list of daemon filter rules,
543: though it is smart enough to know not to split a token at an internal space
544: in a rule (e.g. "\fB\-\ /foo\ \-\ /bar\fP" is parsed as two rules). You may specify
545: one or more merge-file rules using the normal syntax. Only one "filter"
546: parameter can apply to a given module in the config file, so put all the
547: rules you want in a single parameter. Note that per-directory merge-file
548: rules do not provide as much protection as global rules, but they can be
549: used to make \fB\-\-delete\fP work better during a client download operation if
550: the per-dir merge files are included in the transfer and the client
551: requests that they be used.
552: .IP "\fBexclude\fP"
553: This parameter takes a space-separated list of daemon exclude patterns. As
554: with the client \fB\-\-exclude\fP option, patterns can be qualified with "\fB\-\fP" or
555: "\fB+\fP" to explicitly indicate exclude/include. Only one "exclude" parameter
556: can apply to a given module. See the "filter" parameter for a description
557: of how excluded files affect the daemon.
558: .IP "\fBinclude\fP"
559: Use an "include" to override the effects of the "exclude" parameter. Only
560: one "include" parameter can apply to a given module. See the "filter"
561: parameter for a description of how excluded files affect the daemon.
562: .IP "\fBexclude\ from\fP"
563: This parameter specifies the name of a file on the daemon that contains
564: daemon exclude patterns, one per line. Only one "exclude from" parameter
565: can apply to a given module; if you have multiple exclude-from files, you
566: can specify them as a merge file in the "filter" parameter. See the
567: "filter" parameter for a description of how excluded files affect the
568: daemon.
569: .IP "\fBinclude\ from\fP"
570: Analogue of "exclude from" for a file of daemon include patterns. Only one
571: "include from" parameter can apply to a given module. See the "filter"
572: parameter for a description of how excluded files affect the daemon.
573: .IP "\fBincoming\ chmod\fP"
574: This parameter allows you to specify a set of comma-separated chmod strings
575: that will affect the permissions of all incoming files (files that are
576: being received by the daemon). These changes happen after all other
577: permission calculations, and this will even override destination-default
578: and/or existing permissions when the client does not specify \fB\-\-perms\fP.
579: See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
580: manpage for information on the format of this string.
581: .IP "\fBoutgoing\ chmod\fP"
582: This parameter allows you to specify a set of comma-separated chmod strings
583: that will affect the permissions of all outgoing files (files that are
584: being sent out from the daemon). These changes happen first, making the
585: sent permissions appear to be different than those stored in the filesystem
586: itself. For instance, you could disable group write permissions on the
587: server while having it appear to be on to the clients. See the description
588: of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1) manpage for information
589: on the format of this string.
590: .IP "\fBauth\ users\fP"
591: This parameter specifies a comma and/or space-separated list of
592: authorization rules. In its simplest form, you list the usernames that
593: will be allowed to connect to this module. The usernames do not need to
594: exist on the local system. The rules may contain shell wildcard characters
595: that will be matched against the username provided by the client for
596: authentication. If "auth users" is set then the client will be challenged
597: to supply a username and password to connect to the module. A challenge
598: response authentication protocol is used for this exchange. The plain text
599: usernames and passwords are stored in the file specified by the
600: "secrets file" parameter. The default is for all users to be able to
601: connect without a password (this is called "anonymous rsync").
602: .IP
603: In addition to username matching, you can specify groupname matching via a
604: \&'@' prefix. When using groupname matching, the authenticating username
605: must be a real user on the system, or it will be assumed to be a member of
606: no groups. For example, specifying "@rsync" will match the authenticating
607: user if the named user is a member of the rsync group.
608: .IP
609: Finally, options may be specified after a colon (:). The options allow you
610: to "deny" a user or a group, set the access to "ro" (read-only), or set the
611: access to "rw" (read/write). Setting an auth-rule-specific ro/rw setting
612: overrides the module's "read only" setting.
613: .IP
614: Be sure to put the rules in the order you want them to be matched, because
615: the checking stops at the first matching user or group, and that is the
616: only auth that is checked. For example:
617: .RS 4
618: .IP
619: .nf
620: auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam
621: .fi
622: .RE
623: .IP
624: In the above rule, user joe will be denied access no matter what. Any user
625: that is in the group "guest" is also denied access. The user "admin" gets
626: access in read/write mode, but only if the admin user is not in group
627: "guest" (because the admin user-matching rule would never be reached if the
628: user is in group "guest"). Any other user who is in group "rsync" will get
629: read-only access. Finally, users susan, joe, and sam get the ro/rw setting
630: of the module, but only if the user didn't match an earlier group-matching
631: rule.
632: .IP
633: If you need to specify a user or group name with a space in it, start your
634: list with a comma to indicate that the list should only be split on commas
635: (though leading and trailing whitespace will also be removed, and empty
636: entries are just ignored). For example:
637: .RS 4
638: .IP
639: .nf
640: auth users = , joe:deny, @Some Group:deny, admin:rw, @RO Group:ro
641: .fi
642: .RE
643: .IP
644: See the description of the secrets file for how you can have per-user
645: passwords as well as per-group passwords. It also explains how a user can
646: authenticate using their user password or (when applicable) a group
647: password, depending on what rule is being authenticated.
648: .IP
649: See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE
650: SHELL CONNECTION" in \fBrsync\fP(1) for information on how handle an
651: rsyncd.conf-level username that differs from the remote-shell-level
652: username when using a remote shell to connect to an rsync daemon.
653: .IP "\fBsecrets\ file\fP"
654: This parameter specifies the name of a file that contains the
655: username:password and/or @groupname:password pairs used for authenticating
656: this module. This file is only consulted if the "auth users" parameter is
657: specified. The file is line-based and contains one name:password pair per
658: line. Any line has a hash (#) as the very first character on the line is
659: considered a comment and is skipped. The passwords can contain any
660: characters but be warned that many operating systems limit the length of
661: passwords that can be typed at the client end, so you may find that
662: passwords longer than 8 characters don't work.
663: .IP
664: The use of group-specific lines are only relevant when the module is being
665: authorized using a matching "@groupname" rule. When that happens, the user
666: can be authorized via either their "username:password" line or the
667: "@groupname:password" line for the group that triggered the authentication.
668: .IP
669: It is up to you what kind of password entries you want to include, either
670: users, groups, or both. The use of group rules in "auth users" does not
671: require that you specify a group password if you do not want to use shared
672: passwords.
673: .IP
674: There is no default for the "secrets file" parameter, you must choose a
675: name (such as \fB/etc/rsyncd.secrets\fP). The file must normally not be
676: readable by "other"; see "strict modes". If the file is not found or is
677: rejected, no logins for a "user auth" module will be possible.
678: .IP "\fBstrict\ modes\fP"
679: This parameter determines whether or not the permissions on the secrets
680: file will be checked. If "strict modes" is true, then the secrets file
681: must not be readable by any user ID other than the one that the rsync
682: daemon is running under. If "strict modes" is false, the check is not
683: performed. The default is true. This parameter was added to accommodate
684: rsync running on the Windows operating system.
685: .IP "\fBhosts\ allow\fP"
686: This parameter allows you to specify a list of comma- and/or
687: whitespace-separated patterns that are matched against a connecting
688: client's hostname and IP address. If none of the patterns match, then the
689: connection is rejected.
690: .IP
691: Each pattern can be in one of six forms:
692: .IP
693: .RS
694: .IP o
695: a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address of
696: the form a:b:c::d:e:f. In this case the incoming machine's IP address
697: must match exactly.
698: .IP o
699: an address/mask in the form ipaddr/n where ipaddr is the IP address and n
700: is the number of one bits in the netmask. All IP addresses which match
701: the masked IP address will be allowed in.
702: .IP o
703: an address/mask in the form ipaddr/maskaddr where ipaddr is the IP
704: address and maskaddr is the netmask in dotted decimal notation for IPv4,
705: or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
706: addresses which match the masked IP address will be allowed in.
707: .IP o
708: a hostname pattern using wildcards. If the hostname of the connecting IP
709: (as determined by a reverse lookup) matches the wildcarded name (using
710: the same rules as normal unix filename matching), the client is allowed
711: in. This only works if "reverse lookup" is enabled (the default).
712: .IP o
713: a hostname. A plain hostname is matched against the reverse DNS of the
714: connecting IP (if "reverse lookup" is enabled), and/or the IP of the
715: given hostname is matched against the connecting IP (if "forward lookup"
716: is enabled, as it is by default). Any match will be allowed in.
717: .IP o
718: an '@' followed by a netgroup name, which will match if the reverse DNS
719: of the connecting IP is in the specified netgroup.
720: .RE
721: .IP
722: Note IPv6 link-local addresses can have a scope in the address
723: specification:
724: .RS 4
725: .IP
726: .nf
727: fe80::1%link1
728: fe80::%link1/64
729: fe80::%link1/ffff:ffff:ffff:ffff::
730: .fi
731: .RE
732: .IP
733: You can also combine "hosts allow" with "hosts deny" as a way to add
734: exceptions to your deny list. When both parameters are specified, the
735: "hosts allow" parameter is checked first and a match results in the client
736: being able to connect. A non-allowed host is then matched against the
737: "hosts deny" list to see if it should be rejected. A host that does not
738: match either list is allowed to connect.
739: .IP
740: The default is no "hosts allow" parameter, which means all hosts can
741: connect.
742: .IP "\fBhosts\ deny\fP"
743: This parameter allows you to specify a list of comma- and/or
744: whitespace-separated patterns that are matched against a connecting clients
745: hostname and IP address. If the pattern matches then the connection is
746: rejected. See the "hosts allow" parameter for more information.
747: .IP
748: The default is no "hosts deny" parameter, which means all hosts can
749: connect.
750: .IP "\fBreverse\ lookup\fP"
751: Controls whether the daemon performs a reverse lookup on the client's IP
752: address to determine its hostname, which is used for "hosts allow" &
753: "hosts deny" checks and the "%h" log escape. This is enabled by default,
754: but you may wish to disable it to save time if you know the lookup will not
755: return a useful result, in which case the daemon will use the name
756: "UNDETERMINED" instead.
757: .IP
758: If this parameter is enabled globally (even by default), rsync performs the
759: lookup as soon as a client connects, so disabling it for a module will not
760: avoid the lookup. Thus, you probably want to disable it globally and then
761: enable it for modules that need the information.
762: .IP "\fBforward\ lookup\fP"
763: Controls whether the daemon performs a forward lookup on any hostname
764: specified in an hosts allow/deny setting. By default this is enabled,
765: allowing the use of an explicit hostname that would not be returned by
766: reverse DNS of the connecting IP.
767: .IP "\fBignore\ errors\fP"
768: This parameter tells rsyncd to ignore I/O errors on the daemon when
769: deciding whether to run the delete phase of the transfer. Normally rsync
770: skips the \fB\-\-delete\fP step if any I/O errors have occurred in order to
771: prevent disastrous deletion due to a temporary resource shortage or other
772: I/O error. In some cases this test is counter productive so you can use
773: this parameter to turn off this behavior.
774: .IP "\fBignore\ nonreadable\fP"
775: This tells the rsync daemon to completely ignore files that are not
776: readable by the user. This is useful for public archives that may have some
777: non-readable files among the directories, and the sysadmin doesn't want
778: those files to be seen at all.
779: .IP "\fBtransfer\ logging\fP"
780: This parameter enables per-file logging of downloads and uploads in a
781: format somewhat similar to that used by ftp daemons. The daemon always
782: logs the transfer at the end, so if a transfer is aborted, no mention will
783: be made in the log file.
784: .IP
785: If you want to customize the log lines, see the "log format" parameter.
786: .IP "\fBlog\ format\fP"
787: This parameter allows you to specify the format used for logging file
788: transfers when transfer logging is enabled. The format is a text string
789: containing embedded single-character escape sequences prefixed with a
790: percent (%) character. An optional numeric field width may also be
791: specified between the percent and the escape letter (e.g.
792: "\fB%\-50n\ %8l\ %07p\fP"). In addition, one or more apostrophes may be specified
793: prior to a numerical escape to indicate that the numerical value should be
794: made more human-readable. The 3 supported levels are the same as for the
795: \fB\-\-human-readable\fP command-line option, though the default is for
796: human-readability to be off. Each added apostrophe increases the level
797: (e.g. "\fB%''l\ %'b\ %f\fP").
798: .IP
799: The default log format is "\fB%o\ %h\ [%a]\ %m\ (%u)\ %f\ %l\fP", and a "\fB%t\ [%p]\fP"
800: is always prefixed when using the "log file" parameter. (A perl script
801: that will summarize this default log format is included in the rsync source
802: code distribution in the "support" subdirectory: rsyncstats.)
803: .IP
804: The single-character escapes that are understood are as follows:
805: .IP
806: .RS
807: .IP o
808: %a the remote IP address (only available for a daemon)
809: .IP o
810: %b the number of bytes actually transferred
811: .IP o
812: %B the permission bits of the file (e.g. rwxrwxrwt)
813: .IP o
814: %c the total size of the block checksums received for the basis file
815: (only when sending)
816: .IP o
817: %C the full-file checksum if it is known for the file. For older rsync
818: protocols/versions, the checksum was salted, and is thus not a useful
819: value (and is not displayed when that is the case). For the checksum to
820: output for a file, either the \fB\-\-checksum\fP option must be in-effect or
821: the file must have been transferred without a salted checksum being used.
822: See the \fB\-\-checksum-choice\fP option for a way to choose the algorithm.
823: .IP o
824: %f the filename (long form on sender; no trailing "/")
825: .IP o
826: %G the gid of the file (decimal) or "DEFAULT"
827: .IP o
828: %h the remote host name (only available for a daemon)
829: .IP o
830: %i an itemized list of what is being updated
831: .IP o
832: %l the length of the file in bytes
833: .IP o
834: %L the string "\fB\->\ SYMLINK\fP", "\fB=>\ HARDLINK\fP", or "" (where \fBSYMLINK\fP
835: or \fBHARDLINK\fP is a filename)
836: .IP o
837: %m the module name
838: .IP o
839: %M the last-modified time of the file
840: .IP o
841: %n the filename (short form; trailing "/" on dir)
842: .IP o
843: %o the operation, which is "send", "recv", or "del." (the latter includes
844: the trailing period)
845: .IP o
846: %p the process ID of this rsync session
847: .IP o
848: %P the module path
849: .IP o
850: %t the current date time
851: .IP o
852: %u the authenticated username or an empty string
853: .IP o
854: %U the uid of the file (decimal)
855: .RE
856: .IP
857: For a list of what the characters mean that are output by "%i", see the
858: \fB\-\-itemize-changes\fP option in the rsync manpage.
859: .IP
860: Note that some of the logged output changes when talking with older rsync
861: versions. For instance, deleted files were only output as verbose messages
862: prior to rsync 2.6.4.
863: .IP "\fBtimeout\fP"
864: This parameter allows you to override the clients choice for I/O timeout
865: for this module. Using this parameter you can ensure that rsync won't wait
866: on a dead client forever. The timeout is specified in seconds. A value of
867: zero means no timeout and is the default. A good choice for anonymous rsync
868: daemons may be 600 (giving a 10 minute timeout).
869: .IP "\fBrefuse\ options\fP"
870: This parameter allows you to specify a space-separated list of rsync
871: command-line options that will be refused by your rsync daemon. You may
872: specify the full option name, its one-letter abbreviation, or a wild-card
873: string that matches multiple options. Beginning in 3.2.0, you can also
874: negate a match term by starting it with a "!".
875: .IP
876: When an option is refused, the daemon prints an error message and exits.
877: .IP
878: For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various
879: delete options:
880: .RS 4
881: .IP
882: .nf
883: refuse options = c delete
884: .fi
885: .RE
886: .IP
887: The reason the above refuses all delete options is that the options imply
888: \fB\-\-delete\fP, and implied options are refused just like explicit options.
889: .IP
890: The use of a negated match allows you to fine-tune your refusals after a
891: wild-card, such as this:
892: .RS 4
893: .IP
894: .nf
895: refuse options = delete-* !delete-during
896: .fi
897: .RE
898: .IP
899: Negated matching can also turn your list of refused options into a list of
900: accepted options. To do this, begin the list with a "\fB*\fP" (to refuse all
901: options) and then specify one or more negated matches to accept. For
902: example:
903: .RS 4
904: .IP
905: .nf
906: refuse options = * !a !v !compress*
907: .fi
908: .RE
909: .IP
910: Don't worry that the "\fB*\fP" will refuse certain vital options such as
911: \fB\-\-dry-run\fP, \fB\-\-server\fP, \fB\-\-no-iconv\fP, \fB\-\-protect-args\fP, etc. These
912: important options are not matched by wild-card, so they must be overridden
913: by their exact name. For instance, if you're forcing iconv transfers you
914: could use something like this:
915: .RS 4
916: .IP
917: .nf
918: refuse options = * no-iconv !a !v
919: .fi
920: .RE
921: .IP
922: As an additional aid (beginning in 3.2.0), refusing (or "\fB!refusing\fP") the
923: "a" or "archive" option also affects all the options that the \fB\-\-archive\fP
924: option implies (\fB\-rdlptgoD\fP), but only if the option is matched explicitly
925: (not using a wildcard). If you want to do something tricky, you can use
926: "\fBarchive*\fP" to avoid this side-effect, but keep in mind that no normal
927: rsync client ever sends the actual archive option to the server.
928: .IP
929: As an additional safety feature, the refusal of "delete" also refuses
930: \fBremove-source-files\fP when the daemon is the sender; if you want the latter
931: without the former, instead refuse "\fBdelete-*\fP" as that refuses all the
932: delete modes without affecting \fB\-\-remove-source-files\fP. (Keep in mind that
933: the client's \fB\-\-delete\fP option typically results in \fB\-\-delete-during\fP.)
934: .IP
935: When un-refusing delete options, you should either specify "\fB!delete*\fP" (to
936: accept all delete options) or specify a limited set that includes "delete",
937: such as:
938: .RS 4
939: .IP
940: .nf
941: refuse options = * !a !delete !delete-during
942: .fi
943: .RE
944: .IP
945: \&... whereas this accepts any delete option except \fB\-\-delete-after\fP:
946: .RS 4
947: .IP
948: .nf
949: refuse options = * !a !delete* delete-after
950: .fi
951: .RE
952: .IP
953: A note on refusing "compress"\ \-\- it is better to set the "dont compress"
954: daemon parameter to "\fB*\fP" because that disables compression silently
955: instead of returning an error that forces the client to remove the \fB\-z\fP
956: option.
957: .IP
958: If you are un-refusing the compress option, you probably want to match
959: "\fB!compress*\fP" so that you also accept the \fB\-\-compress-level\fP option.
960: .IP
961: Note that the "copy-devices" & "write-devices" options are refused by
962: default, but they can be explicitly accepted with "\fB!copy-devices\fP" and/or
963: "\fB!write-devices\fP". The options "log-file" and "log-file-format" are
964: forcibly refused and cannot be accepted.
965: .IP
966: Here are all the options that are not matched by wild-cards:
967: .IP
968: .RS
969: .IP o
970: \fB\-\-server\fP: Required for rsync to even work.
971: .IP o
972: \fB\-\-rsh\fP, \fB\-e\fP: Required to convey compatibility flags to the server.
973: .IP o
974: \fB\-\-out-format\fP: This is required to convey output behavior to a remote
975: receiver. While rsync passes the older alias \fB\-\-log-format\fP for
976: compatibility reasons, this options should not be confused with
977: \fB\-\-log-file-format\fP.
978: .IP o
979: \fB\-\-sender\fP: Use "write only" parameter instead of refusing this.
980: .IP o
981: \fB\-\-dry-run\fP, \fB\-n\fP: Who would want to disable this?
982: .IP o
983: \fB\-\-protect-args\fP, \fB\-s\fP: This actually makes transfers safer.
984: .IP o
985: \fB\-\-from0\fP, \fB\-0\fP: Makes it easier to accept/refuse \fB\-\-files-from\fP without
986: affecting this helpful modifier.
987: .IP o
988: \fB\-\-iconv\fP: This is auto-disabled based on "charset" parameter.
989: .IP o
990: \fB\-\-no-iconv\fP: Most transfers use this option.
991: .IP o
992: \fB\-\-checksum-seed\fP: Is a fairly rare, safe option.
993: .IP o
994: \fB\-\-write-devices\fP: Is non-wild but also auto-disabled.
995: .RE
996: .IP "\fBdont\ compress\fP"
997: This parameter allows you to select filenames based on wildcard patterns
998: that should not be compressed when pulling files from the daemon (no
999: analogous parameter exists to govern the pushing of files to a daemon).
1000: Compression can be expensive in terms of CPU usage, so it is usually good
1001: to not try to compress files that won't compress well, such as already
1002: compressed files.
1003: .IP
1004: The "dont compress" parameter takes a space-separated list of
1005: case-insensitive wildcard patterns. Any source filename matching one of the
1006: patterns will be compressed as little as possible during the transfer. If
1007: the compression algorithm has an "off" level (such as zlib/zlibx) then no
1008: compression occurs for those files. Other algorithms have the level
1009: minimized to reduces the CPU usage as much as possible.
1010: .IP
1011: See the \fB\-\-skip-compress\fP parameter in the \fBrsync\fP(1) manpage for the
1012: list of file suffixes that are not compressed by default. Specifying a
1013: value for the "dont compress" parameter changes the default when the daemon
1014: is the sender.
1015: .IP "\fBearly\ exec\fP, \fBpre-xfer\ exec\fP, \fBpost-xfer\ exec\fP"
1016: You may specify a command to be run in the early stages of the connection,
1017: or right before and/or after the transfer. If the \fBearly\ exec\fP or
1018: \fBpre-xfer\ exec\fP command returns an error code, the transfer is aborted
1019: before it begins. Any output from the \fBpre-xfer\ exec\fP command on stdout
1020: (up to several KB) will be displayed to the user when aborting, but is
1021: \fInot\fP displayed if the script returns success. The other programs cannot
1022: send any text to the user. All output except for the \fBpre-xfer\ exec\fP
1023: stdout goes to the corresponding daemon's stdout/stderr, which is typically
1024: discarded. See the \fB\-\-no-detatch\fP option for a way to see the daemon's
1025: output, which can assist with debugging.
1026: .IP
1027: Note that the \fBearly\ exec\fP command runs before any part of the transfer
1028: request is known except for the module name. This helper script can be
1029: used to setup a disk mount or decrypt some data into a module dir, but you
1030: may need to use \fBlock\ file\fP and \fBmax\ connections\fP to avoid concurrency
1031: issues. If the client rsync specified the \fB\-\-early-input=FILE\fP option, it
1032: can send up to about 5K of data to the stdin of the early script. The
1033: stdin will otherwise be empty.
1034: .IP
1035: Note that the \fBpost-xfer\ exec\fP command is still run even if one of the
1036: other scripts returns an error code. The \fBpre-xfer\ exec\fP command will \fInot\fP
1037: be run, however, if the \fBearly\ exec\fP command fails.
1038: .IP
1039: The following environment variables will be set, though some are specific
1040: to the pre-xfer or the post-xfer environment:
1041: .IP
1042: .RS
1043: .IP o
1044: \fBRSYNC_MODULE_NAME\fP: The name of the module being accessed.
1045: .IP o
1046: \fBRSYNC_MODULE_PATH\fP: The path configured for the module.
1047: .IP o
1048: \fBRSYNC_HOST_ADDR\fP: The accessing host's IP address.
1049: .IP o
1050: \fBRSYNC_HOST_NAME\fP: The accessing host's name.
1051: .IP o
1052: \fBRSYNC_USER_NAME\fP: The accessing user's name (empty if no user).
1053: .IP o
1054: \fBRSYNC_PID\fP: A unique number for this transfer.
1055: .IP o
1056: \fBRSYNC_REQUEST\fP: (pre-xfer only) The module/path info specified by the
1057: user. Note that the user can specify multiple source files, so the
1058: request can be something like "mod/path1 mod/path2", etc.
1059: .IP o
1060: \fBRSYNC_ARG#\fP: (pre-xfer only) The pre-request arguments are set in these
1061: numbered values. RSYNC_ARG0 is always "rsyncd", followed by the options
1062: that were used in RSYNC_ARG1, and so on. There will be a value of "."
1063: indicating that the options are done and the path args are beginning\ \-\-
1064: these contain similar information to RSYNC_REQUEST, but with values
1065: separated and the module name stripped off.
1066: .IP o
1067: \fBRSYNC_EXIT_STATUS\fP: (post-xfer only) the server side's exit value. This
1068: will be 0 for a successful run, a positive value for an error that the
1069: server generated, or a \-1 if rsync failed to exit properly. Note that an
1070: error that occurs on the client side does not currently get sent to the
1071: server side, so this is not the final exit status for the whole transfer.
1072: .IP o
1073: \fBRSYNC_RAW_STATUS\fP: (post-xfer only) the raw exit value from
1074: \fBwaitpid()\fP.
1075: .RE
1076: .IP
1077: Even though the commands can be associated with a particular module, they
1078: are run using the permissions of the user that started the daemon (not the
1079: module's uid/gid setting) without any chroot restrictions.
1080: .IP
1081: These settings honor 2 environment variables: use RSYNC_SHELL to set a
1082: shell to use when running the command (which otherwise uses your
1083: \fBsystem()\fP call's default shell), and use RSYNC_NO_XFER_EXEC to disable
1084: both options completely.
1085: .P
1086: .SH "CONFIG DIRECTIVES"
1087: .P
1088: There are currently two config directives available that allow a config file to
1089: incorporate the contents of other files: \fB&include\fP and \fB&merge\fP. Both allow
1090: a reference to either a file or a directory. They differ in how segregated the
1091: file's contents are considered to be.
1092: .P
1093: The \fB&include\fP directive treats each file as more distinct, with each one
1094: inheriting the defaults of the parent file, starting the parameter parsing as
1095: globals/defaults, and leaving the defaults unchanged for the parsing of the
1096: rest of the parent file.
1097: .P
1098: The \fB&merge\fP directive, on the other hand, treats the file's contents as if it
1099: were simply inserted in place of the directive, and thus it can set parameters
1100: in a module started in another file, can affect the defaults for other files,
1101: etc.
1102: .P
1103: When an \fB&include\fP or \fB&merge\fP directive refers to a directory, it will read in
1104: all the \fB*.conf\fP or \fB*.inc\fP files (respectively) that are contained inside that
1105: directory (without any recursive scanning), with the files sorted into alpha
1106: order. So, if you have a directory named "rsyncd.d" with the files "foo.conf",
1107: "bar.conf", and "baz.conf" inside it, this directive:
1108: .RS 4
1109: .P
1110: .nf
1111: &include /path/rsyncd.d
1112: .fi
1113: .RE
1114: .P
1115: would be the same as this set of directives:
1116: .RS 4
1117: .P
1118: .nf
1119: &include /path/rsyncd.d/bar.conf
1120: &include /path/rsyncd.d/baz.conf
1121: &include /path/rsyncd.d/foo.conf
1122: .fi
1123: .RE
1124: .P
1125: except that it adjusts as files are added and removed from the directory.
1126: .P
1127: The advantage of the \fB&include\fP directive is that you can define one or more
1128: modules in a separate file without worrying about unintended side-effects
1129: between the self-contained module files.
1130: .P
1131: The advantage of the \fB&merge\fP directive is that you can load config snippets
1132: that can be included into multiple module definitions, and you can also set
1133: global values that will affect connections (such as \fBmotd\ file\fP), or globals
1134: that will affect other include files.
1135: .P
1136: For example, this is a useful /etc/rsyncd.conf file:
1137: .RS 4
1138: .P
1139: .nf
1140: port = 873
1141: log file = /var/log/rsync.log
1142: pid file = /var/lock/rsync.lock
1143:
1144: &merge /etc/rsyncd.d
1145: &include /etc/rsyncd.d
1146: .fi
1147: .RE
1148: .P
1149: This would merge any \fB/etc/rsyncd.d/*.inc\fP files (for global values that should
1150: stay in effect), and then include any \fB/etc/rsyncd.d/*.conf\fP files (defining
1151: modules without any global-value cross-talk).
1152: .P
1153: .SH "AUTHENTICATION STRENGTH"
1154: .P
1155: The authentication protocol used in rsync is a 128 bit MD4 based challenge
1156: response system. This is fairly weak protection, though (with at least one
1157: brute-force hash-finding algorithm publicly available), so if you want really
1158: top-quality security, then I recommend that you run rsync over ssh. (Yes, a
1159: future version of rsync will switch over to a stronger hashing method.)
1160: .P
1161: Also note that the rsync daemon protocol does not currently provide any
1162: encryption of the data that is transferred over the connection. Only
1163: authentication is provided. Use ssh as the transport if you want encryption.
1164: .P
1165: You can also make use of SSL/TLS encryption if you put rsync behind an
1166: SSL proxy.
1167: .P
1168: .SH "SSL/TLS Daemon Setup"
1169: .P
1170: When setting up an rsync daemon for access via SSL/TLS, you will need to
1171: configure a proxy (such as haproxy or nginx) as the front-end that handles the
1172: encryption.
1173: .P
1174: .IP o
1175: You should limit the access to the backend-rsyncd port to only allow the
1176: proxy to connect. If it is on the same host as the proxy, then configuring
1177: it to only listen on localhost is a good idea.
1178: .IP o
1179: You should consider turning on the \fBproxy\ protocol\fP parameter if your proxy
1180: supports sending that information. The examples below assume that this is
1181: enabled.
1182: .P
1183: An example haproxy setup is as follows:
1184: .RS 4
1185: .P
1186: .nf
1187: frontend fe_rsync-ssl
1188: bind :::874 ssl crt /etc/letsencrypt/example.com/combined.pem
1189: mode tcp
1190: use_backend be_rsync
1191:
1192: backend be_rsync
1193: mode tcp
1194: server local-rsync 127.0.0.1:873 check send-proxy
1195: .fi
1196: .RE
1197: .P
1198: An example nginx proxy setup is as follows:
1199: .RS 4
1200: .P
1201: .nf
1202: stream {
1203: server {
1204: listen 874 ssl;
1205: listen [::]:874 ssl;
1206:
1207: ssl_certificate /etc/letsencrypt/example.com/fullchain.pem;
1208: ssl_certificate_key /etc/letsencrypt/example.com/privkey.pem;
1209:
1210: proxy_pass localhost:873;
1211: proxy_protocol on; # Requires "proxy protocol = true"
1212: proxy_timeout 1m;
1213: proxy_connect_timeout 5s;
1214: }
1215: }
1216: .fi
1217: .RE
1218: .P
1219: .SH "EXAMPLES"
1220: .P
1221: A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
1222: \fB/home/ftp\fP would be:
1223: .RS 4
1224: .P
1225: .nf
1226: [ftp]
1227: path = /home/ftp
1228: comment = ftp export area
1229: .fi
1230: .RE
1231: .P
1232: A more sophisticated example would be:
1233: .RS 4
1234: .P
1235: .nf
1236: uid = nobody
1237: gid = nobody
1238: use chroot = yes
1239: max connections = 4
1240: syslog facility = local5
1241: pid file = /var/run/rsyncd.pid
1242: slp refresh = 3600
1243:
1244: [ftp]
1245: path = /var/ftp/./pub
1246: comment = whole ftp area (approx 6.1 GB)
1247:
1248: [sambaftp]
1249: path = /var/ftp/./pub/samba
1250: comment = Samba ftp area (approx 300 MB)
1251:
1252: [rsyncftp]
1253: path = /var/ftp/./pub/rsync
1254: comment = rsync ftp area (approx 6 MB)
1255:
1256: [sambawww]
1257: path = /public_html/samba
1258: comment = Samba WWW pages (approx 240 MB)
1259:
1260: [cvs]
1261: path = /data/cvs
1262: comment = CVS repository (requires authentication)
1263: auth users = tridge, susan
1264: secrets file = /etc/rsyncd.secrets
1265: .fi
1266: .RE
1267: .P
1268: The /etc/rsyncd.secrets file would look something like this:
1269: .RS 4
1270: .P
1271: .nf
1272: tridge:mypass
1273: susan:herpass
1274: .fi
1275: .RE
1276: .P
1277: .SH "FILES"
1278: .P
1279: /etc/rsyncd.conf or rsyncd.conf
1280: .P
1281: .SH "SEE ALSO"
1282: .P
1283: \fBrsync\fP(1), \fBrsync-ssl\fP(1)
1284: .P
1285: .SH "BUGS"
1286: .P
1287: Please report bugs! The rsync bug tracking system is online at
1288: https://rsync.samba.org/.
1289: .P
1290: .SH "VERSION"
1291: .P
1292: This man page is current for version 3.2.3 of rsync.
1293: .P
1294: .SH "CREDITS"
1295: .P
1296: rsync is distributed under the GNU General Public License. See the file
1297: COPYING for details.
1298: .P
1299: The primary ftp site for rsync is ftp://rsync.samba.org/pub/rsync
1300: .P
1301: A web site is available at https://rsync.samba.org/.
1302: .P
1303: We would be delighted to hear from you if you like this program.
1304: .P
1305: This program uses the zlib compression library written by Jean-loup Gailly and
1306: Mark Adler.
1307: .P
1308: .SH "THANKS"
1309: .P
1310: Thanks to Warren Stanley for his original idea and patch for the rsync daemon.
1311: Thanks to Karsten Thygesen for his many suggestions and documentation!
1312: .P
1313: .SH "AUTHOR"
1314: .P
1315: rsync was written by Andrew Tridgell and Paul Mackerras. Many people have
1316: later contributed to it.
1317: .P
1318: Mailing lists for support and development are available at
1319: https://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