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)
10 The rsyncd.conf file is the runtime configuration file for rsync when
11 run as an rsync daemon.
13 The rsyncd.conf file controls authentication, access, logging and
16 manpagesection(FILE FORMAT)
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".
22 The file is line-based -- that is, each newline-terminated line represents
23 either a comment, a module name or a parameter.
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.
31 Any line beginning with a hash (#) is ignored, as are lines containing
34 Any line ending in a \ is "continued" on the next line in the
35 customary UNIX fashion.
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
42 manpagesection(LAUNCHING THE RSYNC DAEMON)
44 The rsync daemon is launched by specifying the bf(--daemon) option to
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.
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.
56 When run via inetd you should add a line like this to /etc/services:
60 and a single line something like this to /etc/inetd.conf:
62 verb( rsync stream tcp nowait root /usr/bin/rsync rsyncd --daemon)
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.
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
72 manpagesection(GLOBAL PARAMETERS)
74 The first parameters in the file (before a [module] header) are the
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.
82 dit(bf(motd file)) This parameter allows you to specify a
83 "message of the day" to display to clients on each connect. This
84 usually contains site information and any legal notices. The default
86 This can be overridden by the bf(--dparam=motdfile=FILE)
87 command-line option when starting the daemon.
89 dit(bf(pid file)) This parameter tells the rsync daemon to write
90 its process ID to that file. If the file already exists, the rsync
91 daemon will abort rather than overwrite the file.
92 This can be overridden by the bf(--dparam=pidfile=FILE)
93 command-line option when starting the daemon.
95 dit(bf(port)) You can override the default port the daemon will listen on
96 by specifying this value (defaults to 873). This is ignored if the daemon
97 is being run by inetd, and is superseded by the bf(--port) command-line option.
99 dit(bf(address)) You can override the default IP address the daemon
100 will listen on by specifying this value. This is ignored if the daemon is
101 being run by inetd, and is superseded by the bf(--address) command-line option.
103 dit(bf(socket options)) This parameter can provide endless fun for people
104 who like to tune their systems to the utmost degree. You can set all
105 sorts of socket options which may make transfers faster (or
106 slower!). Read the man page for the code(setsockopt()) system call for
107 details on some of the options you may be able to set. By default no
108 special socket options are set. These settings can also be specified
109 via the bf(--sockopts) command-line option.
113 manpagesection(MODULE PARAMETERS)
115 After the global parameters you should define a number of modules, each
116 module exports a directory tree as a symbolic name. Modules are
117 exported by specifying a module name in square brackets [module]
118 followed by the parameters for that module.
119 The module name cannot contain a slash or a closing square bracket. If the
120 name contains whitespace, each internal sequence of whitespace will be
121 changed into a single space, while leading or trailing whitespace will be
126 dit(bf(comment)) This parameter specifies a description string
127 that is displayed next to the module name when clients obtain a list
128 of available modules. The default is no comment.
130 dit(bf(path)) This parameter specifies the directory in the daemon's
131 filesystem to make available in this module. You must specify this parameter
132 for each module in tt(rsyncd.conf).
134 dit(bf(use chroot)) If "use chroot" is true, the rsync daemon will chroot
135 to the "path" before starting the file transfer with the client. This has
136 the advantage of extra protection against possible implementation security
137 holes, but it has the disadvantages of requiring super-user privileges,
138 of not being able to follow symbolic links that are either absolute or outside
139 of the new root path, and of complicating the preservation of users and groups
142 As an additional safety feature, you can specify a dot-dir in the module's
143 "path" to indicate the point where the chroot should occur. This allows rsync
144 to run in a chroot with a non-"/" path for the top of the transfer hierarchy.
145 Doing this guards against unintended library loading (since those absolute
146 paths will not be inside the transfer hierarchy unless you have used an unwise
147 pathname), and lets you setup libraries for the chroot that are outside of the
148 transfer. For example, specifying "/var/rsync/./module1" will chroot to the
149 "/var/rsync" directory and set the inside-chroot path to "/module1". If you
150 had omitted the dot-dir, the chroot would have used the whole path, and the
151 inside-chroot path would have been "/".
153 When "use chroot" is false or the inside-chroot path is not "/", rsync will:
154 (1) munge symlinks by
155 default for security reasons (see "munge symlinks" for a way to turn this
156 off, but only if you trust your users), (2) substitute leading slashes in
157 absolute paths with the module's path (so that options such as
158 bf(--backup-dir), bf(--compare-dest), etc. interpret an absolute path as
159 rooted in the module's "path" dir), and (3) trim ".." path elements from
160 args if rsync believes they would escape the module hierarchy.
161 The default for "use chroot" is true, and is the safer choice (especially
162 if the module is not read-only).
164 When this parameter is enabled, rsync will not attempt to map users and groups
165 by name (by default), but instead copy IDs as though bf(--numeric-ids) had
166 been specified. In order to enable name-mapping, rsync needs to be able to
167 use the standard library functions for looking up names and IDs (i.e.
168 code(getpwuid()), code(getgrgid()), code(getpwname()), and code(getgrnam())).
170 process in the chroot hierarchy will need to have access to the resources
171 used by these library functions (traditionally /etc/passwd and
172 /etc/group, but perhaps additional dynamic libraries as well).
174 If you copy the necessary resources into the module's chroot area, you
175 should protect them through your OS's normal user/group or ACL settings (to
176 prevent the rsync module's user from being able to change them), and then
177 hide them from the user's view via "exclude" (see how in the discussion of
178 that parameter). At that point it will be safe to enable the mapping of users
179 and groups by name using the "numeric ids" daemon parameter (see below).
181 Note also that you are free to setup custom user/group information in the
182 chroot area that is different from your normal system. For example, you
183 could abbreviate the list of users and groups.
185 dit(bf(numeric ids)) Enabling this parameter disables the mapping
186 of users and groups by name for the current daemon module. This prevents
187 the daemon from trying to load any user/group-related files or libraries.
188 This enabling makes the transfer behave as if the client had passed
189 the bf(--numeric-ids) command-line option. By default, this parameter is
190 enabled for chroot modules and disabled for non-chroot modules.
192 A chroot-enabled module should not have this parameter enabled unless you've
193 taken steps to ensure that the module has the necessary resources it needs
194 to translate names, and that it is not possible for a user to change those
197 dit(bf(munge symlinks)) This parameter tells rsync to modify
198 all symlinks in the same way as the (non-daemon-affecting)
199 bf(--munge-links) command-line option (using a method described below).
200 This should help protect your files from user trickery when
201 your daemon module is writable. The default is disabled when "use chroot"
202 is on and the inside-chroot path is "/", otherwise it is enabled.
204 If you disable this parameter on a daemon that is not read-only, there
205 are tricks that a user can play with uploaded symlinks to access
206 daemon-excluded items (if your module has any), and, if "use chroot"
207 is off, rsync can even be tricked into showing or changing data that
208 is outside the module's path (as access-permissions allow).
210 The way rsync disables the use of symlinks is to prefix each one with
211 the string "/rsyncd-munged/". This prevents the links from being used
212 as long as that directory does not exist. When this parameter is enabled,
213 rsync will refuse to run if that path is a directory or a symlink to
214 a directory. When using the "munge symlinks" parameter in a chroot area
215 that has an inside-chroot path of "/", you should add "/rsyncd-munged/"
216 to the exclude setting for the module so that
217 a user can't try to create it.
219 Note: rsync makes no attempt to verify that any pre-existing symlinks in
220 the module's hierarchy are as safe as you want them to be (unless, of
221 course, it just copied in the whole hierarchy). If you setup an rsync
222 daemon on a new area or locally add symlinks, you can manually protect your
223 symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
224 every symlink's value. There is a perl script in the support directory
225 of the source code named "munge-symlinks" that can be used to add or remove
226 this prefix from your symlinks.
228 When this parameter is disabled on a writable module and "use chroot" is off
229 (or the inside-chroot path is not "/"),
230 incoming symlinks will be modified to drop a leading slash and to remove ".."
231 path elements that rsync believes will allow a symlink to escape the module's
232 hierarchy. There are tricky ways to work around this, though, so you had
233 better trust your users if you choose this combination of parameters.
235 dit(bf(charset)) This specifies the name of the character set in which the
236 module's filenames are stored. If the client uses an bf(--iconv) option,
237 the daemon will use the value of the "charset" parameter regardless of the
238 character set the client actually passed. This allows the daemon to
239 support charset conversion in a chroot module without extra files in the
240 chroot area, and also ensures that name-translation is done in a consistent
241 manner. If the "charset" parameter is not set, the bf(--iconv) option is
242 refused, just as if "iconv" had been specified via "refuse options".
244 If you wish to force users to always use bf(--iconv) for a particular
245 module, add "no-iconv" to the "refuse options" parameter. Keep in mind
246 that this will restrict access to your module to very new rsync clients.
248 dit(bf(max connections)) This parameter allows you to
249 specify the maximum number of simultaneous connections you will allow.
250 Any clients connecting when the maximum has been reached will receive a
251 message telling them to try later. The default is 0, which means no limit.
252 A negative value disables the module.
253 See also the "lock file" parameter.
255 dit(bf(log file)) When the "log file" parameter is set to a non-empty
256 string, the rsync daemon will log messages to the indicated file rather
257 than using syslog. This is particularly useful on systems (such as AIX)
258 where code(syslog()) doesn't work for chrooted programs. The file is
259 opened before code(chroot()) is called, allowing it to be placed outside
260 the transfer. If this value is set on a per-module basis instead of
261 globally, the global log will still contain any authorization failures
262 or config-file error messages.
264 If the daemon fails to open the specified file, it will fall back to
265 using syslog and output an error about the failure. (Note that the
266 failure to open the specified log file used to be a fatal error.)
268 This setting can be overridden by using the bf(--log-file=FILE) or
269 bf(--dparam=logfile=FILE) command-line options. The former overrides
270 all the log-file parameters of the daemon and all module settings.
271 The latter sets the daemon's log file and the default for all the
272 modules, which still allows modules to override the default setting.
274 dit(bf(syslog facility)) This parameter allows you to
275 specify the syslog facility name to use when logging messages from the
276 rsync daemon. You may use any standard syslog facility name which is
277 defined on your system. Common names are auth, authpriv, cron, daemon,
278 ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0,
279 local1, local2, local3, local4, local5, local6 and local7. The default
280 is daemon. This setting has no effect if the "log file" setting is a
281 non-empty string (either set in the per-modules settings, or inherited
282 from the global settings).
284 dit(bf(max verbosity)) This parameter allows you to control
285 the maximum amount of verbose information that you'll allow the daemon to
286 generate (since the information goes into the log file). The default is 1,
287 which allows the client to request one level of verbosity.
289 dit(bf(lock file)) This parameter specifies the file to use to
290 support the "max connections" parameter. The rsync daemon uses record
291 locking on this file to ensure that the max connections limit is not
292 exceeded for the modules sharing the lock file.
293 The default is tt(/var/run/rsyncd.lock).
295 dit(bf(read only)) This parameter determines whether clients
296 will be able to upload files or not. If "read only" is true then any
297 attempted uploads will fail. If "read only" is false then uploads will
298 be possible if file permissions on the daemon side allow them. The default
299 is for all modules to be read only.
301 dit(bf(write only)) This parameter determines whether clients
302 will be able to download files or not. If "write only" is true then any
303 attempted downloads will fail. If "write only" is false then downloads
304 will be possible if file permissions on the daemon side allow them. The
305 default is for this parameter to be disabled.
307 dit(bf(list)) This parameter determines whether this module is
308 listed when the client asks for a listing of available modules. In addition,
309 if this is false, the daemon will pretend the module does not exist
310 when a client denied by "hosts allow" or "hosts deny" attempts to access it.
311 Realize that if "reverse lookup" is disabled globally but enabled for the
312 module, the resulting reverse lookup to a potentially client-controlled DNS
313 server may still reveal to the client that it hit an existing module.
314 The default is for modules to be listable.
316 dit(bf(uid)) This parameter specifies the user name or user ID that
317 file transfers to and from that module should take place as when the daemon
318 was run as root. In combination with the "gid" parameter this determines what
319 file permissions are available. The default is uid -2, which is normally
322 dit(bf(gid)) This parameter specifies the group name or group ID that
323 file transfers to and from that module should take place as when the daemon
324 was run as root. This complements the "uid" parameter. The default is gid -2,
325 which is normally the group "nobody".
327 dit(bf(fake super)) Setting "fake super = yes" for a module causes the
328 daemon side to behave as if the bf(--fake-user) command-line option had
329 been specified. This allows the full attributes of a file to be stored
330 without having to have the daemon actually running as root.
332 dit(bf(filter)) The daemon has its own filter chain that determines what files
333 it will let the client access. This chain is not sent to the client and is
334 independent of any filters the client may have specified. Files excluded by
335 the daemon filter chain (bf(daemon-excluded) files) are treated as non-existent
336 if the client tries to pull them, are skipped with an error message if the
337 client tries to push them (triggering exit code 23), and are never deleted from
338 the module. You can use daemon filters to prevent clients from downloading or
339 tampering with private administrative files, such as files you may add to
340 support uid/gid name translations.
342 The daemon filter chain is built from the "filter", "include from", "include",
343 "exclude from", and "exclude" parameters, in that order of priority. Anchored
344 patterns are anchored at the root of the module. To prevent access to an
345 entire subtree, for example, "/secret", you em(must) exclude everything in the
346 subtree; the easiest way to do this is with a triple-star pattern like
349 The "filter" parameter takes a space-separated list of daemon filter rules,
350 though it is smart enough to know not to split a token at an internal space in
351 a rule (e.g. "- /foo - /bar" is parsed as two rules). You may specify one or
352 more merge-file rules using the normal syntax. Only one "filter" parameter can
353 apply to a given module in the config file, so put all the rules you want in a
354 single parameter. Note that per-directory merge-file rules do not provide as
355 much protection as global rules, but they can be used to make bf(--delete) work
356 better during a client download operation if the per-dir merge files are
357 included in the transfer and the client requests that they be used.
359 dit(bf(exclude)) This parameter takes a space-separated list of daemon
360 exclude patterns. As with the client bf(--exclude) option, patterns can be
361 qualified with "- " or "+ " to explicitly indicate exclude/include. Only one
362 "exclude" parameter can apply to a given module. See the "filter" parameter
363 for a description of how excluded files affect the daemon.
365 dit(bf(include)) Use an "include" to override the effects of the "exclude"
366 parameter. Only one "include" parameter can apply to a given module. See the
367 "filter" parameter for a description of how excluded files affect the daemon.
369 dit(bf(exclude from)) This parameter specifies the name of a file
370 on the daemon that contains daemon exclude patterns, one per line. Only one
371 "exclude from" parameter can apply to a given module; if you have multiple
372 exclude-from files, you can specify them as a merge file in the "filter"
373 parameter. See the "filter" parameter for a description of how excluded files
376 dit(bf(include from)) Analogue of "exclude from" for a file of daemon include
377 patterns. Only one "include from" parameter can apply to a given module. See
378 the "filter" parameter for a description of how excluded files affect the
381 dit(bf(incoming chmod)) This parameter allows you to specify a set of
382 comma-separated chmod strings that will affect the permissions of all
383 incoming files (files that are being received by the daemon). These
384 changes happen after all other permission calculations, and this will
385 even override destination-default and/or existing permissions when the
386 client does not specify bf(--perms).
387 See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
388 manpage for information on the format of this string.
390 dit(bf(outgoing chmod)) This parameter allows you to specify a set of
391 comma-separated chmod strings that will affect the permissions of all
392 outgoing files (files that are being sent out from the daemon). These
393 changes happen first, making the sent permissions appear to be different
394 than those stored in the filesystem itself. For instance, you could
395 disable group write permissions on the server while having it appear to
396 be on to the clients.
397 See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
398 manpage for information on the format of this string.
400 dit(bf(auth users)) This parameter specifies a comma and
401 space-separated list of usernames that will be allowed to connect to
402 this module. The usernames do not need to exist on the local
403 system. The usernames may also contain shell wildcard characters. If
404 "auth users" is set then the client will be challenged to supply a
405 username and password to connect to the module. A challenge response
406 authentication protocol is used for this exchange. The plain text
407 usernames and passwords are stored in the file specified by the
408 "secrets file" parameter. The default is for all users to be able to
409 connect without a password (this is called "anonymous rsync").
411 See also the "CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL
412 PROGRAM" section in bf(rsync)(1) for information on how handle an
413 rsyncd.conf-level username that differs from the remote-shell-level
414 username when using a remote shell to connect to an rsync daemon.
416 dit(bf(secrets file)) This parameter specifies the name of
417 a file that contains the username:password pairs used for
418 authenticating this module. This file is only consulted if the "auth
419 users" parameter is specified. The file is line based and contains
420 username:password pairs separated by a single colon. Any line starting
421 with a hash (#) is considered a comment and is skipped. The passwords
422 can contain any characters but be warned that many operating systems
423 limit the length of passwords that can be typed at the client end, so
424 you may find that passwords longer than 8 characters don't work.
426 There is no default for the "secrets file" parameter, you must choose a name
427 (such as tt(/etc/rsyncd.secrets)). The file must normally not be readable
428 by "other"; see "strict modes".
430 dit(bf(strict modes)) This parameter determines whether or not
431 the permissions on the secrets file will be checked. If "strict modes" is
432 true, then the secrets file must not be readable by any user ID other
433 than the one that the rsync daemon is running under. If "strict modes" is
434 false, the check is not performed. The default is true. This parameter
435 was added to accommodate rsync running on the Windows operating system.
437 dit(bf(hosts allow)) This parameter allows you to specify a
438 list of patterns that are matched against a connecting clients
439 hostname and IP address. If none of the patterns match then the
440 connection is rejected.
442 Each pattern can be in one of five forms:
445 it() a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address
446 of the form a:b:c::d:e:f. In this case the incoming machine's IP address
448 it() an address/mask in the form ipaddr/n where ipaddr is the IP address
449 and n is the number of one bits in the netmask. All IP addresses which
450 match the masked IP address will be allowed in.
451 it() an address/mask in the form ipaddr/maskaddr where ipaddr is the
452 IP address and maskaddr is the netmask in dotted decimal notation for IPv4,
453 or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
454 addresses which match the masked IP address will be allowed in.
455 it() a hostname. The hostname as determined by a reverse lookup will
456 be matched (case insensitive) against the pattern. Only an exact
457 match is allowed in. This only works if "reverse lookup" is enabled
459 it() a hostname pattern using wildcards. These are matched using the
460 same rules as normal unix filename matching. If the pattern matches
461 then the client is allowed in.
464 Note IPv6 link-local addresses can have a scope in the address specification:
467 tt( fe80::1%link1)nl()
468 tt( fe80::%link1/64)nl()
469 tt( fe80::%link1/ffff:ffff:ffff:ffff::)nl()
472 You can also combine "hosts allow" with a separate "hosts deny"
473 parameter. If both parameters are specified then the "hosts allow" parameter is
474 checked first and a match results in the client being able to
475 connect. The "hosts deny" parameter is then checked and a match means
476 that the host is rejected. If the host does not match either the
477 "hosts allow" or the "hosts deny" patterns then it is allowed to
480 The default is no "hosts allow" parameter, which means all hosts can connect.
482 dit(bf(hosts deny)) This parameter allows you to specify a
483 list of patterns that are matched against a connecting clients
484 hostname and IP address. If the pattern matches then the connection is
485 rejected. See the "hosts allow" parameter for more information.
487 The default is no "hosts deny" parameter, which means all hosts can connect.
489 dit(bf(reverse lookup)) Controls whether the daemon performs a reverse lookup
490 on the client's IP address to determine its hostname, which is used for
491 "hosts allow"/"hosts deny" checks and the "%h" log escape. This is enabled by
492 default, but you may wish to disable it to save time if you know the lookup will
493 not return a useful result, in which case the daemon will use the name
494 "UNDETERMINED" instead.
496 If this parameter is enabled globally (even by default), rsync performs the
497 lookup as soon as a client connects, so disabling it for a module will not
498 avoid the lookup. Thus, you probably want to disable it globally and then
499 enable it for modules that need the information.
501 dit(bf(ignore errors)) This parameter tells rsyncd to
502 ignore I/O errors on the daemon when deciding whether to run the delete
503 phase of the transfer. Normally rsync skips the bf(--delete) step if any
504 I/O errors have occurred in order to prevent disastrous deletion due
505 to a temporary resource shortage or other I/O error. In some cases this
506 test is counter productive so you can use this parameter to turn off this
509 dit(bf(ignore nonreadable)) This tells the rsync daemon to completely
510 ignore files that are not readable by the user. This is useful for
511 public archives that may have some non-readable files among the
512 directories, and the sysadmin doesn't want those files to be seen at all.
514 dit(bf(transfer logging)) This parameter enables per-file
515 logging of downloads and uploads in a format somewhat similar to that
516 used by ftp daemons. The daemon always logs the transfer at the end, so
517 if a transfer is aborted, no mention will be made in the log file.
519 If you want to customize the log lines, see the "log format" parameter.
521 dit(bf(log format)) This parameter allows you to specify the
522 format used for logging file transfers when transfer logging is enabled.
523 The format is a text string containing embedded single-character escape
524 sequences prefixed with a percent (%) character. An optional numeric
525 field width may also be specified between the percent and the escape
526 letter (e.g. "bf(%-50n %8l %07p)").
528 The default log format is "%o %h [%a] %m (%u) %f %l", and a "%t [%p] "
529 is always prefixed when using the "log file" parameter.
530 (A perl script that will summarize this default log format is included
531 in the rsync source code distribution in the "support" subdirectory:
534 The single-character escapes that are understood are as follows:
537 it() %a the remote IP address
538 it() %b the number of bytes actually transferred
539 it() %B the permission bits of the file (e.g. rwxrwxrwt)
540 it() %c the total size of the block checksums received for the basis file (only when sending)
541 it() %C the full-file MD5 checksum if bf(--checksum) is enabled or a file was transferred (only for protocol 30 or above).
542 it() %f the filename (long form on sender; no trailing "/")
543 it() %G the gid of the file (decimal) or "DEFAULT"
544 it() %h the remote host name
545 it() %i an itemized list of what is being updated
546 it() %l the length of the file in bytes
547 it() %L the string " -> SYMLINK", " => HARDLINK", or "" (where bf(SYMLINK) or bf(HARDLINK) is a filename)
548 it() %m the module name
549 it() %M the last-modified time of the file
550 it() %n the filename (short form; trailing "/" on dir)
551 it() %o the operation, which is "send", "recv", or "del." (the latter includes the trailing period)
552 it() %p the process ID of this rsync session
553 it() %P the module path
554 it() %t the current date time
555 it() %u the authenticated username or an empty string
556 it() %U the uid of the file (decimal)
559 For a list of what the characters mean that are output by "%i", see the
560 bf(--itemize-changes) option in the rsync manpage.
562 Note that some of the logged output changes when talking with older
563 rsync versions. For instance, deleted files were only output as verbose
564 messages prior to rsync 2.6.4.
566 dit(bf(timeout)) This parameter allows you to override the
567 clients choice for I/O timeout for this module. Using this parameter you
568 can ensure that rsync won't wait on a dead client forever. The timeout
569 is specified in seconds. A value of zero means no timeout and is the
570 default. A good choice for anonymous rsync daemons may be 600 (giving
571 a 10 minute timeout).
573 dit(bf(refuse options)) This parameter allows you to
574 specify a space-separated list of rsync command line options that will
575 be refused by your rsync daemon.
576 You may specify the full option name, its one-letter abbreviation, or a
577 wild-card string that matches multiple options.
578 For example, this would refuse bf(--checksum) (bf(-c)) and all the various
581 quote(tt( refuse options = c delete))
583 The reason the above refuses all delete options is that the options imply
584 bf(--delete), and implied options are refused just like explicit options.
585 As an additional safety feature, the refusal of "delete" also refuses
586 bf(remove-source-files) when the daemon is the sender; if you want the latter
587 without the former, instead refuse "delete-*" -- that refuses all the
588 delete modes without affecting bf(--remove-source-files).
590 When an option is refused, the daemon prints an error message and exits.
591 To prevent all compression when serving files,
592 you can use "dont compress = *" (see below)
593 instead of "refuse options = compress" to avoid returning an error to a
594 client that requests compression.
596 dit(bf(dont compress)) This parameter allows you to select
597 filenames based on wildcard patterns that should not be compressed
598 when pulling files from the daemon (no analogous parameter exists to
599 govern the pushing of files to a daemon).
600 Compression is expensive in terms of CPU usage, so it
601 is usually good to not try to compress files that won't compress well,
602 such as already compressed files.
604 The "dont compress" parameter takes a space-separated list of
605 case-insensitive wildcard patterns. Any source filename matching one
606 of the patterns will not be compressed during transfer.
608 See the bf(--skip-compress) parameter in the bf(rsync)(1) manpage for the list
609 of file suffixes that are not compressed by default. Specifying a value
610 for the "dont compress" parameter changes the default when the daemon is
613 dit(bf(pre-xfer exec), bf(post-xfer exec)) You may specify a command to be run
614 before and/or after the transfer. If the bf(pre-xfer exec) command fails, the
615 transfer is aborted before it begins.
617 The following environment variables will be set, though some are
618 specific to the pre-xfer or the post-xfer environment:
621 it() bf(RSYNC_MODULE_NAME): The name of the module being accessed.
622 it() bf(RSYNC_MODULE_PATH): The path configured for the module.
623 it() bf(RSYNC_HOST_ADDR): The accessing host's IP address.
624 it() bf(RSYNC_HOST_NAME): The accessing host's name.
625 it() bf(RSYNC_USER_NAME): The accessing user's name (empty if no user).
626 it() bf(RSYNC_PID): A unique number for this transfer.
627 it() bf(RSYNC_REQUEST): (pre-xfer only) The module/path info specified
628 by the user (note that the user can specify multiple source files,
629 so the request can be something like "mod/path1 mod/path2", etc.).
630 it() bf(RSYNC_ARG#): (pre-xfer only) The pre-request arguments are set
631 in these numbered values. RSYNC_ARG0 is always "rsyncd", and the last
632 value contains a single period.
633 it() bf(RSYNC_EXIT_STATUS): (post-xfer only) the server side's exit value.
634 This will be 0 for a successful run, a positive value for an error that the
635 server generated, or a -1 if rsync failed to exit properly. Note that an
636 error that occurs on the client side does not currently get sent to the
637 server side, so this is not the final exit status for the whole transfer.
638 it() bf(RSYNC_RAW_STATUS): (post-xfer only) the raw exit value from code(waitpid()).
641 Even though the commands can be associated with a particular module, they
642 are run using the permissions of the user that started the daemon (not the
643 module's uid/gid setting) without any chroot restrictions.
647 manpagesection(CONFIG DIRECTIVES)
649 There are currently two config directives available that allow a config file to
650 incorporate the contents of other files: bf(&include) and bf(&merge). Both
651 allow a reference to either a file or a directory. They differ in how
652 segregated the file's contents are considered to be.
654 The bf(&include) directive treats each file as more distinct, with each one
655 inheriting the defaults of the parent file, starting the parameter parsing
656 as globals/defaults, and leaving the defaults unchanged for the parsing of
657 the rest of the parent file.
659 The bf(&merge) directive, on the other hand, treats the file's contents as
660 if it were simply inserted in place of the directive, and thus it can set
661 parameters in a module started in another file, can affect the defaults for
664 When an bf(&include) or bf(&merge) directive refers to a directory, it will read
665 in all the bf(*.conf) files contained inside that directory (without any
666 recursive scanning), with the files sorted into alpha order. So, if you have a
667 directory named "rsyncd.d" with the files "foo.conf", "bar.conf", and
668 "baz.conf" inside it, this directive:
670 verb( &include /path/rsyncd.d )
672 would be the same as this set of directives:
674 verb( &include /path/rsyncd.d/bar.conf
675 &include /path/rsyncd.d/baz.conf
676 &include /path/rsyncd.d/foo.conf )
678 except that it adjusts as files are added and removed from the directory.
680 The advantage of the bf(&include) directive is that you can define one or more
681 modules in a separate file without worrying about unintended side-effects
682 between the self-contained module files. For instance, this is a useful
683 /etc/rsyncd.conf file:
686 log file = /var/log/rsync.log
687 pid file = /var/lock/rsync.lock
689 &include /etc/rsyncd.d )
691 The advantage of the bf(&merge) directive is that you can load config snippets
692 that can be included into multiple module definitions.
694 manpagesection(AUTHENTICATION STRENGTH)
696 The authentication protocol used in rsync is a 128 bit MD4 based
697 challenge response system. This is fairly weak protection, though (with
698 at least one brute-force hash-finding algorithm publicly available), so
699 if you want really top-quality security, then I recommend that you run
700 rsync over ssh. (Yes, a future version of rsync will switch over to a
701 stronger hashing method.)
703 Also note that the rsync daemon protocol does not currently provide any
704 encryption of the data that is transferred over the connection. Only
705 authentication is provided. Use ssh as the transport if you want
708 Future versions of rsync may support SSL for better authentication and
709 encryption, but that is still being investigated.
711 manpagesection(EXAMPLES)
713 A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
714 tt(/home/ftp) would be:
719 comment = ftp export area
722 A more sophisticated example would be:
729 syslog facility = local5
730 pid file = /var/run/rsyncd.pid
733 path = /var/ftp/./pub
734 comment = whole ftp area (approx 6.1 GB)
737 path = /var/ftp/./pub/samba
738 comment = Samba ftp area (approx 300 MB)
741 path = /var/ftp/./pub/rsync
742 comment = rsync ftp area (approx 6 MB)
745 path = /public_html/samba
746 comment = Samba WWW pages (approx 240 MB)
750 comment = CVS repository (requires authentication)
751 auth users = tridge, susan
752 secrets file = /etc/rsyncd.secrets
755 The /etc/rsyncd.secrets file would look something like this:
758 tt(tridge:mypass)nl()
759 tt(susan:herpass)nl()
764 /etc/rsyncd.conf or rsyncd.conf
774 Please report bugs! The rsync bug tracking system is online at
775 url(http://rsync.samba.org/)(http://rsync.samba.org/)
777 manpagesection(VERSION)
779 This man page is current for version 3.0.3 of rsync.
781 manpagesection(CREDITS)
783 rsync is distributed under the GNU public license. See the file
786 The primary ftp site for rsync is
787 url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
789 A WEB site is available at
790 url(http://rsync.samba.org/)(http://rsync.samba.org/)
792 We would be delighted to hear from you if you like this program.
794 This program uses the zlib compression library written by Jean-loup
795 Gailly and Mark Adler.
797 manpagesection(THANKS)
799 Thanks to Warren Stanley for his original idea and patch for the rsync
800 daemon. Thanks to Karsten Thygesen for his many suggestions and
805 rsync was written by Andrew Tridgell and Paul Mackerras.
806 Many people have later contributed to it.
808 Mailing lists for support and development are available at
809 url(http://lists.samba.org)(lists.samba.org)