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