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 If the value contains a "/./" element then the path will be divided at that
168 point into a chroot dir and an inner-chroot subdir. If [`use chroot`](#)
169 is set to false, though, the extraneous dot dir is just cleaned out of the
170 path. An example of this idiom is:
172 > path = /var/rsync/./module1
174 This will (when chrooting) chroot to "/var/rsync" and set the inside-chroot
177 You may base the path's value off of an environment variable by surrounding
178 the variable name with percent signs. You can even reference a variable
179 that is set by rsync when the user connects. For example, this would use
180 the authorizing user's name in the path:
182 > path = /home/%RSYNC_USER_NAME%
184 It is fine if the path includes internal spaces -- they will be retained
185 verbatim (which means that you shouldn't try to escape them). If your
186 final directory has a trailing space (and this is somehow not something you
187 wish to fix), append a trailing slash to the path to avoid losing the
192 If "use chroot" is true, the rsync daemon will chroot to the "[path](#)" before
193 starting the file transfer with the client. This has the advantage of
194 extra protection against possible implementation security holes, but it has
195 the disadvantages of requiring super-user privileges, of not being able to
196 follow symbolic links that are either absolute or outside of the new root
197 path, and of complicating the preservation of users and groups by name (see
200 If `use chroot` is not set, it defaults to trying to enable a chroot but
201 allows the daemon to continue (after logging a warning) if it fails. The
202 one exception to this is when a module's [`path`](#) has a "/./" chroot
203 divider in it -- this causes an unset value to be treated as true for that
206 Prior to rsync 3.2.7, the default value was "true". The new default makes
207 it easier to setup an rsync daemon as a non-root user or to run a daemon on
208 a system where chroot fails. Explicitly setting the value to true in the
209 rsyncd.conf file will always require the chroot to succeed.
211 It is also possible to specify a dot-dir in the module's "[path](#)" to
212 indicate that you want to chdir to the earlier part of the path and then
213 serve files from inside the latter part of the path (with default
214 sanitizing and symlink munging). This can be useful if you need some
215 library dirs inside the chroot (typically for uid & gid lookups) but don't
216 want to put the lib dir into the top of the served path (even though they
217 can be hidden with an [`exclude`](#) directive). However, a better choice
218 for a modern rsync setup is to use a [`name converter`](#)" and try to
219 avoid inner lib dirs altogether. See also the [`daemon chroot`](#)
220 parameter, which causes rsync to chroot into its own chroot area before
221 doing any path-related chrooting.
223 If the daemon is serving the "/" dir (either directly or due to being
224 chrooted to the module's path), rsync does not do any extra path sanitizing
225 or (default) munging. When it has to limit access to a particular subdir
226 (either due to chroot being disabled or having an inside-chroot path set),
227 rsync will munge symlinks (by default) and sanitize paths. Those that
228 dislike munged symlinks (and really, really trust their users to not break
229 out of the subdir) can disable the symlink munging via the "[munge
230 symlinks](#)" parameter. Sanitizing paths trims ".." path elements from
231 args that rsync believes would escape the module hierarchy, and also
232 substitutes leading slashes in absolute paths with the module's path (so
233 that options such as `--backup-dir` & `--compare-dest` interpret an
234 absolute path as rooted in the module's "[path](#)" dir).
236 When a chroot is in effect *and* the "[name converter](#)" parameter is
237 *not* set, the "[numeric ids](#)" parameter will default to being enabled
238 (disabling name lookups). This means that if you manually setup
239 name-lookup libraries in your chroot (instead of using a name converter)
240 that you need to explicitly set `numeric ids = false` for rsync to do name
243 If you copy library resources into the module's chroot area, you should
244 protect them through your OS's normal user/group or ACL settings (to
245 prevent the rsync module's user from being able to change them), and then
246 hide them from the user's view via "[exclude](#)" (see how in the discussion of
247 that parameter). However, it's easier and safer to setup a name converter.
251 This parameter specifies a path to which the daemon will chroot before
252 beginning communication with clients. Module paths (and any "[use chroot](#)"
253 settings) will then be related to this one. This lets you choose if you
254 want the whole daemon to be chrooted (with this setting), just the
255 transfers to be chrooted (with "[use chroot](#)"), or both. Keep in mind that
256 the "daemon chroot" area may need various OS/lib/etc files installed to
257 allow the daemon to function. By default the daemon runs without any
262 When this parameter is enabled, all incoming connections must start with a
263 V1 or V2 proxy protocol header. If the header is not found, the connection
266 Setting this to `true` requires a proxy server to forward source IP
267 information to rsync, allowing you to log proper IP/host info and make use
268 of client-oriented IP restrictions. The default of `false` means that the
269 IP information comes directly from the socket's metadata. If rsync is not
270 behind a proxy, this should be disabled.
272 _CAUTION_: using this option can be dangerous if you do not ensure that
273 only the proxy is allowed to connect to the rsync port. If any non-proxied
274 connections are allowed through, the client will be able to use a modified
275 rsync to spoof any remote IP address that they desire. You can lock this
276 down using something like iptables `-uid-owner root` rules (for strict
277 localhost access), various firewall rules, or you can require password
278 authorization so that any spoofing by users will not grant extra access.
280 This setting is global. If you need some modules to require this and not
281 others, then you will need to setup multiple rsync daemon processes on
286 This parameter lets you specify a program that will be run by the rsync
287 daemon to do user & group conversions between names & ids. This script
288 is started prior to any chroot being setup, and runs as the daemon user
289 (not the transfer user). You can specify a fully qualified pathname or
290 a program name that is on the $PATH.
292 The program can be used to do normal user & group lookups without having to
293 put any extra files into the chroot area of the module *or* you can do
294 customized conversions.
296 The nameconvert program has access to all of the environment variables that
297 are described in the section on `pre-xfer exec`. This is useful if you
298 want to customize the conversion using information about the module and/or
301 There is a sample python script in the support dir named "nameconvert" that
302 implements the normal user & group lookups. Feel free to customize it or
303 just use it as documentation to implement your own.
307 Enabling this parameter disables the mapping of users and groups by name
308 for the current daemon module. This prevents the daemon from trying to
309 load any user/group-related files or libraries. This enabling makes the
310 transfer behave as if the client had passed the `--numeric-ids`
311 command-line option. By default, this parameter is enabled for chroot
312 modules and disabled for non-chroot modules. Also keep in mind that
313 uid/gid preservation requires the module to be running as root (see "[uid](#)")
314 or for "[fake super](#)" to be configured.
316 A chroot-enabled module should not have this parameter set to false unless
317 you're using a "[name converter](#)" program *or* you've taken steps to ensure
318 that the module has the necessary resources it needs to translate names and
319 that it is not possible for a user to change those resources.
323 This parameter tells rsync to modify all symlinks in the same way as the
324 (non-daemon-affecting) `--munge-links` command-line option (using a method
325 described below). This should help protect your files from user trickery
326 when your daemon module is writable. The default is disabled when
327 "[use chroot](#)" is on with an inside-chroot path of "/", OR if "[daemon chroot](#)"
328 is on, otherwise it is enabled.
330 If you disable this parameter on a daemon that is not read-only, there are
331 tricks that a user can play with uploaded symlinks to access
332 daemon-excluded items (if your module has any), and, if "[use chroot](#)" is
333 off, rsync can even be tricked into showing or changing data that is
334 outside the module's path (as access-permissions allow).
336 The way rsync disables the use of symlinks is to prefix each one with the
337 string "/rsyncd-munged/". This prevents the links from being used as long
338 as that directory does not exist. When this parameter is enabled, rsync
339 will refuse to run if that path is a directory or a symlink to a directory.
340 When using the "munge symlinks" parameter in a chroot area that has an
341 inside-chroot path of "/", you should add "/rsyncd-munged/" to the exclude
342 setting for the module so that a user can't try to create it.
344 Note: rsync makes no attempt to verify that any pre-existing symlinks in
345 the module's hierarchy are as safe as you want them to be (unless, of
346 course, it just copied in the whole hierarchy). If you setup an rsync
347 daemon on a new area or locally add symlinks, you can manually protect your
348 symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
349 every symlink's value. There is a perl script in the support directory of
350 the source code named "munge-symlinks" that can be used to add or remove
351 this prefix from your symlinks.
353 When this parameter is disabled on a writable module and "[use chroot](#)" is
354 off (or the inside-chroot path is not "/"), incoming symlinks will be
355 modified to drop a leading slash and to remove ".." path elements that
356 rsync believes will allow a symlink to escape the module's hierarchy.
357 There are tricky ways to work around this, though, so you had better trust
358 your users if you choose this combination of parameters.
362 This specifies the name of the character set in which the module's
363 filenames are stored. If the client uses an `--iconv` option, the daemon
364 will use the value of the "charset" parameter regardless of the character
365 set the client actually passed. This allows the daemon to support charset
366 conversion in a chroot module without extra files in the chroot area, and
367 also ensures that name-translation is done in a consistent manner. If the
368 "charset" parameter is not set, the `--iconv` option is refused, just as if
369 "iconv" had been specified via "[refuse options](#)".
371 If you wish to force users to always use `--iconv` for a particular module,
372 add "no-iconv" to the "[refuse options](#)" parameter. Keep in mind that this
373 will restrict access to your module to very new rsync clients.
377 This parameter allows you to specify the maximum number of simultaneous
378 connections you will allow. Any clients connecting when the maximum has
379 been reached will receive a message telling them to try later. The default
380 is 0, which means no limit. A negative value disables the module. See
381 also the "[lock file](#)" parameter.
385 When the "log file" parameter is set to a non-empty string, the rsync
386 daemon will log messages to the indicated file rather than using syslog.
387 This is particularly useful on systems (such as AIX) where **syslog()**
388 doesn't work for chrooted programs. The file is opened before **chroot()**
389 is called, allowing it to be placed outside the transfer. If this value is
390 set on a per-module basis instead of globally, the global log will still
391 contain any authorization failures or config-file error messages.
393 If the daemon fails to open the specified file, it will fall back to using
394 syslog and output an error about the failure. (Note that the failure to
395 open the specified log file used to be a fatal error.)
397 This setting can be overridden by using the `--log-file=FILE` or
398 `--dparam=logfile=FILE` command-line options. The former overrides all the
399 log-file parameters of the daemon and all module settings. The latter sets
400 the daemon's log file and the default for all the modules, which still
401 allows modules to override the default setting.
405 This parameter allows you to specify the syslog facility name to use when
406 logging messages from the rsync daemon. You may use any standard syslog
407 facility name which is defined on your system. Common names are auth,
408 authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user,
409 uucp, local0, local1, local2, local3, local4, local5, local6 and local7.
410 The default is daemon. This setting has no effect if the "[log file](#)"
411 setting is a non-empty string (either set in the per-modules settings, or
412 inherited from the global settings).
416 This parameter allows you to specify the syslog tag to use when logging
417 messages from the rsync daemon. The default is "rsyncd". This setting has
418 no effect if the "[log file](#)" setting is a non-empty string (either set in
419 the per-modules settings, or inherited from the global settings).
421 For example, if you wanted each authenticated user's name to be included in
422 the syslog tag, you could do something like this:
424 > syslog tag = rsyncd.%RSYNC_USER_NAME%
428 This parameter allows you to control the maximum amount of verbose
429 information that you'll allow the daemon to generate (since the information
430 goes into the log file). The default is 1, which allows the client to
431 request one level of verbosity.
433 This also affects the user's ability to request higher levels of `--info`
434 and `--debug` logging. If the max value is 2, then no info and/or debug
435 value that is higher than what would be set by `-vv` will be honored by the
436 daemon in its logging. To see how high of a verbosity level you need to
437 accept for a particular info/debug level, refer to `rsync --info=help` and
438 `rsync --debug=help`. For instance, it takes max-verbosity 4 to be able to
439 output debug TIME2 and FLIST3.
443 This parameter specifies the file to use to support the "[max connections](#)"
444 parameter. The rsync daemon uses record locking on this file to ensure that
445 the max connections limit is not exceeded for the modules sharing the lock
446 file. The default is `/var/run/rsyncd.lock`.
450 This parameter determines whether clients will be able to upload files or
451 not. If "read only" is true then any attempted uploads will fail. If
452 "read only" is false then uploads will be possible if file permissions on
453 the daemon side allow them. The default is for all modules to be read only.
455 Note that "[auth users](#)" can override this setting on a per-user basis.
459 This parameter determines whether clients will be able to download files or
460 not. If "write only" is true then any attempted downloads will fail. If
461 "write only" is false then downloads will be possible if file permissions
462 on the daemon side allow them. The default is for this parameter to be
465 Helpful hint: you probably want to specify "refuse options = delete" for a
470 When set to True, this parameter tells the rsync daemon to open files with
472 (on systems that support it) to avoid changing the access time of the files
473 that are being transferred. If your OS does not support the O_NOATIME flag
474 then rsync will silently ignore this option. Note also that some
475 filesystems are mounted to avoid updating the atime on read access even
476 without the O_NOATIME flag being set.
478 When set to False, this parameters ensures that files on the server are not
479 opened with O_NOATIME.
481 When set to Unset (the default) the user controls the setting via
486 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.
497 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.
504 The RSYNC_USER_NAME environment variable may be used to request that rsync
505 run as the authorizing user. For example, if you want a rsync to run as
506 the same user that was received for the rsync authentication, this setup is
509 > uid = %RSYNC_USER_NAME%
514 This parameter specifies one or more group names/IDs that will be used when
515 accessing the module. The first one will be the default group, and any
516 extra ones be set as supplemental groups. You may also specify a "`*`" as
517 the first gid in the list, which will be replaced by all the normal groups
518 for the transfer's user (see "[uid](#)"). The default when run by a super-user
519 is to switch to your OS's "nobody" (or perhaps "nogroup") group with no
520 other supplementary groups. The default for a non-super-user is to not
521 change any group attributes (and indeed, your OS may not allow a
522 non-super-user to try to change their group settings).
524 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.
532 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.
538 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.
544 Setting "fake super = yes" for a module causes the daemon side to behave as
545 if the `--fake-super` 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.
551 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 (`daemon-excluded` 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.
561 The daemon filter chain is built from the "filter", "[include from](#)",
562 "[include](#)", "[exclude from](#)", and "[exclude](#)" parameters, in that order of
563 priority. Anchored patterns are anchored at the root of the module. To
564 prevent access to an entire subtree, for example, "`/secret`", you **must**
565 exclude everything in the subtree; the easiest way to do this is with a
566 triple-star pattern like "`/secret/***`".
568 The "filter" parameter takes a space-separated list of daemon filter rules,
569 though it is smart enough to know not to split a token at an internal space
570 in a rule (e.g. "`- /foo - /bar`" is parsed as two rules). You may specify
571 one or more merge-file rules using the normal syntax. Only one "filter"
572 parameter can apply to a given module in the config file, so put all the
573 rules you want in a single parameter. Note that per-directory merge-file
574 rules do not provide as much protection as global rules, but they can be
575 used to make `--delete` work better during a client download operation if
576 the per-dir merge files are included in the transfer and the client
577 requests that they be used.
581 This parameter takes a space-separated list of daemon exclude patterns. As
582 with the client `--exclude` option, patterns can be qualified with "`- `" or
583 "`+ `" to explicitly indicate exclude/include. Only one "exclude" parameter
584 can apply to a given module. See the "filter" parameter for a description
585 of how excluded files affect the daemon.
589 Use an "include" to override the effects of the "[exclude](#)" parameter. Only
590 one "include" parameter can apply to a given module. See the "[filter](#)"
591 parameter for a description of how excluded files affect the daemon.
595 This parameter specifies the name of a file on the daemon that contains
596 daemon exclude patterns, one per line. Only one "exclude from" parameter
597 can apply to a given module; if you have multiple exclude-from files, you
598 can specify them as a merge file in the "[filter](#)" parameter. See the
599 "[filter](#)" parameter for a description of how excluded files affect the
604 Analogue of "[exclude from](#)" for a file of daemon include patterns. Only one
605 "include from" parameter can apply to a given module. See the "[filter](#)"
606 parameter for a description of how excluded files affect the daemon.
610 This parameter allows you to specify a set of comma-separated chmod strings
611 that will affect the permissions of all incoming files (files that are
612 being received by the daemon). These changes happen after all other
613 permission calculations, and this will even override destination-default
614 and/or existing permissions when the client does not specify `--perms`.
615 See the description of the `--chmod` rsync option and the **chmod**(1)
616 manpage for information on the format of this string.
620 This parameter allows you to specify a set of comma-separated chmod strings
621 that will affect the permissions of all outgoing files (files that are
622 being sent out from the daemon). These changes happen first, making the
623 sent permissions appear to be different than those stored in the filesystem
624 itself. For instance, you could disable group write permissions on the
625 server while having it appear to be on to the clients. See the description
626 of the `--chmod` rsync option and the **chmod**(1) manpage for information
627 on the format of this string.
631 This parameter specifies a comma and/or space-separated list of
632 authorization rules. In its simplest form, you list the usernames that
633 will be allowed to connect to this module. The usernames do not need to
634 exist on the local system. The rules may contain shell wildcard characters
635 that will be matched against the username provided by the client for
636 authentication. If "auth users" is set then the client will be challenged
637 to supply a username and password to connect to the module. A challenge
638 response authentication protocol is used for this exchange. The plain text
639 usernames and passwords are stored in the file specified by the
640 "[secrets file](#)" parameter. The default is for all users to be able to
641 connect without a password (this is called "anonymous rsync").
643 In addition to username matching, you can specify groupname matching via a
644 '@' prefix. When using groupname matching, the authenticating username
645 must be a real user on the system, or it will be assumed to be a member of
646 no groups. For example, specifying "@rsync" will match the authenticating
647 user if the named user is a member of the rsync group.
649 Finally, options may be specified after a colon (:). The options allow you
650 to "deny" a user or a group, set the access to "ro" (read-only), or set the
651 access to "rw" (read/write). Setting an auth-rule-specific ro/rw setting
652 overrides the module's "[read only](#)" setting.
654 Be sure to put the rules in the order you want them to be matched, because
655 the checking stops at the first matching user or group, and that is the
656 only auth that is checked. For example:
658 > auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam
660 In the above rule, user joe will be denied access no matter what. Any user
661 that is in the group "guest" is also denied access. The user "admin" gets
662 access in read/write mode, but only if the admin user is not in group
663 "guest" (because the admin user-matching rule would never be reached if the
664 user is in group "guest"). Any other user who is in group "rsync" will get
665 read-only access. Finally, users susan, joe, and sam get the ro/rw setting
666 of the module, but only if the user didn't match an earlier group-matching
669 If you need to specify a user or group name with a space in it, start your
670 list with a comma to indicate that the list should only be split on commas
671 (though leading and trailing whitespace will also be removed, and empty
672 entries are just ignored). For example:
674 > auth users = , joe:deny, @Some Group:deny, admin:rw, @RO Group:ro
676 See the description of the secrets file for how you can have per-user
677 passwords as well as per-group passwords. It also explains how a user can
678 authenticate using their user password or (when applicable) a group
679 password, depending on what rule is being authenticated.
681 See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE
682 SHELL CONNECTION" in **rsync**(1) for information on how handle an
683 rsyncd.conf-level username that differs from the remote-shell-level
684 username when using a remote shell to connect to an rsync daemon.
688 This parameter specifies the name of a file that contains the
689 username:password and/or @groupname:password pairs used for authenticating
690 this module. This file is only consulted if the "[auth users](#)" parameter is
691 specified. The file is line-based and contains one name:password pair per
692 line. Any line has a hash (#) as the very first character on the line is
693 considered a comment and is skipped. The passwords can contain any
694 characters but be warned that many operating systems limit the length of
695 passwords that can be typed at the client end, so you may find that
696 passwords longer than 8 characters don't work.
698 The use of group-specific lines are only relevant when the module is being
699 authorized using a matching "@groupname" rule. When that happens, the user
700 can be authorized via either their "username:password" line or the
701 "@groupname:password" line for the group that triggered the authentication.
703 It is up to you what kind of password entries you want to include, either
704 users, groups, or both. The use of group rules in "[auth users](#)" does not
705 require that you specify a group password if you do not want to use shared
708 There is no default for the "secrets file" parameter, you must choose a
709 name (such as `/etc/rsyncd.secrets`). The file must normally not be
710 readable by "other"; see "[strict modes](#)". If the file is not found or is
711 rejected, no logins for an "[auth users](#)" module will be possible.
715 This parameter determines whether or not the permissions on the secrets
716 file will be checked. If "strict modes" is true, then the secrets file
717 must not be readable by any user ID other than the one that the rsync
718 daemon is running under. If "strict modes" is false, the check is not
719 performed. The default is true. This parameter was added to accommodate
720 rsync running on the Windows operating system.
724 This parameter allows you to specify a list of comma- and/or
725 whitespace-separated patterns that are matched against a connecting
726 client's hostname and IP address. If none of the patterns match, then the
727 connection is rejected.
729 Each pattern can be in one of six forms:
731 - a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address of
732 the form a:b:c::d:e:f. In this case the incoming machine's IP address
734 - an address/mask in the form ipaddr/n where ipaddr is the IP address and n
735 is the number of one bits in the netmask. All IP addresses which match
736 the masked IP address will be allowed in.
737 - an address/mask in the form ipaddr/maskaddr where ipaddr is the IP
738 address and maskaddr is the netmask in dotted decimal notation for IPv4,
739 or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
740 addresses which match the masked IP address will be allowed in.
741 - a hostname pattern using wildcards. If the hostname of the connecting IP
742 (as determined by a reverse lookup) matches the wildcarded name (using
743 the same rules as normal Unix filename matching), the client is allowed
744 in. This only works if "[reverse lookup](#)" is enabled (the default).
745 - a hostname. A plain hostname is matched against the reverse DNS of the
746 connecting IP (if "[reverse lookup](#)" is enabled), and/or the IP of the
747 given hostname is matched against the connecting IP (if "[forward lookup](#)"
748 is enabled, as it is by default). Any match will be allowed in.
749 - an '@' followed by a netgroup name, which will match if the reverse DNS
750 of the connecting IP is in the specified netgroup.
752 Note IPv6 link-local addresses can have a scope in the address
757 > fe80::%link1/ffff:ffff:ffff:ffff::
759 You can also combine "hosts allow" with "[hosts deny](#)" as a way to add
760 exceptions to your deny list. When both parameters are specified, the
761 "hosts allow" parameter is checked first and a match results in the client
762 being able to connect. A non-allowed host is then matched against the
763 "[hosts deny](#)" list to see if it should be rejected. A host that does not
764 match either list is allowed to connect.
766 The default is no "hosts allow" parameter, which means all hosts can
771 This parameter allows you to specify a list of comma- and/or
772 whitespace-separated patterns that are matched against a connecting clients
773 hostname and IP address. If the pattern matches then the connection is
774 rejected. See the "[hosts allow](#)" parameter for more information.
776 The default is no "hosts deny" parameter, which means all hosts can
781 Controls whether the daemon performs a reverse lookup on the client's IP
782 address to determine its hostname, which is used for "[hosts allow](#)" &
783 "[hosts deny](#)" checks and the "%h" log escape. This is enabled by default,
784 but you may wish to disable it to save time if you know the lookup will not
785 return a useful result, in which case the daemon will use the name
786 "UNDETERMINED" instead.
788 If this parameter is enabled globally (even by default), rsync performs the
789 lookup as soon as a client connects, so disabling it for a module will not
790 avoid the lookup. Thus, you probably want to disable it globally and then
791 enable it for modules that need the information.
795 Controls whether the daemon performs a forward lookup on any hostname
796 specified in an hosts allow/deny setting. By default this is enabled,
797 allowing the use of an explicit hostname that would not be returned by
798 reverse DNS of the connecting IP.
802 This parameter tells rsyncd to ignore I/O errors on the daemon when
803 deciding whether to run the delete phase of the transfer. Normally rsync
804 skips the `--delete` step if any I/O errors have occurred in order to
805 prevent disastrous deletion due to a temporary resource shortage or other
806 I/O error. In some cases this test is counter productive so you can use
807 this parameter to turn off this behavior.
809 0. `ignore nonreadable`
811 This tells the rsync daemon to completely ignore files that are not
812 readable by the user. This is useful for public archives that may have some
813 non-readable files among the directories, and the sysadmin doesn't want
814 those files to be seen at all.
816 0. `transfer logging`
818 This parameter enables per-file logging of downloads and uploads in a
819 format somewhat similar to that used by ftp daemons. The daemon always
820 logs the transfer at the end, so if a transfer is aborted, no mention will
821 be made in the log file.
823 If you want to customize the log lines, see the "[log format](#)" parameter.
827 This parameter allows you to specify the format used for logging file
828 transfers when transfer logging is enabled. The format is a text string
829 containing embedded single-character escape sequences prefixed with a
830 percent (%) character. An optional numeric field width may also be
831 specified between the percent and the escape letter (e.g.
832 "`%-50n %8l %07p`"). In addition, one or more apostrophes may be specified
833 prior to a numerical escape to indicate that the numerical value should be
834 made more human-readable. The 3 supported levels are the same as for the
835 `--human-readable` command-line option, though the default is for
836 human-readability to be off. Each added apostrophe increases the level
837 (e.g. "`%''l %'b %f`").
839 The default log format is "`%o %h [%a] %m (%u) %f %l`", and a "`%t [%p] `"
840 is always prefixed when using the "[log file](#)" parameter. (A perl script
841 that will summarize this default log format is included in the rsync source
842 code distribution in the "support" subdirectory: rsyncstats.)
844 The single-character escapes that are understood are as follows:
846 - %a the remote IP address (only available for a daemon)
847 - %b the number of bytes actually transferred
848 - %B the permission bits of the file (e.g. rwxrwxrwt)
849 - %c the total size of the block checksums received for the basis file
851 - %C the full-file checksum if it is known for the file. For older rsync
852 protocols/versions, the checksum was salted, and is thus not a useful
853 value (and is not displayed when that is the case). For the checksum to
854 output for a file, either the `--checksum` option must be in-effect or
855 the file must have been transferred without a salted checksum being used.
856 See the `--checksum-choice` option for a way to choose the algorithm.
857 - %f the filename (long form on sender; no trailing "/")
858 - %G the gid of the file (decimal) or "DEFAULT"
859 - %h the remote host name (only available for a daemon)
860 - %i an itemized list of what is being updated
861 - %l the length of the file in bytes
862 - %L the string "` -> SYMLINK`", "` => HARDLINK`", or "" (where `SYMLINK`
863 or `HARDLINK` is a filename)
865 - %M the last-modified time of the file
866 - %n the filename (short form; trailing "/" on dir)
867 - %o the operation, which is "send", "recv", or "del." (the latter includes
869 - %p the process ID of this rsync session
871 - %t the current date time
872 - %u the authenticated username or an empty string
873 - %U the uid of the file (decimal)
875 For a list of what the characters mean that are output by "%i", see the
876 `--itemize-changes` option in the rsync manpage.
878 Note that some of the logged output changes when talking with older rsync
879 versions. For instance, deleted files were only output as verbose messages
880 prior to rsync 2.6.4.
884 This parameter allows you to override the clients choice for I/O timeout
885 for this module. Using this parameter you can ensure that rsync won't wait
886 on a dead client forever. The timeout is specified in seconds. A value of
887 zero means no timeout and is the default. A good choice for anonymous rsync
888 daemons may be 600 (giving a 10 minute timeout).
892 This parameter allows you to specify a space-separated list of rsync
893 command-line options that will be refused by your rsync daemon. You may
894 specify the full option name, its one-letter abbreviation, or a wild-card
895 string that matches multiple options. Beginning in 3.2.0, you can also
896 negate a match term by starting it with a "!".
898 When an option is refused, the daemon prints an error message and exits.
900 For example, this would refuse `--checksum` (`-c`) and all the various
903 > refuse options = c delete
905 The reason the above refuses all delete options is that the options imply
906 `--delete`, and implied options are refused just like explicit options.
908 The use of a negated match allows you to fine-tune your refusals after a
909 wild-card, such as this:
911 > refuse options = delete-* !delete-during
913 Negated matching can also turn your list of refused options into a list of
914 accepted options. To do this, begin the list with a "`*`" (to refuse all
915 options) and then specify one or more negated matches to accept. For
918 > refuse options = * !a !v !compress*
920 Don't worry that the "`*`" will refuse certain vital options such as
921 `--dry-run`, `--server`, `--no-iconv`, `--seclude-args`, etc. These
922 important options are not matched by wild-card, so they must be overridden
923 by their exact name. For instance, if you're forcing iconv transfers you
924 could use something like this:
926 > refuse options = * no-iconv !a !v
928 As an additional aid (beginning in 3.2.0), refusing (or "`!refusing`") the
929 "a" or "archive" option also affects all the options that the `--archive`
930 option implies (`-rdlptgoD`), but only if the option is matched explicitly
931 (not using a wildcard). If you want to do something tricky, you can use
932 "`archive*`" to avoid this side-effect, but keep in mind that no normal
933 rsync client ever sends the actual archive option to the server.
935 As an additional safety feature, the refusal of "delete" also refuses
936 `remove-source-files` when the daemon is the sender; if you want the latter
937 without the former, instead refuse "`delete-*`" as that refuses all the
938 delete modes without affecting `--remove-source-files`. (Keep in mind that
939 the client's `--delete` option typically results in `--delete-during`.)
941 When un-refusing delete options, you should either specify "`!delete*`" (to
942 accept all delete options) or specify a limited set that includes "delete",
945 > refuse options = * !a !delete !delete-during
947 ... whereas this accepts any delete option except `--delete-after`:
949 > refuse options = * !a !delete* delete-after
951 A note on refusing "compress": it may be better to set the "[dont compress](#)"
952 daemon parameter to "`*`" and ensure that `RSYNC_COMPRESS_LIST=zlib` is set
953 in the environment of the daemon in order to disable compression silently
954 instead of returning an error that forces the client to remove the `-z`
957 If you are un-refusing the compress option, you may want to match
958 "`!compress*`" if you also want to allow the `--compress-level` option.
960 Note that the "copy-devices" & "write-devices" options are refused by
961 default, but they can be explicitly accepted with "`!copy-devices`" and/or
962 "`!write-devices`". The options "log-file" and "log-file-format" are
963 forcibly refused and cannot be accepted.
965 Here are all the options that are not matched by wild-cards:
967 - `--server`: Required for rsync to even work.
968 - `--rsh`, `-e`: Required to convey compatibility flags to the server.
969 - `--out-format`: This is required to convey output behavior to a remote
970 receiver. While rsync passes the older alias `--log-format` for
971 compatibility reasons, this options should not be confused with
973 - `--sender`: Use "[write only](#)" parameter instead of refusing this.
974 - `--dry-run`, `-n`: Who would want to disable this?
975 - `--seclude-args`, `-s`: Is the oldest arg-protection method.
976 - `--from0`, `-0`: Makes it easier to accept/refuse `--files-from` without
977 affecting this helpful modifier.
978 - `--iconv`: This is auto-disabled based on "[charset](#)" parameter.
979 - `--no-iconv`: Most transfers use this option.
980 - `--checksum-seed`: Is a fairly rare, safe option.
981 - `--write-devices`: Is non-wild but also auto-disabled.
985 **NOTE:** This parameter currently has no effect except in one instance: if
986 it is set to "`*`" then it minimizes or disables compression for all files
987 (for those that don't want to refuse the `--compress` option completely).
989 This parameter allows you to select filenames based on wildcard patterns
990 that should not be compressed when pulling files from the daemon (no
991 analogous parameter exists to govern the pushing of files to a daemon).
992 Compression can be expensive in terms of CPU usage, so it is usually good
993 to not try to compress files that won't compress well, such as already
996 The "dont compress" parameter takes a space-separated list of
997 case-insensitive wildcard patterns. Any source filename matching one of the
998 patterns will be compressed as little as possible during the transfer. If
999 the compression algorithm has an "off" level, then no compression occurs
1000 for those files. If an algorithms has the ability to change the level in
1001 mid-stream, it will be minimized to reduce the CPU usage as much as
1004 See the `--skip-compress` parameter in the **rsync**(1) manpage for the
1005 list of file suffixes that are skipped by default if this parameter is not
1008 0. `early exec`, `pre-xfer exec`, `post-xfer exec`
1010 You may specify a command to be run in the early stages of the connection,
1011 or right before and/or after the transfer. If the `early exec` or
1012 `pre-xfer exec` command returns an error code, the transfer is aborted
1013 before it begins. Any output from the `pre-xfer exec` command on stdout
1014 (up to several KB) will be displayed to the user when aborting, but is
1015 _not_ displayed if the script returns success. The other programs cannot
1016 send any text to the user. All output except for the `pre-xfer exec`
1017 stdout goes to the corresponding daemon's stdout/stderr, which is typically
1018 discarded. See the `--no-detatch` option for a way to see the daemon's
1019 output, which can assist with debugging.
1021 Note that the `early exec` command runs before any part of the transfer
1022 request is known except for the module name. This helper script can be
1023 used to setup a disk mount or decrypt some data into a module dir, but you
1024 may need to use `lock file` and `max connections` to avoid concurrency
1025 issues. If the client rsync specified the `--early-input=FILE` option, it
1026 can send up to about 5K of data to the stdin of the early script. The
1027 stdin will otherwise be empty.
1029 Note that the `post-xfer exec` command is still run even if one of the
1030 other scripts returns an error code. The `pre-xfer exec` command will _not_
1031 be run, however, if the `early exec` command fails.
1033 The following environment variables will be set, though some are specific
1034 to the pre-xfer or the post-xfer environment:
1036 - `RSYNC_MODULE_NAME`: The name of the module being accessed.
1037 - `RSYNC_MODULE_PATH`: The path configured for the module.
1038 - `RSYNC_HOST_ADDR`: The accessing host's IP address.
1039 - `RSYNC_HOST_NAME`: The accessing host's name.
1040 - `RSYNC_USER_NAME`: The accessing user's name (empty if no user).
1041 - `RSYNC_PID`: A unique number for this transfer.
1042 - `RSYNC_REQUEST`: (pre-xfer only) The module/path info specified by the
1043 user. Note that the user can specify multiple source files, so the
1044 request can be something like "mod/path1 mod/path2", etc.
1045 - `RSYNC_ARG#`: (pre-xfer only) The pre-request arguments are set in these
1046 numbered values. RSYNC_ARG0 is always "rsyncd", followed by the options
1047 that were used in RSYNC_ARG1, and so on. There will be a value of "."
1048 indicating that the options are done and the path args are beginning --
1049 these contain similar information to RSYNC_REQUEST, but with values
1050 separated and the module name stripped off.
1051 - `RSYNC_EXIT_STATUS`: (post-xfer only) the server side's exit value. This
1052 will be 0 for a successful run, a positive value for an error that the
1053 server generated, or a -1 if rsync failed to exit properly. Note that an
1054 error that occurs on the client side does not currently get sent to the
1055 server side, so this is not the final exit status for the whole transfer.
1056 - `RSYNC_RAW_STATUS`: (post-xfer only) the raw exit value from
1059 Even though the commands can be associated with a particular module, they
1060 are run using the permissions of the user that started the daemon (not the
1061 module's uid/gid setting) without any chroot restrictions.
1063 These settings honor 2 environment variables: use RSYNC_SHELL to set a
1064 shell to use when running the command (which otherwise uses your
1065 **system()** call's default shell), and use RSYNC_NO_XFER_EXEC to disable
1066 both options completely.
1068 ## CONFIG DIRECTIVES
1070 There are currently two config directives available that allow a config file to
1071 incorporate the contents of other files: `&include` and `&merge`. Both allow
1072 a reference to either a file or a directory. They differ in how segregated the
1073 file's contents are considered to be.
1075 The `&include` directive treats each file as more distinct, with each one
1076 inheriting the defaults of the parent file, starting the parameter parsing as
1077 globals/defaults, and leaving the defaults unchanged for the parsing of the
1078 rest of the parent file.
1080 The `&merge` directive, on the other hand, treats the file's contents as if it
1081 were simply inserted in place of the directive, and thus it can set parameters
1082 in a module started in another file, can affect the defaults for other files,
1085 When an `&include` or `&merge` directive refers to a directory, it will read in
1086 all the `*.conf` or `*.inc` files (respectively) that are contained inside that
1087 directory (without any recursive scanning), with the files sorted into alpha
1088 order. So, if you have a directory named "rsyncd.d" with the files "foo.conf",
1089 "bar.conf", and "baz.conf" inside it, this directive:
1091 > &include /path/rsyncd.d
1093 would be the same as this set of directives:
1095 > &include /path/rsyncd.d/bar.conf
1096 > &include /path/rsyncd.d/baz.conf
1097 > &include /path/rsyncd.d/foo.conf
1099 except that it adjusts as files are added and removed from the directory.
1101 The advantage of the `&include` directive is that you can define one or more
1102 modules in a separate file without worrying about unintended side-effects
1103 between the self-contained module files.
1105 The advantage of the `&merge` directive is that you can load config snippets
1106 that can be included into multiple module definitions, and you can also set
1107 global values that will affect connections (such as `motd file`), or globals
1108 that will affect other include files.
1110 For example, this is a useful /etc/rsyncd.conf file:
1113 > log file = /var/log/rsync.log
1114 > pid file = /var/lock/rsync.lock
1116 > &merge /etc/rsyncd.d
1117 > &include /etc/rsyncd.d
1119 This would merge any `/etc/rsyncd.d/*.inc` files (for global values that should
1120 stay in effect), and then include any `/etc/rsyncd.d/*.conf` files (defining
1121 modules without any global-value cross-talk).
1123 ## AUTHENTICATION STRENGTH
1125 The authentication protocol used in rsync is a 128 bit MD4 based challenge
1126 response system. This is fairly weak protection, though (with at least one
1127 brute-force hash-finding algorithm publicly available), so if you want really
1128 top-quality security, then I recommend that you run rsync over ssh. (Yes, a
1129 future version of rsync will switch over to a stronger hashing method.)
1131 Also note that the rsync daemon protocol does not currently provide any
1132 encryption of the data that is transferred over the connection. Only
1133 authentication is provided. Use ssh as the transport if you want encryption.
1135 You can also make use of SSL/TLS encryption if you put rsync behind an
1138 ## SSL/TLS Daemon Setup
1140 When setting up an rsync daemon for access via SSL/TLS, you will need to
1141 configure a TCP proxy (such as haproxy or nginx) as the front-end that handles
1144 - You should limit the access to the backend-rsyncd port to only allow the
1145 proxy to connect. If it is on the same host as the proxy, then configuring
1146 it to only listen on localhost is a good idea.
1147 - You should consider turning on the `proxy protocol` rsync-daemon parameter if
1148 your proxy supports sending that information. The examples below assume that
1151 An example haproxy setup is as follows:
1154 > frontend fe_rsync-ssl
1155 > bind :::874 ssl crt /etc/letsencrypt/example.com/combined.pem
1157 > use_backend be_rsync
1161 > server local-rsync 127.0.0.1:873 check send-proxy
1164 An example nginx proxy setup is as follows:
1170 > listen [::]:874 ssl;
1172 > ssl_certificate /etc/letsencrypt/example.com/fullchain.pem;
1173 > ssl_certificate_key /etc/letsencrypt/example.com/privkey.pem;
1175 > proxy_pass localhost:873;
1176 > proxy_protocol on; # Requires rsyncd.conf "proxy protocol = true"
1178 > proxy_connect_timeout 5s;
1183 ## DAEMON CONFIG EXAMPLES
1185 A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
1186 `/home/ftp` would be:
1191 > comment = ftp export area
1194 A more sophisticated example would be:
1200 > max connections = 4
1201 > syslog facility = local5
1202 > pid file = /var/run/rsyncd.pid
1205 > path = /var/ftp/./pub
1206 > comment = whole ftp area (approx 6.1 GB)
1209 > path = /var/ftp/./pub/samba
1210 > comment = Samba ftp area (approx 300 MB)
1213 > path = /var/ftp/./pub/rsync
1214 > comment = rsync ftp area (approx 6 MB)
1217 > path = /public_html/samba
1218 > comment = Samba WWW pages (approx 240 MB)
1222 > comment = CVS repository (requires authentication)
1223 > auth users = tridge, susan
1224 > secrets file = /etc/rsyncd.secrets
1227 The /etc/rsyncd.secrets file would look something like this:
1234 /etc/rsyncd.conf or rsyncd.conf
1238 [**rsync**(1)](rsync.1), [**rsync-ssl**(1)](rsync-ssl.1)
1242 Please report bugs! The rsync bug tracking system is online at
1243 <https://rsync.samba.org/>.
1247 This manpage is current for version @VERSION@ of rsync.
1251 Rsync is distributed under the GNU General Public License. See the file
1252 [COPYING](COPYING) for details.
1254 An rsync web site is available at <https://rsync.samba.org/> and its github
1255 project is <https://github.com/WayneD/rsync>.
1259 Thanks to Warren Stanley for his original idea and patch for the rsync daemon.
1260 Thanks to Karsten Thygesen for his many suggestions and documentation!
1264 Rsync was originally written by Andrew Tridgell and Paul Mackerras. Many
1265 people have later contributed to it. It is currently maintained by Wayne
1268 Mailing lists for support and development are available at
1269 <https://lists.samba.org/>.