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