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