Added "listen backlog" daemon config paramater.
[rsync.git] / rsyncd.conf.yo
1 mailto(rsync-bugs@samba.org)
2 manpage(rsyncd.conf)(5)(29 Jun 2008)()()
3 manpagename(rsyncd.conf)(configuration file for rsync in daemon mode)
4 manpagesynopsis()
5
6 rsyncd.conf
7
8 manpagedescription()
9
10 The rsyncd.conf file is the runtime configuration file for rsync when
11 run as an rsync daemon.
12
13 The rsyncd.conf file controls authentication, access, logging and
14 available modules.
15
16 manpagesection(FILE FORMAT)
17
18 The file consists of modules and parameters. A module begins with the
19 name of the module in square brackets and continues until the next
20 module begins. Modules contain parameters of the form "name = value".
21
22 The file is line-based -- that is, each newline-terminated line represents
23 either a comment, a module name or a parameter.
24
25 Only the first equals sign in a parameter is significant. Whitespace before
26 or after the first equals sign is discarded. Leading, trailing and internal
27 whitespace in module and parameter names is irrelevant. Leading and
28 trailing whitespace in a parameter value is discarded. Internal whitespace
29 within a parameter value is retained verbatim.
30
31 Any line beginning with a hash (#) is ignored, as are lines containing
32 only whitespace.
33
34 Any line ending in a \ is "continued" on the next line in the
35 customary UNIX fashion.
36
37 The values following the equals sign in parameters are all either a string
38 (no quotes needed) or a boolean, which may be given as yes/no, 0/1 or
39 true/false. Case is not significant in boolean values, but is preserved
40 in string values.
41
42 manpagesection(LAUNCHING THE RSYNC DAEMON)
43
44 The rsync daemon is launched by specifying the bf(--daemon) option to
45 rsync.
46
47 The daemon must run with root privileges if you wish to use chroot, to
48 bind to a port numbered under 1024 (as is the default 873), or to set
49 file ownership.  Otherwise, it must just have permission to read and
50 write the appropriate data, log, and lock files.
51
52 You can launch it either via inetd, as a stand-alone daemon, or from
53 an rsync client via a remote shell.  If run as a stand-alone daemon then
54 just run the command "bf(rsync --daemon)" from a suitable startup script.
55
56 When run via inetd you should add a line like this to /etc/services:
57
58 verb(  rsync           873/tcp)
59
60 and a single line something like this to /etc/inetd.conf:
61
62 verb(  rsync   stream  tcp     nowait  root   /usr/bin/rsync rsyncd --daemon)
63
64 Replace "/usr/bin/rsync" with the path to where you have rsync installed on
65 your system.  You will then need to send inetd a HUP signal to tell it to
66 reread its config file.
67
68 Note that you should bf(not) send the rsync daemon a HUP signal to force
69 it to reread the tt(rsyncd.conf) file. The file is re-read on each client
70 connection.
71
72 manpagesection(GLOBAL PARAMETERS)
73
74 The first parameters in the file (before a [module] header) are the
75 global parameters.
76
77 You may also include any module parameters in the global part of the
78 config file in which case the supplied value will override the
79 default for that parameter.
80
81 You may use references to environment variables in the values of parameters.
82 String parameters will have %VAR% references expanded as late as possible (when
83 the string is used in the program), allowing for the use of variables that
84 rsync sets at connection time, such as RSYNC_USER_NAME.  Non-string parameters
85 (such as true/false settings) are expanded when read from the config file.  If
86 a variable does not exist in the environment, or if a sequence of characters is
87 not a valid reference (such as an un-paired percent sign), the raw characters
88 are passed through unchanged.  This helps with backward compatibility and
89 safety (e.g. expanding a non-existent %VAR% to an empty string in a path could
90 result in a very unsafe path).  The safest way to insert a literal % into a
91 value is to use %%.
92
93 startdit()
94 dit(bf(motd file)) This parameter allows you to specify a
95 "message of the day" to display to clients on each connect. This
96 usually contains site information and any legal notices. The default
97 is no motd file.
98 This can be overridden by the bf(--dparam=motdfile=FILE)
99 command-line option when starting the daemon.
100
101 dit(bf(pid file)) This parameter tells the rsync daemon to write
102 its process ID to that file.  If the file already exists, the rsync
103 daemon will abort rather than overwrite the file.
104 This can be overridden by the bf(--dparam=pidfile=FILE)
105 command-line option when starting the daemon.
106
107 dit(bf(port)) You can override the default port the daemon will listen on
108 by specifying this value (defaults to 873).  This is ignored if the daemon
109 is being run by inetd, and is superseded by the bf(--port) command-line option.
110
111 dit(bf(address)) You can override the default IP address the daemon
112 will listen on by specifying this value.  This is ignored if the daemon is
113 being run by inetd, and is superseded by the bf(--address) command-line option.
114
115 dit(bf(socket options)) This parameter can provide endless fun for people
116 who like to tune their systems to the utmost degree. You can set all
117 sorts of socket options which may make transfers faster (or
118 slower!). Read the man page for the code(setsockopt()) system call for
119 details on some of the options you may be able to set. By default no
120 special socket options are set.  These settings can also be specified
121 via the bf(--sockopts) command-line option.
122
123 dit(bf(listen backlog)) You can override the default backlog value when the
124 daemon listens for connections.  It defaults to 5.
125
126 enddit()
127
128 manpagesection(MODULE PARAMETERS)
129
130 After the global parameters you should define a number of modules, each
131 module exports a directory tree as a symbolic name. Modules are
132 exported by specifying a module name in square brackets [module]
133 followed by the parameters for that module.
134 The module name cannot contain a slash or a closing square bracket.  If the
135 name contains whitespace, each internal sequence of whitespace will be
136 changed into a single space, while leading or trailing whitespace will be
137 discarded.
138
139 As with GLOBAL PARAMETERS, you may use references to environment variables in
140 the values of parameters.  See the GLOBAL PARAMETERS section for more details.
141
142 startdit()
143
144 dit(bf(comment)) This parameter specifies a description string
145 that is displayed next to the module name when clients obtain a list
146 of available modules. The default is no comment.
147
148 dit(bf(path)) This parameter specifies the directory in the daemon's
149 filesystem to make available in this module.  You must specify this parameter
150 for each module in tt(rsyncd.conf).
151
152 You may base the path's value off of an environment variable by surrounding
153 the variable name with percent signs.  You can even reference a variable
154 that is set by rsync when the user connects.
155 For example, this would use the authorizing user's name in the path:
156
157 verb(    path = /home/%RSYNC_USER_NAME% )
158
159 dit(bf(use chroot)) If "use chroot" is true, the rsync daemon will chroot
160 to the "path" before starting the file transfer with the client.  This has
161 the advantage of extra protection against possible implementation security
162 holes, but it has the disadvantages of requiring super-user privileges,
163 of not being able to follow symbolic links that are either absolute or outside
164 of the new root path, and of complicating the preservation of users and groups
165 by name (see below).
166
167 As an additional safety feature, you can specify a dot-dir in the module's
168 "path" to indicate the point where the chroot should occur.  This allows rsync
169 to run in a chroot with a non-"/" path for the top of the transfer hierarchy.
170 Doing this guards against unintended library loading (since those absolute
171 paths will not be inside the transfer hierarchy unless you have used an unwise
172 pathname), and lets you setup libraries for the chroot that are outside of the
173 transfer.  For example, specifying "/var/rsync/./module1" will chroot to the
174 "/var/rsync" directory and set the inside-chroot path to "/module1".  If you
175 had omitted the dot-dir, the chroot would have used the whole path, and the
176 inside-chroot path would have been "/".
177
178 When "use chroot" is false or the inside-chroot path is not "/", rsync will:
179 (1) munge symlinks by
180 default for security reasons (see "munge symlinks" for a way to turn this
181 off, but only if you trust your users), (2) substitute leading slashes in
182 absolute paths with the module's path (so that options such as
183 bf(--backup-dir), bf(--compare-dest), etc. interpret an absolute path as
184 rooted in the module's "path" dir), and (3) trim ".." path elements from
185 args if rsync believes they would escape the module hierarchy.
186 The default for "use chroot" is true, and is the safer choice (especially
187 if the module is not read-only).
188
189 When this parameter is enabled, rsync will not attempt to map users and groups
190 by name (by default), but instead copy IDs as though bf(--numeric-ids) had
191 been specified.  In order to enable name-mapping, rsync needs to be able to
192 use the standard library functions for looking up names and IDs (i.e.
193 code(getpwuid()), code(getgrgid()), code(getpwname()), and code(getgrnam())).
194 This means the rsync
195 process in the chroot hierarchy will need to have access to the resources
196 used by these library functions (traditionally /etc/passwd and
197 /etc/group, but perhaps additional dynamic libraries as well).
198
199 If you copy the necessary resources into the module's chroot area, you
200 should protect them through your OS's normal user/group or ACL settings (to
201 prevent the rsync module's user from being able to change them), and then
202 hide them from the user's view via "exclude" (see how in the discussion of
203 that parameter).  At that point it will be safe to enable the mapping of users
204 and groups by name using the "numeric ids" daemon parameter (see below).
205
206 Note also that you are free to setup custom user/group information in the
207 chroot area that is different from your normal system.  For example, you
208 could abbreviate the list of users and groups.
209
210 dit(bf(numeric ids)) Enabling this parameter disables the mapping
211 of users and groups by name for the current daemon module.  This prevents
212 the daemon from trying to load any user/group-related files or libraries.
213 This enabling makes the transfer behave as if the client had passed
214 the bf(--numeric-ids) command-line option.  By default, this parameter is
215 enabled for chroot modules and disabled for non-chroot modules.
216
217 A chroot-enabled module should not have this parameter enabled unless you've
218 taken steps to ensure that the module has the necessary resources it needs
219 to translate names, and that it is not possible for a user to change those
220 resources.
221
222 dit(bf(munge symlinks)) This parameter tells rsync to modify
223 all symlinks in the same way as the (non-daemon-affecting)
224 bf(--munge-links) command-line option (using a method described below).
225 This should help protect your files from user trickery when
226 your daemon module is writable.  The default is disabled when "use chroot"
227 is on and the inside-chroot path is "/", otherwise it is enabled.
228
229 If you disable this parameter on a daemon that is not read-only, there
230 are tricks that a user can play with uploaded symlinks to access
231 daemon-excluded items (if your module has any), and, if "use chroot"
232 is off, rsync can even be tricked into showing or changing data that
233 is outside the module's path (as access-permissions allow).
234
235 The way rsync disables the use of symlinks is to prefix each one with
236 the string "/rsyncd-munged/".  This prevents the links from being used
237 as long as that directory does not exist.  When this parameter is enabled,
238 rsync will refuse to run if that path is a directory or a symlink to
239 a directory.  When using the "munge symlinks" parameter in a chroot area
240 that has an inside-chroot path of "/", you should add "/rsyncd-munged/"
241 to the exclude setting for the module so that
242 a user can't try to create it.
243
244 Note:  rsync makes no attempt to verify that any pre-existing symlinks in
245 the module's hierarchy are as safe as you want them to be (unless, of
246 course, it just copied in the whole hierarchy).  If you setup an rsync
247 daemon on a new area or locally add symlinks, you can manually protect your
248 symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
249 every symlink's value.  There is a perl script in the support directory
250 of the source code named "munge-symlinks" that can be used to add or remove
251 this prefix from your symlinks.
252
253 When this parameter is disabled on a writable module and "use chroot" is off
254 (or the inside-chroot path is not "/"),
255 incoming symlinks will be modified to drop a leading slash and to remove ".."
256 path elements that rsync believes will allow a symlink to escape the module's
257 hierarchy.  There are tricky ways to work around this, though, so you had
258 better trust your users if you choose this combination of parameters.
259
260 dit(bf(charset)) This specifies the name of the character set in which the
261 module's filenames are stored.  If the client uses an bf(--iconv) option,
262 the daemon will use the value of the "charset" parameter regardless of the
263 character set the client actually passed.  This allows the daemon to
264 support charset conversion in a chroot module without extra files in the
265 chroot area, and also ensures that name-translation is done in a consistent
266 manner.  If the "charset" parameter is not set, the bf(--iconv) option is
267 refused, just as if "iconv" had been specified via "refuse options".
268
269 If you wish to force users to always use bf(--iconv) for a particular
270 module, add "no-iconv" to the "refuse options" parameter.  Keep in mind
271 that this will restrict access to your module to very new rsync clients.
272
273 dit(bf(max connections)) This parameter allows you to
274 specify the maximum number of simultaneous connections you will allow.
275 Any clients connecting when the maximum has been reached will receive a
276 message telling them to try later.  The default is 0, which means no limit.
277 A negative value disables the module.
278 See also the "lock file" parameter.
279
280 dit(bf(log file)) When the "log file" parameter is set to a non-empty
281 string, the rsync daemon will log messages to the indicated file rather
282 than using syslog. This is particularly useful on systems (such as AIX)
283 where code(syslog()) doesn't work for chrooted programs.  The file is
284 opened before code(chroot()) is called, allowing it to be placed outside
285 the transfer.  If this value is set on a per-module basis instead of
286 globally, the global log will still contain any authorization failures
287 or config-file error messages.
288
289 If the daemon fails to open the specified file, it will fall back to
290 using syslog and output an error about the failure.  (Note that the
291 failure to open the specified log file used to be a fatal error.)
292
293 This setting can be overridden by using the bf(--log-file=FILE) or
294 bf(--dparam=logfile=FILE) command-line options.  The former overrides
295 all the log-file parameters of the daemon and all module settings.
296 The latter sets the daemon's log file and the default for all the
297 modules, which still allows modules to override the default setting.
298
299 dit(bf(syslog facility)) This parameter allows you to
300 specify the syslog facility name to use when logging messages from the
301 rsync daemon. You may use any standard syslog facility name which is
302 defined on your system. Common names are auth, authpriv, cron, daemon,
303 ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0,
304 local1, local2, local3, local4, local5, local6 and local7. The default
305 is daemon.  This setting has no effect if the "log file" setting is a
306 non-empty string (either set in the per-modules settings, or inherited
307 from the global settings).
308
309 dit(bf(max verbosity)) This parameter allows you to control
310 the maximum amount of verbose information that you'll allow the daemon to
311 generate (since the information goes into the log file). The default is 1,
312 which allows the client to request one level of verbosity.
313
314 dit(bf(lock file)) This parameter specifies the file to use to
315 support the "max connections" parameter. The rsync daemon uses record
316 locking on this file to ensure that the max connections limit is not
317 exceeded for the modules sharing the lock file.
318 The default is tt(/var/run/rsyncd.lock).
319
320 dit(bf(read only)) This parameter determines whether clients
321 will be able to upload files or not. If "read only" is true then any
322 attempted uploads will fail. If "read only" is false then uploads will
323 be possible if file permissions on the daemon side allow them. The default
324 is for all modules to be read only.
325
326 Note that "auth users" can override this setting on a per-user basis.
327
328 dit(bf(write only)) This parameter determines whether clients
329 will be able to download files or not. If "write only" is true then any
330 attempted downloads will fail. If "write only" is false then downloads
331 will be possible if file permissions on the daemon side allow them.  The
332 default is for this parameter to be disabled.
333
334 dit(bf(list)) This parameter determines whether this module is
335 listed when the client asks for a listing of available modules.  In addition,
336 if this is false, the daemon will pretend the module does not exist
337 when a client denied by "hosts allow" or "hosts deny" attempts to access it.
338 Realize that if "reverse lookup" is disabled globally but enabled for the
339 module, the resulting reverse lookup to a potentially client-controlled DNS
340 server may still reveal to the client that it hit an existing module.
341 The default is for modules to be listable.
342
343 dit(bf(uid)) This parameter specifies the user name or user ID that
344 file transfers to and from that module should take place as when the daemon
345 was run as root. In combination with the "gid" parameter this determines what
346 file permissions are available. The default when run by a super-user is to
347 switch to the system's "nobody" user.  The default for a non-super-user is to
348 not try to change the user.  See also the "gid" parameter.
349
350 The RSYNC_USER_NAME environment variable may be used to request that rsync run
351 as the authorizing user.  For example, if you want a rsync to run as the same
352 user that was received for the rsync authentication, this setup is useful:
353
354 verb(    uid = %RSYNC_USER_NAME%
355     gid = * )
356
357 dit(bf(gid)) This parameter specifies one or more group names/IDs that will be
358 used when accessing the module.  The first one will be the default group, and
359 any extra ones be set as supplemental groups.  You may also specify a "*" as
360 the first gid in the list, which will be replaced by all the normal groups for
361 the transfer's user (see "uid").  The default when run by a super-user is to
362 switch to your OS's "nobody" (or perhaps "nogroup") group with no other
363 supplementary groups.  The default for a non-super-user is to not change any
364 group attributes (and indeed, your OS may not allow a non-super-user to try to
365 change their group settings).
366
367 dit(bf(fake super)) Setting "fake super = yes" for a module causes the
368 daemon side to behave as if the bf(--fake-super) command-line option had
369 been specified.  This allows the full attributes of a file to be stored
370 without having to have the daemon actually running as root.
371
372 dit(bf(filter)) The daemon has its own filter chain that determines what files
373 it will let the client access.  This chain is not sent to the client and is
374 independent of any filters the client may have specified.  Files excluded by
375 the daemon filter chain (bf(daemon-excluded) files) are treated as non-existent
376 if the client tries to pull them, are skipped with an error message if the
377 client tries to push them (triggering exit code 23), and are never deleted from
378 the module.  You can use daemon filters to prevent clients from downloading or
379 tampering with private administrative files, such as files you may add to
380 support uid/gid name translations.
381
382 The daemon filter chain is built from the "filter", "include from", "include",
383 "exclude from", and "exclude" parameters, in that order of priority.  Anchored
384 patterns are anchored at the root of the module.  To prevent access to an
385 entire subtree, for example, "/secret", you em(must) exclude everything in the
386 subtree; the easiest way to do this is with a triple-star pattern like
387 "/secret/***".
388
389 The "filter" parameter takes a space-separated list of daemon filter rules,
390 though it is smart enough to know not to split a token at an internal space in
391 a rule (e.g. "- /foo  - /bar" is parsed as two rules).  You may specify one or
392 more merge-file rules using the normal syntax.  Only one "filter" parameter can
393 apply to a given module in the config file, so put all the rules you want in a
394 single parameter.  Note that per-directory merge-file rules do not provide as
395 much protection as global rules, but they can be used to make bf(--delete) work
396 better during a client download operation if the per-dir merge files are
397 included in the transfer and the client requests that they be used.
398
399 dit(bf(exclude)) This parameter takes a space-separated list of daemon
400 exclude patterns.  As with the client bf(--exclude) option, patterns can be
401 qualified with "- " or "+ " to explicitly indicate exclude/include.  Only one
402 "exclude" parameter can apply to a given module.  See the "filter" parameter
403 for a description of how excluded files affect the daemon.
404
405 dit(bf(include)) Use an "include" to override the effects of the "exclude"
406 parameter.  Only one "include" parameter can apply to a given module.  See the
407 "filter" parameter for a description of how excluded files affect the daemon.
408
409 dit(bf(exclude from)) This parameter specifies the name of a file
410 on the daemon that contains daemon exclude patterns, one per line.  Only one
411 "exclude from" parameter can apply to a given module; if you have multiple
412 exclude-from files, you can specify them as a merge file in the "filter"
413 parameter.  See the "filter" parameter for a description of how excluded files
414 affect the daemon.
415
416 dit(bf(include from)) Analogue of "exclude from" for a file of daemon include
417 patterns.  Only one "include from" parameter can apply to a given module.  See
418 the "filter" parameter for a description of how excluded files affect the
419 daemon.
420
421 dit(bf(incoming chmod)) This parameter allows you to specify a set of
422 comma-separated chmod strings that will affect the permissions of all
423 incoming files (files that are being received by the daemon).  These
424 changes happen after all other permission calculations, and this will
425 even override destination-default and/or existing permissions when the
426 client does not specify bf(--perms).
427 See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
428 manpage for information on the format of this string.
429
430 dit(bf(outgoing chmod)) This parameter allows you to specify a set of
431 comma-separated chmod strings that will affect the permissions of all
432 outgoing files (files that are being sent out from the daemon).  These
433 changes happen first, making the sent permissions appear to be different
434 than those stored in the filesystem itself.  For instance, you could
435 disable group write permissions on the server while having it appear to
436 be on to the clients.
437 See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
438 manpage for information on the format of this string.
439
440 dit(bf(auth users)) This parameter specifies a comma and/or space-separated
441 list of authorization rules.  In its simplest form, you list the usernames
442 that will be allowed to connect to
443 this module. The usernames do not need to exist on the local
444 system. The rules may contain shell wildcard characters that will be matched
445 against the username provided by the client for authentication. If
446 "auth users" is set then the client will be challenged to supply a
447 username and password to connect to the module. A challenge response
448 authentication protocol is used for this exchange. The plain text
449 usernames and passwords are stored in the file specified by the
450 "secrets file" parameter. The default is for all users to be able to
451 connect without a password (this is called "anonymous rsync").
452
453 In addition to username matching, you can specify groupname matching via a '@'
454 prefix.  When using groupname matching, the authenticating username must be a
455 real user on the system, or it will be assumed to be a member of no groups.
456 For example, specifying "@rsync" will match the authenticating user if the
457 named user is a member of the rsync group.
458
459 Finally, options may be specified after a colon (:).  The options allow you to
460 "deny" a user or a group, set the access to "ro" (read-only), or set the access
461 to "rw" (read/write).  Setting an auth-rule-specific ro/rw setting overrides
462 the module's "read only" setting.
463
464 Be sure to put the rules in the order you want them to be matched, because the
465 checking stops at the first matching user or group, and that is the only auth
466 that is checked.  For example:
467
468 verb(  auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam )
469
470 In the above rule, user joe will be denied access no matter what.  Any user
471 that is in the group "guest" is also denied access.  The user "admin" gets
472 access in read/write mode, but only if the admin user is not in group "guest"
473 (because the admin user-matching rule would never be reached if the user is in
474 group "guest").  Any other user who is in group "rsync" will get read-only
475 access.  Finally, users susan, joe, and sam get the ro/rw setting of the
476 module, but only if the user didn't match an earlier group-matching rule.
477
478 See the description of the secrets file for how you can have per-user passwords
479 as well as per-group passwords.  It also explains how a user can authenticate
480 using their user password or (when applicable) a group password, depending on
481 what rule is being authenticated.
482
483 See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE
484 SHELL CONNECTION" in bf(rsync)(1) for information on how handle an
485 rsyncd.conf-level username that differs from the remote-shell-level
486 username when using a remote shell to connect to an rsync daemon.
487
488 dit(bf(secrets file)) This parameter specifies the name of a file that contains
489 the username:password and/or @groupname:password pairs used for authenticating
490 this module. This file is only consulted if the "auth users" parameter is
491 specified.  The file is line-based and contains one name:password pair per
492 line.  Any line has a hash (#) as the very first character on the line is
493 considered a comment and is skipped.  The passwords can contain any characters
494 but be warned that many operating systems limit the length of passwords that
495 can be typed at the client end, so you may find that passwords longer than 8
496 characters don't work.
497
498 The use of group-specific lines are only relevant when the module is being
499 authorized using a matching "@groupname" rule.  When that happens, the user
500 can be authorized via either their "username:password" line or the
501 "@groupname:password" line for the group that triggered the authentication.
502
503 It is up to you what kind of password entries you want to include, either
504 users, groups, or both.  The use of group rules in "auth users" does not
505 require that you specify a group password if you do not want to use shared
506 passwords.
507
508 There is no default for the "secrets file" parameter, you must choose a name
509 (such as tt(/etc/rsyncd.secrets)).  The file must normally not be readable
510 by "other"; see "strict modes".  If the file is not found or is rejected, no
511 logins for a "user auth" module will be possible.
512
513 dit(bf(strict modes)) This parameter determines whether or not
514 the permissions on the secrets file will be checked.  If "strict modes" is
515 true, then the secrets file must not be readable by any user ID other
516 than the one that the rsync daemon is running under.  If "strict modes" is
517 false, the check is not performed.  The default is true.  This parameter
518 was added to accommodate rsync running on the Windows operating system.
519
520 dit(bf(hosts allow)) This parameter allows you to specify a
521 list of patterns that are matched against a connecting clients
522 hostname and IP address. If none of the patterns match then the
523 connection is rejected.
524
525 Each pattern can be in one of five forms:
526
527 quote(itemization(
528   it() a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address
529   of the form a:b:c::d:e:f. In this case the incoming machine's IP address
530   must match exactly.
531   it() an address/mask in the form ipaddr/n where ipaddr is the IP address
532   and n is the number of one bits in the netmask.  All IP addresses which
533   match the masked IP address will be allowed in.
534   it() an address/mask in the form ipaddr/maskaddr where ipaddr is the
535   IP address and maskaddr is the netmask in dotted decimal notation for IPv4,
536   or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
537   addresses which match the masked IP address will be allowed in.
538   it() a hostname pattern using wildcards. If the hostname of the connecting IP
539   (as determined by a reverse lookup) matches the wildcarded name (using the
540   same rules as normal unix filename matching), the client is allowed in.  This
541   only works if "reverse lookup" is enabled (the default).
542   it() a hostname. A plain hostname is matched against the reverse DNS of the
543   connecting IP (if "reverse lookup" is enabled), and/or the IP of the given
544   hostname is matched against the connecting IP (if "forward lookup" is
545   enabled, as it is by default).  Any match will be allowed in.
546 ))
547
548 Note IPv6 link-local addresses can have a scope in the address specification:
549
550 quote(
551 tt(    fe80::1%link1)nl()
552 tt(    fe80::%link1/64)nl()
553 tt(    fe80::%link1/ffff:ffff:ffff:ffff::)nl()
554 )
555
556 You can also combine "hosts allow" with a separate "hosts deny"
557 parameter. If both parameters are specified then the "hosts allow" parameter is
558 checked first and a match results in the client being able to
559 connect. The "hosts deny" parameter is then checked and a match means
560 that the host is rejected. If the host does not match either the
561 "hosts allow" or the "hosts deny" patterns then it is allowed to
562 connect.
563
564 The default is no "hosts allow" parameter, which means all hosts can connect.
565
566 dit(bf(hosts deny)) This parameter allows you to specify a
567 list of patterns that are matched against a connecting clients
568 hostname and IP address. If the pattern matches then the connection is
569 rejected. See the "hosts allow" parameter for more information.
570
571 The default is no "hosts deny" parameter, which means all hosts can connect.
572
573 dit(bf(reverse lookup)) Controls whether the daemon performs a reverse lookup
574 on the client's IP address to determine its hostname, which is used for
575 "hosts allow"/"hosts deny" checks and the "%h" log escape.  This is enabled by
576 default, but you may wish to disable it to save time if you know the lookup will
577 not return a useful result, in which case the daemon will use the name
578 "UNDETERMINED" instead.
579
580 If this parameter is enabled globally (even by default), rsync performs the
581 lookup as soon as a client connects, so disabling it for a module will not
582 avoid the lookup.  Thus, you probably want to disable it globally and then
583 enable it for modules that need the information.
584
585 dit(bf(forward lookup)) Controls whether the daemon performs a forward lookup
586 on any hostname specified in an hosts allow/deny setting.  By default this is
587 enabled, allowing the use of an explicit hostname that would not be returned
588 by reverse DNS of the connecting IP.
589
590 dit(bf(ignore errors)) This parameter tells rsyncd to
591 ignore I/O errors on the daemon when deciding whether to run the delete
592 phase of the transfer. Normally rsync skips the bf(--delete) step if any
593 I/O errors have occurred in order to prevent disastrous deletion due
594 to a temporary resource shortage or other I/O error. In some cases this
595 test is counter productive so you can use this parameter to turn off this
596 behavior.
597
598 dit(bf(ignore nonreadable)) This tells the rsync daemon to completely
599 ignore files that are not readable by the user. This is useful for
600 public archives that may have some non-readable files among the
601 directories, and the sysadmin doesn't want those files to be seen at all.
602
603 dit(bf(transfer logging)) This parameter enables per-file
604 logging of downloads and uploads in a format somewhat similar to that
605 used by ftp daemons.  The daemon always logs the transfer at the end, so
606 if a transfer is aborted, no mention will be made in the log file.
607
608 If you want to customize the log lines, see the "log format" parameter.
609
610 dit(bf(log format)) This parameter allows you to specify the
611 format used for logging file transfers when transfer logging is enabled.
612 The format is a text string containing embedded single-character escape
613 sequences prefixed with a percent (%) character.  An optional numeric
614 field width may also be specified between the percent and the escape
615 letter (e.g. "bf(%-50n %8l %07p)").
616 In addition, one or more apostrophes may be specified prior to a numerical
617 escape to indicate that the numerical value should be made more human-readable.
618 The 3 supported levels are the same as for the bf(--human-readable)
619 command-line option, though the default is for human-readability to be off.
620 Each added apostrophe increases the level (e.g. "bf(%''l %'b %f)").
621
622 The default log format is "%o %h [%a] %m (%u) %f %l", and a "%t [%p] "
623 is always prefixed when using the "log file" parameter.
624 (A perl script that will summarize this default log format is included
625 in the rsync source code distribution in the "support" subdirectory:
626 rsyncstats.)
627
628 The single-character escapes that are understood are as follows:
629
630 quote(itemization(
631   it() %a the remote IP address
632   it() %b the number of bytes actually transferred
633   it() %B the permission bits of the file (e.g. rwxrwxrwt)
634   it() %c the total size of the block checksums received for the basis file (only when sending)
635   it() %C the full-file MD5 checksum if bf(--checksum) is enabled or a file was transferred (only for protocol 30 or above).
636   it() %f the filename (long form on sender; no trailing "/")
637   it() %G the gid of the file (decimal) or "DEFAULT"
638   it() %h the remote host name
639   it() %i an itemized list of what is being updated
640   it() %l the length of the file in bytes
641   it() %L the string " -> SYMLINK", " => HARDLINK", or "" (where bf(SYMLINK) or bf(HARDLINK) is a filename)
642   it() %m the module name
643   it() %M the last-modified time of the file
644   it() %n the filename (short form; trailing "/" on dir)
645   it() %o the operation, which is "send", "recv", or "del." (the latter includes the trailing period)
646   it() %p the process ID of this rsync session
647   it() %P the module path
648   it() %t the current date time
649   it() %u the authenticated username or an empty string
650   it() %U the uid of the file (decimal)
651 ))
652
653 For a list of what the characters mean that are output by "%i", see the
654 bf(--itemize-changes) option in the rsync manpage.
655
656 Note that some of the logged output changes when talking with older
657 rsync versions.  For instance, deleted files were only output as verbose
658 messages prior to rsync 2.6.4.
659
660 dit(bf(timeout)) This parameter allows you to override the
661 clients choice for I/O timeout for this module. Using this parameter you
662 can ensure that rsync won't wait on a dead client forever. The timeout
663 is specified in seconds. A value of zero means no timeout and is the
664 default. A good choice for anonymous rsync daemons may be 600 (giving
665 a 10 minute timeout).
666
667 dit(bf(refuse options)) This parameter allows you to
668 specify a space-separated list of rsync command line options that will
669 be refused by your rsync daemon.
670 You may specify the full option name, its one-letter abbreviation, or a
671 wild-card string that matches multiple options.
672 For example, this would refuse bf(--checksum) (bf(-c)) and all the various
673 delete options:
674
675 quote(tt(    refuse options = c delete))
676
677 The reason the above refuses all delete options is that the options imply
678 bf(--delete), and implied options are refused just like explicit options.
679 As an additional safety feature, the refusal of "delete" also refuses
680 bf(remove-source-files) when the daemon is the sender; if you want the latter
681 without the former, instead refuse "delete-*" -- that refuses all the
682 delete modes without affecting bf(--remove-source-files).
683
684 When an option is refused, the daemon prints an error message and exits.
685 To prevent all compression when serving files,
686 you can use "dont compress = *" (see below)
687 instead of "refuse options = compress" to avoid returning an error to a
688 client that requests compression.
689
690 dit(bf(dont compress)) This parameter allows you to select
691 filenames based on wildcard patterns that should not be compressed
692 when pulling files from the daemon (no analogous parameter exists to
693 govern the pushing of files to a daemon).
694 Compression is expensive in terms of CPU usage, so it
695 is usually good to not try to compress files that won't compress well,
696 such as already compressed files.
697
698 The "dont compress" parameter takes a space-separated list of
699 case-insensitive wildcard patterns. Any source filename matching one
700 of the patterns will not be compressed during transfer.
701
702 See the bf(--skip-compress) parameter in the bf(rsync)(1) manpage for the list
703 of file suffixes that are not compressed by default.  Specifying a value
704 for the "dont compress" parameter changes the default when the daemon is
705 the sender.
706
707 dit(bf(pre-xfer exec), bf(post-xfer exec)) You may specify a command to be run
708 before and/or after the transfer.  If the bf(pre-xfer exec) command fails, the
709 transfer is aborted before it begins.
710
711 The following environment variables will be set, though some are
712 specific to the pre-xfer or the post-xfer environment:
713
714 quote(itemization(
715   it() bf(RSYNC_MODULE_NAME): The name of the module being accessed.
716   it() bf(RSYNC_MODULE_PATH): The path configured for the module.
717   it() bf(RSYNC_HOST_ADDR): The accessing host's IP address.
718   it() bf(RSYNC_HOST_NAME): The accessing host's name.
719   it() bf(RSYNC_USER_NAME): The accessing user's name (empty if no user).
720   it() bf(RSYNC_PID): A unique number for this transfer.
721   it() bf(RSYNC_REQUEST): (pre-xfer only) The module/path info specified
722   by the user (note that the user can specify multiple source files,
723   so the request can be something like "mod/path1 mod/path2", etc.).
724   it() bf(RSYNC_ARG#): (pre-xfer only) The pre-request arguments are set
725   in these numbered values. RSYNC_ARG0 is always "rsyncd", and the last
726   value contains a single period.
727   it() bf(RSYNC_EXIT_STATUS): (post-xfer only) the server side's exit value.
728   This will be 0 for a successful run, a positive value for an error that the
729   server generated, or a -1 if rsync failed to exit properly.  Note that an
730   error that occurs on the client side does not currently get sent to the
731   server side, so this is not the final exit status for the whole transfer.
732   it() bf(RSYNC_RAW_STATUS): (post-xfer only) the raw exit value from code(waitpid()).
733 ))
734
735 Even though the commands can be associated with a particular module, they
736 are run using the permissions of the user that started the daemon (not the
737 module's uid/gid setting) without any chroot restrictions.
738
739 enddit()
740
741 manpagesection(CONFIG DIRECTIVES)
742
743 There are currently two config directives available that allow a config file to
744 incorporate the contents of other files:  bf(&include) and bf(&merge).  Both
745 allow a reference to either a file or a directory.  They differ in how
746 segregated the file's contents are considered to be.
747
748 The bf(&include) directive treats each file as more distinct, with each one
749 inheriting the defaults of the parent file, starting the parameter parsing
750 as globals/defaults, and leaving the defaults unchanged for the parsing of
751 the rest of the parent file.
752
753 The bf(&merge) directive, on the other hand, treats the file's contents as
754 if it were simply inserted in place of the directive, and thus it can set
755 parameters in a module started in another file, can affect the defaults for
756 other files, etc.
757
758 When an bf(&include) or bf(&merge) directive refers to a directory, it will read
759 in all the bf(*.conf) files contained inside that directory (without any
760 recursive scanning), with the files sorted into alpha order.  So, if you have a
761 directory named "rsyncd.d" with the files "foo.conf", "bar.conf", and
762 "baz.conf" inside it, this directive:
763
764 verb(    &include /path/rsyncd.d )
765
766 would be the same as this set of directives:
767
768 verb(    &include /path/rsyncd.d/bar.conf
769     &include /path/rsyncd.d/baz.conf
770     &include /path/rsyncd.d/foo.conf )
771
772 except that it adjusts as files are added and removed from the directory.
773
774 The advantage of the bf(&include) directive is that you can define one or more
775 modules in a separate file without worrying about unintended side-effects
776 between the self-contained module files.  For instance, this is a useful
777 /etc/rsyncd.conf file:
778
779 verb(    port = 873
780     log file = /var/log/rsync.log
781     pid file = /var/lock/rsync.lock
782
783     &include /etc/rsyncd.d )
784
785 The advantage of the bf(&merge) directive is that you can load config snippets
786 that can be included into multiple module definitions.
787
788 manpagesection(AUTHENTICATION STRENGTH)
789
790 The authentication protocol used in rsync is a 128 bit MD4 based
791 challenge response system. This is fairly weak protection, though (with
792 at least one brute-force hash-finding algorithm publicly available), so
793 if you want really top-quality security, then I recommend that you run
794 rsync over ssh.  (Yes, a future version of rsync will switch over to a
795 stronger hashing method.)
796
797 Also note that the rsync daemon protocol does not currently provide any
798 encryption of the data that is transferred over the connection. Only
799 authentication is provided. Use ssh as the transport if you want
800 encryption.
801
802 Future versions of rsync may support SSL for better authentication and
803 encryption, but that is still being investigated.
804
805 manpagesection(EXAMPLES)
806
807 A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
808 tt(/home/ftp) would be:
809
810 verb(
811 [ftp]
812         path = /home/ftp
813         comment = ftp export area
814 )
815
816 A more sophisticated example would be:
817
818 verb(
819 uid = nobody
820 gid = nobody
821 use chroot = yes
822 max connections = 4
823 syslog facility = local5
824 pid file = /var/run/rsyncd.pid
825
826 [ftp]
827         path = /var/ftp/./pub
828         comment = whole ftp area (approx 6.1 GB)
829
830 [sambaftp]
831         path = /var/ftp/./pub/samba
832         comment = Samba ftp area (approx 300 MB)
833
834 [rsyncftp]
835         path = /var/ftp/./pub/rsync
836         comment = rsync ftp area (approx 6 MB)
837
838 [sambawww]
839         path = /public_html/samba
840         comment = Samba WWW pages (approx 240 MB)
841
842 [cvs]
843         path = /data/cvs
844         comment = CVS repository (requires authentication)
845         auth users = tridge, susan
846         secrets file = /etc/rsyncd.secrets
847 )
848
849 The /etc/rsyncd.secrets file would look something like this:
850
851 quote(
852 tt(tridge:mypass)nl()
853 tt(susan:herpass)nl()
854 )
855
856 manpagefiles()
857
858 /etc/rsyncd.conf or rsyncd.conf
859
860 manpageseealso()
861
862 bf(rsync)(1)
863
864 manpagediagnostics()
865
866 manpagebugs()
867
868 Please report bugs! The rsync bug tracking system is online at
869 url(http://rsync.samba.org/)(http://rsync.samba.org/)
870
871 manpagesection(VERSION)
872
873 This man page is current for version 3.0.3 of rsync.
874
875 manpagesection(CREDITS)
876
877 rsync is distributed under the GNU public license.  See the file
878 COPYING for details.
879
880 The primary ftp site for rsync is
881 url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
882
883 A WEB site is available at
884 url(http://rsync.samba.org/)(http://rsync.samba.org/)
885
886 We would be delighted to hear from you if you like this program.
887
888 This program uses the zlib compression library written by Jean-loup
889 Gailly and Mark Adler.
890
891 manpagesection(THANKS)
892
893 Thanks to Warren Stanley for his original idea and patch for the rsync
894 daemon. Thanks to Karsten Thygesen for his many suggestions and
895 documentation!
896
897 manpageauthor()
898
899 rsync was written by Andrew Tridgell and Paul Mackerras.
900 Many people have later contributed to it.
901
902 Mailing lists for support and development are available at
903 url(http://lists.samba.org)(lists.samba.org)