3 rsyncd.conf - configuration file for rsync in daemon mode
9 The online version of this manpage (that includes cross-linking of topics)
10 is available at <https://download.samba.org/pub/rsync/rsyncd.conf.5>.
14 The rsyncd.conf file is the runtime configuration file for rsync when run as an
17 The rsyncd.conf file controls authentication, access, logging and available
22 The file consists of modules and parameters. A module begins with the name of
23 the module in square brackets and continues until the next module begins.
24 Modules contain parameters of the form `name = value`.
26 The file is line-based -- that is, each newline-terminated line represents
27 either a comment, a module name or a parameter.
29 Only the first equals sign in a parameter is significant. Whitespace before or
30 after the first equals sign is discarded. Leading, trailing and internal
31 whitespace in module and parameter names is irrelevant. Leading and trailing
32 whitespace in a parameter value is discarded. Internal whitespace within a
33 parameter value is retained verbatim.
35 Any line **beginning** with a hash (`#`) is ignored, as are lines containing
36 only whitespace. (If a hash occurs after anything other than leading
37 whitespace, it is considered a part of the line's content.)
39 Any line ending in a `\` is "continued" on the next line in the customary UNIX
42 The values following the equals sign in parameters are all either a string (no
43 quotes needed) or a boolean, which may be given as yes/no, 0/1 or true/false.
44 Case is not significant in boolean values, but is preserved in string values.
46 ## LAUNCHING THE RSYNC DAEMON
48 The rsync daemon is launched by specifying the `--daemon` option to rsync.
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,
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 "`rsync --daemon`" from a suitable startup script.
59 When run via inetd you should add a line like this to /etc/services:
63 and a single line something like this to /etc/inetd.conf:
65 > rsync stream tcp nowait root @BINDIR@/rsync rsyncd --daemon
67 Replace "@BINDIR@/rsync" with the path to where you have rsync installed on
68 your system. You will then need to send inetd a HUP signal to tell it to
69 reread its config file.
71 Note that you should **not** send the rsync daemon a HUP signal to force it to
72 reread the `rsyncd.conf` file. The file is re-read on each client connection.
76 The first parameters in the file (before a [module] header) are the global
77 parameters. Rsync also allows for the use of a "[global]" module name to
78 indicate the start of one or more global-parameter sections (the name must be
81 You may also include any module parameters in the global part of the config
82 file in which case the supplied value will override the default for that
85 You may use references to environment variables in the values of parameters.
86 String parameters will have %VAR% references expanded as late as possible (when
87 the string is first used in the program), allowing for the use of variables
88 that rsync sets at connection time, such as RSYNC_USER_NAME. Non-string
89 parameters (such as true/false settings) are expanded when read from the config
90 file. If a variable does not exist in the environment, or if a sequence of
91 characters is not a valid reference (such as an un-paired percent sign), the
92 raw characters are passed through unchanged. This helps with backward
93 compatibility and safety (e.g. expanding a non-existent %VAR% to an empty
94 string in a path could result in a very unsafe path). The safest way to insert
95 a literal % into a value is to use %%.
97 [comment]: # (An OL starting at 0 is converted into a DL by the parser.)
101 This parameter allows you to specify a "message of the day" (MOTD) to display
102 to clients on each connect. This usually contains site information and any
103 legal notices. The default is no MOTD file. This can be overridden by the
104 `--dparam=motdfile=FILE` command-line option when starting the daemon.
108 This parameter tells the rsync daemon to write its process ID to that file.
109 The rsync keeps the file locked so that it can know when it is safe to
110 overwrite an existing file.
112 The filename can be overridden by the `--dparam=pidfile=FILE` command-line
113 option when starting the daemon.
117 You can override the default port the daemon will listen on by specifying
118 this value (defaults to 873). This is ignored if the daemon is being run
119 by inetd, and is superseded by the `--port` command-line option.
123 You can override the default IP address the daemon will listen on by
124 specifying this value. This is ignored if the daemon is being run by
125 inetd, and is superseded by the `--address` command-line option.
129 This parameter can provide endless fun for people who like to tune their
130 systems to the utmost degree. You can set all sorts of socket options which
131 may make transfers faster (or slower!). Read the manpage for the
132 **setsockopt()** system call for details on some of the options you may be
133 able to set. By default no special socket options are set. These settings
134 can also be specified via the `--sockopts` command-line option.
138 You can override the default backlog value when the daemon listens for
139 connections. It defaults to 5.
143 After the global parameters you should define a number of modules, each module
144 exports a directory tree as a symbolic name. Modules are exported by specifying
145 a module name in square brackets [module] followed by the parameters for that
146 module. The module name cannot contain a slash or a closing square bracket.
147 If the name contains whitespace, each internal sequence of whitespace will be
148 changed into a single space, while leading or trailing whitespace will be
149 discarded. Also, the name cannot be "global" as that exact name indicates that
150 global parameters follow (see above).
152 As with GLOBAL PARAMETERS, you may use references to environment variables in
153 the values of parameters. See the GLOBAL PARAMETERS section for more details.
157 This parameter specifies a description string that is displayed next to the
158 module name when clients obtain a list of available modules. The default is
163 This parameter specifies the directory in the daemon's filesystem to make
164 available in this module. You must specify this parameter for each module
167 You may base the path's value off of an environment variable by surrounding
168 the variable name with percent signs. You can even reference a variable
169 that is set by rsync when the user connects. For example, this would use
170 the authorizing user's name in the path:
172 > path = /home/%RSYNC_USER_NAME%
174 It is fine if the path includes internal spaces -- they will be retained
175 verbatim (which means that you shouldn't try to escape them). If your
176 final directory has a trailing space (and this is somehow not something you
177 wish to fix), append a trailing slash to the path to avoid losing the
182 If "use chroot" is true, the rsync daemon will chroot to the "[path](#)" before
183 starting the file transfer with the client. This has the advantage of
184 extra protection against possible implementation security holes, but it has
185 the disadvantages of requiring super-user privileges, of not being able to
186 follow symbolic links that are either absolute or outside of the new root
187 path, and of complicating the preservation of users and groups by name (see
190 As an additional safety feature, you can specify a dot-dir in the module's
191 "[path](#)" to indicate the point where the chroot should occur. This allows
192 rsync to run in a chroot with a non-"/" path for the top of the transfer
193 hierarchy. Doing this guards against unintended library loading (since
194 those absolute paths will not be inside the transfer hierarchy unless you
195 have used an unwise pathname), and lets you setup libraries for the chroot
196 that are outside of the transfer. For example, specifying
197 "/var/rsync/./module1" will chroot to the "/var/rsync" directory and set
198 the inside-chroot path to "/module1". If you had omitted the dot-dir, the
199 chroot would have used the whole path, and the inside-chroot path would
202 When both "use chroot" and "[daemon chroot](#)" are false, OR the inside-chroot
203 path of "use chroot" is not "/", rsync will: (1) munge symlinks by default
204 for security reasons (see "[munge symlinks](#)" for a way to turn this off, but
205 only if you trust your users), (2) substitute leading slashes in absolute
206 paths with the module's path (so that options such as `--backup-dir`,
207 `--compare-dest`, etc. interpret an absolute path as rooted in the module's
208 "[path](#)" dir), and (3) trim ".." path elements from args if rsync believes
209 they would escape the module hierarchy. The default for "use chroot" is
210 true, and is the safer choice (especially if the module is not read-only).
212 When this parameter is enabled *and* the "[name converter](#)" parameter is
213 *not* set, the "[numeric ids](#)" parameter will default to being enabled
214 (disabling name lookups). This means that if you manually setup
215 name-lookup libraries in your chroot (instead of using a name converter)
216 that you need to explicitly set `numeric ids = false` for rsync to do name
219 If you copy library resources into the module's chroot area, you should
220 protect them through your OS's normal user/group or ACL settings (to
221 prevent the rsync module's user from being able to change them), and then
222 hide them from the user's view via "[exclude](#)" (see how in the discussion of
223 that parameter). However, it's easier and safer to setup a name converter.
227 This parameter specifies a path to which the daemon will chroot before
228 beginning communication with clients. Module paths (and any "[use chroot](#)"
229 settings) will then be related to this one. This lets you choose if you
230 want the whole daemon to be chrooted (with this setting), just the
231 transfers to be chrooted (with "[use chroot](#)"), or both. Keep in mind that
232 the "daemon chroot" area may need various OS/lib/etc files installed to
233 allow the daemon to function. By default the daemon runs without any
238 When this parameter is enabled, all incoming connections must start with a
239 V1 or V2 proxy protocol header. If the header is not found, the connection
242 Setting this to `true` requires a proxy server to forward source IP
243 information to rsync, allowing you to log proper IP/host info and make use
244 of client-oriented IP restrictions. The default of `false` means that the
245 IP information comes directly from the socket's metadata. If rsync is not
246 behind a proxy, this should be disabled.
248 _CAUTION_: using this option can be dangerous if you do not ensure that
249 only the proxy is allowed to connect to the rsync port. If any non-proxied
250 connections are allowed through, the client will be able to use a modified
251 rsync to spoof any remote IP address that they desire. You can lock this
252 down using something like iptables `-uid-owner root` rules (for strict
253 localhost access), various firewall rules, or you can require password
254 authorization so that any spoofing by users will not grant extra access.
256 This setting is global. If you need some modules to require this and not
257 others, then you will need to setup multiple rsync daemon processes on
262 This parameter lets you specify a program that will be run by the rsync
263 daemon to do user & group conversions between names & ids. This script
264 is started prior to any chroot being setup, and runs as the daemon user
265 (not the transfer user). You can specify a fully qualified pathname or
266 a program name that is on the $PATH.
268 The program can be used to do normal user & group lookups without having to
269 put any extra files into the chroot area of the module *or* you can do
270 customized conversions.
272 The nameconvert program has access to all of the environment variables that
273 are described in the section on `pre-xfer exec`. This is useful if you
274 want to customize the conversion using information about the module and/or
277 There is a sample python script in the support dir named "nameconvert" that
278 implements the normal user & group lookups. Feel free to customize it or
279 just use it as documentation to implement your own.
283 Enabling this parameter disables the mapping of users and groups by name
284 for the current daemon module. This prevents the daemon from trying to
285 load any user/group-related files or libraries. This enabling makes the
286 transfer behave as if the client had passed the `--numeric-ids`
287 command-line option. By default, this parameter is enabled for chroot
288 modules and disabled for non-chroot modules. Also keep in mind that
289 uid/gid preservation requires the module to be running as root (see "[uid](#)")
290 or for "[fake super](#)" to be configured.
292 A chroot-enabled module should not have this parameter set to false unless
293 you're using a "[name converter](#)" program *or* you've taken steps to ensure
294 that the module has the necessary resources it needs to translate names and
295 that it is not possible for a user to change those resources.
299 This parameter tells rsync to modify all symlinks in the same way as the
300 (non-daemon-affecting) `--munge-links` command-line option (using a method
301 described below). This should help protect your files from user trickery
302 when your daemon module is writable. The default is disabled when
303 "[use chroot](#)" is on with an inside-chroot path of "/", OR if "[daemon chroot](#)"
304 is on, otherwise it is enabled.
306 If you disable this parameter on a daemon that is not read-only, there are
307 tricks that a user can play with uploaded symlinks to access
308 daemon-excluded items (if your module has any), and, if "[use chroot](#)" is
309 off, rsync can even be tricked into showing or changing data that is
310 outside the module's path (as access-permissions allow).
312 The way rsync disables the use of symlinks is to prefix each one with the
313 string "/rsyncd-munged/". This prevents the links from being used as long
314 as that directory does not exist. When this parameter is enabled, rsync
315 will refuse to run if that path is a directory or a symlink to a directory.
316 When using the "munge symlinks" parameter in a chroot area that has an
317 inside-chroot path of "/", you should add "/rsyncd-munged/" to the exclude
318 setting for the module so that a user can't try to create it.
320 Note: rsync makes no attempt to verify that any pre-existing symlinks in
321 the module's hierarchy are as safe as you want them to be (unless, of
322 course, it just copied in the whole hierarchy). If you setup an rsync
323 daemon on a new area or locally add symlinks, you can manually protect your
324 symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
325 every symlink's value. There is a perl script in the support directory of
326 the source code named "munge-symlinks" that can be used to add or remove
327 this prefix from your symlinks.
329 When this parameter is disabled on a writable module and "[use chroot](#)" is
330 off (or the inside-chroot path is not "/"), incoming symlinks will be
331 modified to drop a leading slash and to remove ".." path elements that
332 rsync believes will allow a symlink to escape the module's hierarchy.
333 There are tricky ways to work around this, though, so you had better trust
334 your users if you choose this combination of parameters.
338 This specifies the name of the character set in which the module's
339 filenames are stored. If the client uses an `--iconv` option, the daemon
340 will use the value of the "charset" parameter regardless of the character
341 set the client actually passed. This allows the daemon to support charset
342 conversion in a chroot module without extra files in the chroot area, and
343 also ensures that name-translation is done in a consistent manner. If the
344 "charset" parameter is not set, the `--iconv` option is refused, just as if
345 "iconv" had been specified via "[refuse options](#)".
347 If you wish to force users to always use `--iconv` 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.
353 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.
361 When the "log file" parameter is set to a non-empty string, the rsync
362 daemon will log messages to the indicated file rather than using syslog.
363 This is particularly useful on systems (such as AIX) where **syslog()**
364 doesn't work for chrooted programs. The file is opened before **chroot()**
365 is called, allowing it to be placed outside the transfer. If this value is
366 set on a per-module basis instead of globally, the global log will still
367 contain any authorization failures or config-file error messages.
369 If the daemon fails to open the specified file, it will fall back to using
370 syslog and output an error about the failure. (Note that the failure to
371 open the specified log file used to be a fatal error.)
373 This setting can be overridden by using the `--log-file=FILE` or
374 `--dparam=logfile=FILE` command-line options. The former overrides all the
375 log-file parameters of the daemon and all module settings. The latter sets
376 the daemon's log file and the default for all the modules, which still
377 allows modules to override the default setting.
381 This parameter allows you to specify the syslog facility name to use when
382 logging messages from the rsync daemon. You may use any standard syslog
383 facility name which is defined on your system. Common names are auth,
384 authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user,
385 uucp, local0, local1, local2, local3, local4, local5, local6 and local7.
386 The default is daemon. This setting has no effect if the "[log file](#)"
387 setting is a non-empty string (either set in the per-modules settings, or
388 inherited from the global settings).
392 This parameter allows you to specify the syslog tag to use when logging
393 messages from the rsync daemon. The default is "rsyncd". This setting has
394 no effect if the "[log file](#)" setting is a non-empty string (either set in
395 the per-modules settings, or inherited from the global settings).
397 For example, if you wanted each authenticated user's name to be included in
398 the syslog tag, you could do something like this:
400 > syslog tag = rsyncd.%RSYNC_USER_NAME%
404 This parameter allows you to control the maximum amount of verbose
405 information that you'll allow the daemon to generate (since the information
406 goes into the log file). The default is 1, which allows the client to
407 request one level of verbosity.
409 This also affects the user's ability to request higher levels of `--info`
410 and `--debug` logging. If the max value is 2, then no info and/or debug
411 value that is higher than what would be set by `-vv` will be honored by the
412 daemon in its logging. To see how high of a verbosity level you need to
413 accept for a particular info/debug level, refer to `rsync --info=help` and
414 `rsync --debug=help`. For instance, it takes max-verbosity 4 to be able to
415 output debug TIME2 and FLIST3.
419 This parameter specifies the file to use to support the "[max connections](#)"
420 parameter. The rsync daemon uses record locking on this file to ensure that
421 the max connections limit is not exceeded for the modules sharing the lock
422 file. The default is `/var/run/rsyncd.lock`.
426 This parameter determines whether clients will be able to upload files or
427 not. If "read only" is true then any attempted uploads will fail. If
428 "read only" is false then uploads will be possible if file permissions on
429 the daemon side allow them. The default is for all modules to be read only.
431 Note that "[auth users](#)" can override this setting on a per-user basis.
435 This parameter determines whether clients will be able to download files or
436 not. If "write only" is true then any attempted downloads will fail. If
437 "write only" is false then downloads will be possible if file permissions
438 on the daemon side allow them. The default is for this parameter to be
441 Helpful hint: you probably want to specify "refuse options = delete" for a
446 When set to True, this parameter tells the rsync daemon to open files with
448 (on systems that support it) to avoid changing the access time of the files
449 that are being transferred. If your OS does not support the O_NOATIME flag
450 then rsync will silently ignore this option. Note also that some
451 filesystems are mounted to avoid updating the atime on read access even
452 without the O_NOATIME flag being set.
454 When set to False, this parameters ensures that files on the server are not
455 opened with O_NOATIME.
457 When set to Unset (the default) the user controls the setting via
462 This parameter determines whether this module is listed when the client
463 asks for a listing of available modules. In addition, if this is false,
464 the daemon will pretend the module does not exist when a client denied by
465 "[hosts allow](#)" or "[hosts deny](#)" attempts to access it. Realize that if
466 "[reverse lookup](#)" is disabled globally but enabled for the module, the
467 resulting reverse lookup to a potentially client-controlled DNS server may
468 still reveal to the client that it hit an existing module. The default is
469 for modules to be listable.
473 This parameter specifies the user name or user ID that file transfers to
474 and from that module should take place as when the daemon was run as root.
475 In combination with the "[gid](#)" parameter this determines what file
476 permissions are available. The default when run by a super-user is to
477 switch to the system's "nobody" user. The default for a non-super-user is
478 to not try to change the user. See also the "[gid](#)" parameter.
480 The RSYNC_USER_NAME environment variable may be used to request that rsync
481 run as the authorizing user. For example, if you want a rsync to run as
482 the same user that was received for the rsync authentication, this setup is
485 > uid = %RSYNC_USER_NAME%
490 This parameter specifies one or more group names/IDs that will be used when
491 accessing the module. The first one will be the default group, and any
492 extra ones be set as supplemental groups. You may also specify a "`*`" as
493 the first gid in the list, which will be replaced by all the normal groups
494 for the transfer's user (see "[uid](#)"). The default when run by a super-user
495 is to switch to your OS's "nobody" (or perhaps "nogroup") group with no
496 other supplementary groups. The default for a non-super-user is to not
497 change any group attributes (and indeed, your OS may not allow a
498 non-super-user to try to change their group settings).
500 The specified list is normally split into tokens based on spaces and
501 commas. However, if the list starts with a comma, then the list is only
502 split on commas, which allows a group name to contain a space. In either
503 case any leading and/or trailing whitespace is removed from the tokens and
504 empty tokens are ignored.
508 This parameter specifies a uid under which the daemon will run. The daemon
509 usually runs as user root, and when this is left unset the user is left
510 unchanged. See also the "[uid](#)" parameter.
514 This parameter specifies a gid under which the daemon will run. The daemon
515 usually runs as group root, and when this is left unset, the group is left
516 unchanged. See also the "[gid](#)" parameter.
520 Setting "fake super = yes" for a module causes the daemon side to behave as
521 if the `--fake-super` 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.
527 The daemon has its own filter chain that determines what files it will let
528 the client access. This chain is not sent to the client and is independent
529 of any filters the client may have specified. Files excluded by the daemon
530 filter chain (`daemon-excluded` files) are treated as non-existent if the
531 client tries to pull them, are skipped with an error message if the client
532 tries to push them (triggering exit code 23), and are never deleted from
533 the module. You can use daemon filters to prevent clients from downloading
534 or tampering with private administrative files, such as files you may add
535 to support uid/gid name translations.
537 The daemon filter chain is built from the "filter", "[include from](#)",
538 "[include](#)", "[exclude from](#)", and "[exclude](#)" parameters, in that order of
539 priority. Anchored patterns are anchored at the root of the module. To
540 prevent access to an entire subtree, for example, "`/secret`", you **must**
541 exclude everything in the subtree; the easiest way to do this is with a
542 triple-star pattern like "`/secret/***`".
544 The "filter" parameter takes a space-separated list of daemon filter rules,
545 though it is smart enough to know not to split a token at an internal space
546 in a rule (e.g. "`- /foo - /bar`" is parsed as two rules). You may specify
547 one or more merge-file rules using the normal syntax. Only one "filter"
548 parameter can apply to a given module in the config file, so put all the
549 rules you want in a single parameter. Note that per-directory merge-file
550 rules do not provide as much protection as global rules, but they can be
551 used to make `--delete` work better during a client download operation if
552 the per-dir merge files are included in the transfer and the client
553 requests that they be used.
557 This parameter takes a space-separated list of daemon exclude patterns. As
558 with the client `--exclude` option, patterns can be qualified with "`- `" or
559 "`+ `" to explicitly indicate exclude/include. Only one "exclude" parameter
560 can apply to a given module. See the "filter" parameter for a description
561 of how excluded files affect the daemon.
565 Use an "include" to override the effects of the "[exclude](#)" parameter. Only
566 one "include" parameter can apply to a given module. See the "[filter](#)"
567 parameter for a description of how excluded files affect the daemon.
571 This parameter specifies the name of a file on the daemon that contains
572 daemon exclude patterns, one per line. Only one "exclude from" parameter
573 can apply to a given module; if you have multiple exclude-from files, you
574 can specify them as a merge file in the "[filter](#)" parameter. See the
575 "[filter](#)" parameter for a description of how excluded files affect the
580 Analogue of "[exclude from](#)" for a file of daemon include patterns. Only one
581 "include from" parameter can apply to a given module. See the "[filter](#)"
582 parameter for a description of how excluded files affect the daemon.
586 This parameter allows you to specify a set of comma-separated chmod strings
587 that will affect the permissions of all incoming files (files that are
588 being received by the daemon). These changes happen after all other
589 permission calculations, and this will even override destination-default
590 and/or existing permissions when the client does not specify `--perms`.
591 See the description of the `--chmod` rsync option and the **chmod**(1)
592 manpage for information on the format of this string.
596 This parameter allows you to specify a set of comma-separated chmod strings
597 that will affect the permissions of all outgoing files (files that are
598 being sent out from the daemon). These changes happen first, making the
599 sent permissions appear to be different than those stored in the filesystem
600 itself. For instance, you could disable group write permissions on the
601 server while having it appear to be on to the clients. See the description
602 of the `--chmod` rsync option and the **chmod**(1) manpage for information
603 on the format of this string.
607 This parameter specifies a comma and/or space-separated list of
608 authorization rules. In its simplest form, you list the usernames that
609 will be allowed to connect to this module. The usernames do not need to
610 exist on the local system. The rules may contain shell wildcard characters
611 that will be matched against the username provided by the client for
612 authentication. If "auth users" is set then the client will be challenged
613 to supply a username and password to connect to the module. A challenge
614 response authentication protocol is used for this exchange. The plain text
615 usernames and passwords are stored in the file specified by the
616 "[secrets file](#)" parameter. The default is for all users to be able to
617 connect without a password (this is called "anonymous rsync").
619 In addition to username matching, you can specify groupname matching via a
620 '@' prefix. When using groupname matching, the authenticating username
621 must be a real user on the system, or it will be assumed to be a member of
622 no groups. For example, specifying "@rsync" will match the authenticating
623 user if the named user is a member of the rsync group.
625 Finally, options may be specified after a colon (:). The options allow you
626 to "deny" a user or a group, set the access to "ro" (read-only), or set the
627 access to "rw" (read/write). Setting an auth-rule-specific ro/rw setting
628 overrides the module's "[read only](#)" setting.
630 Be sure to put the rules in the order you want them to be matched, because
631 the checking stops at the first matching user or group, and that is the
632 only auth that is checked. For example:
634 > auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam
636 In the above rule, user joe will be denied access no matter what. Any user
637 that is in the group "guest" is also denied access. The user "admin" gets
638 access in read/write mode, but only if the admin user is not in group
639 "guest" (because the admin user-matching rule would never be reached if the
640 user is in group "guest"). Any other user who is in group "rsync" will get
641 read-only access. Finally, users susan, joe, and sam get the ro/rw setting
642 of the module, but only if the user didn't match an earlier group-matching
645 If you need to specify a user or group name with a space in it, start your
646 list with a comma to indicate that the list should only be split on commas
647 (though leading and trailing whitespace will also be removed, and empty
648 entries are just ignored). For example:
650 > auth users = , joe:deny, @Some Group:deny, admin:rw, @RO Group:ro
652 See the description of the secrets file for how you can have per-user
653 passwords as well as per-group passwords. It also explains how a user can
654 authenticate using their user password or (when applicable) a group
655 password, depending on what rule is being authenticated.
657 See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE
658 SHELL CONNECTION" in **rsync**(1) for information on how handle an
659 rsyncd.conf-level username that differs from the remote-shell-level
660 username when using a remote shell to connect to an rsync daemon.
664 This parameter specifies the name of a file that contains the
665 username:password and/or @groupname:password pairs used for authenticating
666 this module. This file is only consulted if the "[auth users](#)" parameter is
667 specified. The file is line-based and contains one name:password pair per
668 line. Any line has a hash (#) as the very first character on the line is
669 considered a comment and is skipped. The passwords can contain any
670 characters but be warned that many operating systems limit the length of
671 passwords that can be typed at the client end, so you may find that
672 passwords longer than 8 characters don't work.
674 The use of group-specific lines are only relevant when the module is being
675 authorized using a matching "@groupname" rule. When that happens, the user
676 can be authorized via either their "username:password" line or the
677 "@groupname:password" line for the group that triggered the authentication.
679 It is up to you what kind of password entries you want to include, either
680 users, groups, or both. The use of group rules in "[auth users](#)" does not
681 require that you specify a group password if you do not want to use shared
684 There is no default for the "secrets file" parameter, you must choose a
685 name (such as `/etc/rsyncd.secrets`). The file must normally not be
686 readable by "other"; see "[strict modes](#)". If the file is not found or is
687 rejected, no logins for an "[auth users](#)" module will be possible.
691 This parameter determines whether or not the permissions on the secrets
692 file will be checked. If "strict modes" is true, then the secrets file
693 must not be readable by any user ID other than the one that the rsync
694 daemon is running under. If "strict modes" is false, the check is not
695 performed. The default is true. This parameter was added to accommodate
696 rsync running on the Windows operating system.
700 This parameter allows you to specify a list of comma- and/or
701 whitespace-separated patterns that are matched against a connecting
702 client's hostname and IP address. If none of the patterns match, then the
703 connection is rejected.
705 Each pattern can be in one of six forms:
707 - a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address of
708 the form a:b:c::d:e:f. In this case the incoming machine's IP address
710 - an address/mask in the form ipaddr/n where ipaddr is the IP address and n
711 is the number of one bits in the netmask. All IP addresses which match
712 the masked IP address will be allowed in.
713 - an address/mask in the form ipaddr/maskaddr where ipaddr is the IP
714 address and maskaddr is the netmask in dotted decimal notation for IPv4,
715 or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
716 addresses which match the masked IP address will be allowed in.
717 - a hostname pattern using wildcards. If the hostname of the connecting IP
718 (as determined by a reverse lookup) matches the wildcarded name (using
719 the same rules as normal Unix filename matching), the client is allowed
720 in. This only works if "[reverse lookup](#)" is enabled (the default).
721 - a hostname. A plain hostname is matched against the reverse DNS of the
722 connecting IP (if "[reverse lookup](#)" is enabled), and/or the IP of the
723 given hostname is matched against the connecting IP (if "[forward lookup](#)"
724 is enabled, as it is by default). Any match will be allowed in.
725 - an '@' followed by a netgroup name, which will match if the reverse DNS
726 of the connecting IP is in the specified netgroup.
728 Note IPv6 link-local addresses can have a scope in the address
733 > fe80::%link1/ffff:ffff:ffff:ffff::
735 You can also combine "hosts allow" with "[hosts deny](#)" as a way to add
736 exceptions to your deny list. When both parameters are specified, the
737 "hosts allow" parameter is checked first and a match results in the client
738 being able to connect. A non-allowed host is then matched against the
739 "[hosts deny](#)" list to see if it should be rejected. A host that does not
740 match either list is allowed to connect.
742 The default is no "hosts allow" parameter, which means all hosts can
747 This parameter allows you to specify a list of comma- and/or
748 whitespace-separated patterns that are matched against a connecting clients
749 hostname and IP address. If the pattern matches then the connection is
750 rejected. See the "[hosts allow](#)" parameter for more information.
752 The default is no "hosts deny" parameter, which means all hosts can
757 Controls whether the daemon performs a reverse lookup on the client's IP
758 address to determine its hostname, which is used for "[hosts allow](#)" &
759 "[hosts deny](#)" checks and the "%h" log escape. This is enabled by default,
760 but you may wish to disable it to save time if you know the lookup will not
761 return a useful result, in which case the daemon will use the name
762 "UNDETERMINED" instead.
764 If this parameter is enabled globally (even by default), rsync performs the
765 lookup as soon as a client connects, so disabling it for a module will not
766 avoid the lookup. Thus, you probably want to disable it globally and then
767 enable it for modules that need the information.
771 Controls whether the daemon performs a forward lookup on any hostname
772 specified in an hosts allow/deny setting. By default this is enabled,
773 allowing the use of an explicit hostname that would not be returned by
774 reverse DNS of the connecting IP.
778 This parameter tells rsyncd to ignore I/O errors on the daemon when
779 deciding whether to run the delete phase of the transfer. Normally rsync
780 skips the `--delete` step if any I/O errors have occurred in order to
781 prevent disastrous deletion due to a temporary resource shortage or other
782 I/O error. In some cases this test is counter productive so you can use
783 this parameter to turn off this behavior.
785 0. `ignore nonreadable`
787 This tells the rsync daemon to completely ignore files that are not
788 readable by the user. This is useful for public archives that may have some
789 non-readable files among the directories, and the sysadmin doesn't want
790 those files to be seen at all.
792 0. `transfer logging`
794 This parameter enables per-file logging of downloads and uploads in a
795 format somewhat similar to that used by ftp daemons. The daemon always
796 logs the transfer at the end, so if a transfer is aborted, no mention will
797 be made in the log file.
799 If you want to customize the log lines, see the "[log format](#)" parameter.
803 This parameter allows you to specify the format used for logging file
804 transfers when transfer logging is enabled. The format is a text string
805 containing embedded single-character escape sequences prefixed with a
806 percent (%) character. An optional numeric field width may also be
807 specified between the percent and the escape letter (e.g.
808 "`%-50n %8l %07p`"). In addition, one or more apostrophes may be specified
809 prior to a numerical escape to indicate that the numerical value should be
810 made more human-readable. The 3 supported levels are the same as for the
811 `--human-readable` command-line option, though the default is for
812 human-readability to be off. Each added apostrophe increases the level
813 (e.g. "`%''l %'b %f`").
815 The default log format is "`%o %h [%a] %m (%u) %f %l`", and a "`%t [%p] `"
816 is always prefixed when using the "[log file](#)" parameter. (A perl script
817 that will summarize this default log format is included in the rsync source
818 code distribution in the "support" subdirectory: rsyncstats.)
820 The single-character escapes that are understood are as follows:
822 - %a the remote IP address (only available for a daemon)
823 - %b the number of bytes actually transferred
824 - %B the permission bits of the file (e.g. rwxrwxrwt)
825 - %c the total size of the block checksums received for the basis file
827 - %C the full-file checksum if it is known for the file. For older rsync
828 protocols/versions, the checksum was salted, and is thus not a useful
829 value (and is not displayed when that is the case). For the checksum to
830 output for a file, either the `--checksum` option must be in-effect or
831 the file must have been transferred without a salted checksum being used.
832 See the `--checksum-choice` option for a way to choose the algorithm.
833 - %f the filename (long form on sender; no trailing "/")
834 - %G the gid of the file (decimal) or "DEFAULT"
835 - %h the remote host name (only available for a daemon)
836 - %i an itemized list of what is being updated
837 - %l the length of the file in bytes
838 - %L the string "` -> SYMLINK`", "` => HARDLINK`", or "" (where `SYMLINK`
839 or `HARDLINK` is a filename)
841 - %M the last-modified time of the file
842 - %n the filename (short form; trailing "/" on dir)
843 - %o the operation, which is "send", "recv", or "del." (the latter includes
845 - %p the process ID of this rsync session
847 - %t the current date time
848 - %u the authenticated username or an empty string
849 - %U the uid of the file (decimal)
851 For a list of what the characters mean that are output by "%i", see the
852 `--itemize-changes` option in the rsync manpage.
854 Note that some of the logged output changes when talking with older rsync
855 versions. For instance, deleted files were only output as verbose messages
856 prior to rsync 2.6.4.
860 This parameter allows you to override the clients choice for I/O timeout
861 for this module. Using this parameter you can ensure that rsync won't wait
862 on a dead client forever. The timeout is specified in seconds. A value of
863 zero means no timeout and is the default. A good choice for anonymous rsync
864 daemons may be 600 (giving a 10 minute timeout).
868 This parameter allows you to specify a space-separated list of rsync
869 command-line options that will be refused by your rsync daemon. You may
870 specify the full option name, its one-letter abbreviation, or a wild-card
871 string that matches multiple options. Beginning in 3.2.0, you can also
872 negate a match term by starting it with a "!".
874 When an option is refused, the daemon prints an error message and exits.
876 For example, this would refuse `--checksum` (`-c`) and all the various
879 > refuse options = c delete
881 The reason the above refuses all delete options is that the options imply
882 `--delete`, and implied options are refused just like explicit options.
884 The use of a negated match allows you to fine-tune your refusals after a
885 wild-card, such as this:
887 > refuse options = delete-* !delete-during
889 Negated matching can also turn your list of refused options into a list of
890 accepted options. To do this, begin the list with a "`*`" (to refuse all
891 options) and then specify one or more negated matches to accept. For
894 > refuse options = * !a !v !compress*
896 Don't worry that the "`*`" will refuse certain vital options such as
897 `--dry-run`, `--server`, `--no-iconv`, `--protect-args`, etc. These
898 important options are not matched by wild-card, so they must be overridden
899 by their exact name. For instance, if you're forcing iconv transfers you
900 could use something like this:
902 > refuse options = * no-iconv !a !v
904 As an additional aid (beginning in 3.2.0), refusing (or "`!refusing`") the
905 "a" or "archive" option also affects all the options that the `--archive`
906 option implies (`-rdlptgoD`), but only if the option is matched explicitly
907 (not using a wildcard). If you want to do something tricky, you can use
908 "`archive*`" to avoid this side-effect, but keep in mind that no normal
909 rsync client ever sends the actual archive option to the server.
911 As an additional safety feature, the refusal of "delete" also refuses
912 `remove-source-files` when the daemon is the sender; if you want the latter
913 without the former, instead refuse "`delete-*`" as that refuses all the
914 delete modes without affecting `--remove-source-files`. (Keep in mind that
915 the client's `--delete` option typically results in `--delete-during`.)
917 When un-refusing delete options, you should either specify "`!delete*`" (to
918 accept all delete options) or specify a limited set that includes "delete",
921 > refuse options = * !a !delete !delete-during
923 ... whereas this accepts any delete option except `--delete-after`:
925 > refuse options = * !a !delete* delete-after
927 A note on refusing "compress": it may be better to set the "[dont compress](#)"
928 daemon parameter to "`*`" and ensure that `RSYNC_COMPRESS_LIST=zlib` is set
929 in the environment of the daemon in order to disable compression silently
930 instead of returning an error that forces the client to remove the `-z`
933 If you are un-refusing the compress option, you may want to match
934 "`!compress*`" if you also want to allow the `--compress-level` option.
936 Note that the "copy-devices" & "write-devices" options are refused by
937 default, but they can be explicitly accepted with "`!copy-devices`" and/or
938 "`!write-devices`". The options "log-file" and "log-file-format" are
939 forcibly refused and cannot be accepted.
941 Here are all the options that are not matched by wild-cards:
943 - `--server`: Required for rsync to even work.
944 - `--rsh`, `-e`: Required to convey compatibility flags to the server.
945 - `--out-format`: This is required to convey output behavior to a remote
946 receiver. While rsync passes the older alias `--log-format` for
947 compatibility reasons, this options should not be confused with
949 - `--sender`: Use "[write only](#)" parameter instead of refusing this.
950 - `--dry-run`, `-n`: Who would want to disable this?
951 - `--protect-args`, `-s`: This actually makes transfers safer.
952 - `--from0`, `-0`: Makes it easier to accept/refuse `--files-from` without
953 affecting this helpful modifier.
954 - `--iconv`: This is auto-disabled based on "[charset](#)" parameter.
955 - `--no-iconv`: Most transfers use this option.
956 - `--checksum-seed`: Is a fairly rare, safe option.
957 - `--write-devices`: Is non-wild but also auto-disabled.
961 **NOTE:** This parameter currently has no effect except in one instance: if
962 it is set to "`*`" then it minimizes or disables compression for all files
963 (for those that don't want to refuse the `--compress` option completely).
965 This parameter allows you to select filenames based on wildcard patterns
966 that should not be compressed when pulling files from the daemon (no
967 analogous parameter exists to govern the pushing of files to a daemon).
968 Compression can be expensive in terms of CPU usage, so it is usually good
969 to not try to compress files that won't compress well, such as already
972 The "dont compress" parameter takes a space-separated list of
973 case-insensitive wildcard patterns. Any source filename matching one of the
974 patterns will be compressed as little as possible during the transfer. If
975 the compression algorithm has an "off" level, then no compression occurs
976 for those files. If an algorithms has the ability to change the level in
977 mid-stream, it will be minimized to reduce the CPU usage as much as
980 See the `--skip-compress` parameter in the **rsync**(1) manpage for the
981 list of file suffixes that are skipped by default if this parameter is not
984 0. `early exec`, `pre-xfer exec`, `post-xfer exec`
986 You may specify a command to be run in the early stages of the connection,
987 or right before and/or after the transfer. If the `early exec` or
988 `pre-xfer exec` command returns an error code, the transfer is aborted
989 before it begins. Any output from the `pre-xfer exec` command on stdout
990 (up to several KB) will be displayed to the user when aborting, but is
991 _not_ displayed if the script returns success. The other programs cannot
992 send any text to the user. All output except for the `pre-xfer exec`
993 stdout goes to the corresponding daemon's stdout/stderr, which is typically
994 discarded. See the `--no-detatch` option for a way to see the daemon's
995 output, which can assist with debugging.
997 Note that the `early exec` 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 `lock file` and `max connections` to avoid concurrency
1001 issues. If the client rsync specified the `--early-input=FILE` 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.
1005 Note that the `post-xfer exec` command is still run even if one of the
1006 other scripts returns an error code. The `pre-xfer exec` command will _not_
1007 be run, however, if the `early exec` command fails.
1009 The following environment variables will be set, though some are specific
1010 to the pre-xfer or the post-xfer environment:
1012 - `RSYNC_MODULE_NAME`: The name of the module being accessed.
1013 - `RSYNC_MODULE_PATH`: The path configured for the module.
1014 - `RSYNC_HOST_ADDR`: The accessing host's IP address.
1015 - `RSYNC_HOST_NAME`: The accessing host's name.
1016 - `RSYNC_USER_NAME`: The accessing user's name (empty if no user).
1017 - `RSYNC_PID`: A unique number for this transfer.
1018 - `RSYNC_REQUEST`: (pre-xfer only) The module/path info specified by the
1019 user. Note that the user can specify multiple source files, so the
1020 request can be something like "mod/path1 mod/path2", etc.
1021 - `RSYNC_ARG#`: (pre-xfer only) The pre-request arguments are set in these
1022 numbered values. RSYNC_ARG0 is always "rsyncd", followed by the options
1023 that were used in RSYNC_ARG1, and so on. There will be a value of "."
1024 indicating that the options are done and the path args are beginning --
1025 these contain similar information to RSYNC_REQUEST, but with values
1026 separated and the module name stripped off.
1027 - `RSYNC_EXIT_STATUS`: (post-xfer only) the server side's exit value. This
1028 will be 0 for a successful run, a positive value for an error that the
1029 server generated, or a -1 if rsync failed to exit properly. Note that an
1030 error that occurs on the client side does not currently get sent to the
1031 server side, so this is not the final exit status for the whole transfer.
1032 - `RSYNC_RAW_STATUS`: (post-xfer only) the raw exit value from
1035 Even though the commands can be associated with a particular module, they
1036 are run using the permissions of the user that started the daemon (not the
1037 module's uid/gid setting) without any chroot restrictions.
1039 These settings honor 2 environment variables: use RSYNC_SHELL to set a
1040 shell to use when running the command (which otherwise uses your
1041 **system()** call's default shell), and use RSYNC_NO_XFER_EXEC to disable
1042 both options completely.
1044 ## CONFIG DIRECTIVES
1046 There are currently two config directives available that allow a config file to
1047 incorporate the contents of other files: `&include` and `&merge`. Both allow
1048 a reference to either a file or a directory. They differ in how segregated the
1049 file's contents are considered to be.
1051 The `&include` directive treats each file as more distinct, with each one
1052 inheriting the defaults of the parent file, starting the parameter parsing as
1053 globals/defaults, and leaving the defaults unchanged for the parsing of the
1054 rest of the parent file.
1056 The `&merge` directive, on the other hand, treats the file's contents as if it
1057 were simply inserted in place of the directive, and thus it can set parameters
1058 in a module started in another file, can affect the defaults for other files,
1061 When an `&include` or `&merge` directive refers to a directory, it will read in
1062 all the `*.conf` or `*.inc` files (respectively) that are contained inside that
1063 directory (without any recursive scanning), with the files sorted into alpha
1064 order. So, if you have a directory named "rsyncd.d" with the files "foo.conf",
1065 "bar.conf", and "baz.conf" inside it, this directive:
1067 > &include /path/rsyncd.d
1069 would be the same as this set of directives:
1071 > &include /path/rsyncd.d/bar.conf
1072 > &include /path/rsyncd.d/baz.conf
1073 > &include /path/rsyncd.d/foo.conf
1075 except that it adjusts as files are added and removed from the directory.
1077 The advantage of the `&include` directive is that you can define one or more
1078 modules in a separate file without worrying about unintended side-effects
1079 between the self-contained module files.
1081 The advantage of the `&merge` directive is that you can load config snippets
1082 that can be included into multiple module definitions, and you can also set
1083 global values that will affect connections (such as `motd file`), or globals
1084 that will affect other include files.
1086 For example, this is a useful /etc/rsyncd.conf file:
1089 > log file = /var/log/rsync.log
1090 > pid file = /var/lock/rsync.lock
1092 > &merge /etc/rsyncd.d
1093 > &include /etc/rsyncd.d
1095 This would merge any `/etc/rsyncd.d/*.inc` files (for global values that should
1096 stay in effect), and then include any `/etc/rsyncd.d/*.conf` files (defining
1097 modules without any global-value cross-talk).
1099 ## AUTHENTICATION STRENGTH
1101 The authentication protocol used in rsync is a 128 bit MD4 based challenge
1102 response system. This is fairly weak protection, though (with at least one
1103 brute-force hash-finding algorithm publicly available), so if you want really
1104 top-quality security, then I recommend that you run rsync over ssh. (Yes, a
1105 future version of rsync will switch over to a stronger hashing method.)
1107 Also note that the rsync daemon protocol does not currently provide any
1108 encryption of the data that is transferred over the connection. Only
1109 authentication is provided. Use ssh as the transport if you want encryption.
1111 You can also make use of SSL/TLS encryption if you put rsync behind an
1114 ## SSL/TLS Daemon Setup
1116 When setting up an rsync daemon for access via SSL/TLS, you will need to
1117 configure a TCP proxy (such as haproxy or nginx) as the front-end that handles
1120 - You should limit the access to the backend-rsyncd port to only allow the
1121 proxy to connect. If it is on the same host as the proxy, then configuring
1122 it to only listen on localhost is a good idea.
1123 - You should consider turning on the `proxy protocol` rsync-daemon parameter if
1124 your proxy supports sending that information. The examples below assume that
1127 An example haproxy setup is as follows:
1130 > frontend fe_rsync-ssl
1131 > bind :::874 ssl crt /etc/letsencrypt/example.com/combined.pem
1133 > use_backend be_rsync
1137 > server local-rsync 127.0.0.1:873 check send-proxy
1140 An example nginx proxy setup is as follows:
1146 > listen [::]:874 ssl;
1148 > ssl_certificate /etc/letsencrypt/example.com/fullchain.pem;
1149 > ssl_certificate_key /etc/letsencrypt/example.com/privkey.pem;
1151 > proxy_pass localhost:873;
1152 > proxy_protocol on; # Requires rsyncd.conf "proxy protocol = true"
1154 > proxy_connect_timeout 5s;
1159 ## DAEMON CONFIG EXAMPLES
1161 A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
1162 `/home/ftp` would be:
1167 > comment = ftp export area
1170 A more sophisticated example would be:
1176 > max connections = 4
1177 > syslog facility = local5
1178 > pid file = /var/run/rsyncd.pid
1181 > path = /var/ftp/./pub
1182 > comment = whole ftp area (approx 6.1 GB)
1185 > path = /var/ftp/./pub/samba
1186 > comment = Samba ftp area (approx 300 MB)
1189 > path = /var/ftp/./pub/rsync
1190 > comment = rsync ftp area (approx 6 MB)
1193 > path = /public_html/samba
1194 > comment = Samba WWW pages (approx 240 MB)
1198 > comment = CVS repository (requires authentication)
1199 > auth users = tridge, susan
1200 > secrets file = /etc/rsyncd.secrets
1203 The /etc/rsyncd.secrets file would look something like this:
1210 /etc/rsyncd.conf or rsyncd.conf
1214 [**rsync**(1)](rsync.1), [**rsync-ssl**(1)](rsync-ssl.1)
1218 Please report bugs! The rsync bug tracking system is online at
1219 <https://rsync.samba.org/>.
1223 This manpage is current for version @VERSION@ of rsync.
1227 Rsync is distributed under the GNU General Public License. See the file
1228 [COPYING](COPYING) for details.
1230 An rsync web site is available at <https://rsync.samba.org/> and its github
1231 project is <https://github.com/WayneD/rsync>.
1235 Thanks to Warren Stanley for his original idea and patch for the rsync daemon.
1236 Thanks to Karsten Thygesen for his many suggestions and documentation!
1240 Rsync was originally written by Andrew Tridgell and Paul Mackerras. Many
1241 people have later contributed to it. It is currently maintained by Wayne
1244 Mailing lists for support and development are available at
1245 <https://lists.samba.org/>.