Add a new daemon security option: "munge symlinks".
[rsync/rsync.git] / rsyncd.conf.yo
CommitLineData
9e3c856a 1mailto(rsync-bugs@samba.org)
732b3917 2manpage(rsyncd.conf)(5)(8 Nov 2007)()()
d90338ce 3manpagename(rsyncd.conf)(configuration file for rsync in daemon mode)
41059f75
AT
4manpagesynopsis()
5
6rsyncd.conf
7
8manpagedescription()
9
10The rsyncd.conf file is the runtime configuration file for rsync when
f97c2d4a 11run as an rsync daemon.
41059f75
AT
12
13The rsyncd.conf file controls authentication, access, logging and
14available modules.
15
16manpagesection(FILE FORMAT)
17
f97c2d4a 18The file consists of modules and parameters. A module begins with the
41059f75 19name of the module in square brackets and continues until the next
0abe148f 20module begins. Modules contain parameters of the form "name = value".
41059f75 21
faa82484 22The file is line-based -- that is, each newline-terminated line represents
41059f75
AT
23either a comment, a module name or a parameter.
24
f97c2d4a 25Only the first equals sign in a parameter is significant. Whitespace before
41059f75
AT
26or after the first equals sign is discarded. Leading, trailing and internal
27whitespace in module and parameter names is irrelevant. Leading and
28trailing whitespace in a parameter value is discarded. Internal whitespace
29within a parameter value is retained verbatim.
30
f97c2d4a 31Any line beginning with a hash (#) is ignored, as are lines containing
41059f75
AT
32only whitespace.
33
e22de162 34Any line ending in a \ is "continued" on the next line in the
41059f75
AT
35customary UNIX fashion.
36
37The 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
39true/false. Case is not significant in boolean values, but is preserved
f97c2d4a 40in string values.
41059f75 41
5315b793 42manpagesection(LAUNCHING THE RSYNC DAEMON)
41059f75 43
faa82484 44The rsync daemon is launched by specifying the bf(--daemon) option to
f97c2d4a 45rsync.
f5c20813
MP
46
47The daemon must run with root privileges if you wish to use chroot, to
48bind to a port numbered under 1024 (as is the default 873), or to set
49file ownership. Otherwise, it must just have permission to read and
50write the appropriate data, log, and lock files.
41059f75 51
04657e42
DD
52You can launch it either via inetd, as a stand-alone daemon, or from
53an rsync client via a remote shell. If run as a stand-alone daemon then
faa82484 54just run the command "bf(rsync --daemon)" from a suitable startup script.
41059f75
AT
55
56When run via inetd you should add a line like this to /etc/services:
57
faa82484 58verb( rsync 873/tcp)
41059f75 59
e22de162 60and a single line something like this to /etc/inetd.conf:
f97c2d4a 61
faa82484 62verb( rsync stream tcp nowait root /usr/bin/rsync rsyncd --daemon)
41059f75 63
79f118d8
DD
64Replace "/usr/bin/rsync" with the path to where you have rsync installed on
65your system. You will then need to send inetd a HUP signal to tell it to
66reread its config file.
41059f75 67
d90338ce 68Note that you should bf(not) send the rsync daemon a HUP signal to force
30e8c8e1 69it to reread the tt(rsyncd.conf) file. The file is re-read on each client
f97c2d4a 70connection.
41059f75
AT
71
72manpagesection(GLOBAL OPTIONS)
73
74The first parameters in the file (before a [module] header) are the
f97c2d4a 75global parameters.
41059f75
AT
76
77You may also include any module parameters in the global part of the
78config file in which case the supplied value will override the
79default for that parameter.
80
81startdit()
82dit(bf(motd file)) The "motd file" option allows you to specify a
5315b793 83"message of the day" to display to clients on each connect. This
41059f75
AT
84usually contains site information and any legal notices. The default
85is no motd file.
86
8638dd48 87dit(bf(pid file)) The "pid file" option tells the rsync daemon to write
306847ea
WD
88its process ID to that file. If the file already exists, the rsync
89daemon will abort rather than overwrite the file.
37863201 90
f7112154
WD
91dit(bf(port)) You can override the default port the daemon will listen on
92by specifying this value (defaults to 873). This is ignored if the daemon
93is being run by inetd, and is superseded by the bf(--port) command-line option.
94
95dit(bf(address)) You can override the default IP address the daemon
96will listen on by specifying this value. This is ignored if the daemon is
97being run by inetd, and is superseded by the bf(--address) command-line option.
98
a6801c39
AT
99dit(bf(socket options)) This option can provide endless fun for people
100who like to tune their systems to the utmost degree. You can set all
101sorts of socket options which may make transfers faster (or
19826af5 102slower!). Read the man page for the code(setsockopt()) system call for
a6801c39 103details on some of the options you may be able to set. By default no
5fe3c86f
WD
104special socket options are set. These settings are superseded by the
105bf(--sockopts) command-line option.
a6801c39 106
41059f75
AT
107enddit()
108
109
110manpagesection(MODULE OPTIONS)
111
112After the global options you should define a number of modules, each
113module exports a directory tree as a symbolic name. Modules are
114exported by specifying a module name in square brackets [module]
115followed by the options for that module.
116
117startdit()
118
119dit(bf(comment)) The "comment" option specifies a description string
120that is displayed next to the module name when clients obtain a list
121of available modules. The default is no comment.
122
d90338ce 123dit(bf(path)) The "path" option specifies the directory in the daemon's
8638dd48 124filesystem to make available in this module. You must specify this option
30e8c8e1 125for each module in tt(rsyncd.conf).
8638dd48 126
d90338ce 127dit(bf(use chroot)) If "use chroot" is true, the rsync daemon will chroot
8638dd48
DD
128to the "path" before starting the file transfer with the client. This has
129the advantage of extra protection against possible implementation security
f97c2d4a 130holes, but it has the disadvantages of requiring super-user privileges,
1a7f3d99
WD
131of not being able to follow symbolic links that are either absolute or outside
132of the new root path, and of complicating the preservation of usernames and groups
9585b276
WD
133(see below). When "use chroot" is false, rsync will: (1) munge symlinks by
134default for security reasons (see "munge symlinks" for a way to turn this
135off, but only if you trust your users), (2) substitute leading slashes in
136absolute paths with the module's path (so that options such as
137bf(--backup-dir), bf(--compare-dest), etc. interpret an absolute path as
138rooted in the module's "path" dir), and (3) trim ".." path elements from
139args if rsync believes they would escape the chroot.
140The default for "use chroot" is true, and is the safer choice (especially
141if the module is not read-only).
41059f75 142
cb290916 143In order to preserve usernames and groupnames, rsync needs to be able to
d99b4ccf 144use the standard library functions for looking up names and IDs (i.e.
19826af5 145code(getpwuid()), code(getgrgid()), code(getpwname()), and code(getgrnam())). This means a
d99b4ccf
WD
146process in the chroot namespace will need to have access to the resources
147used by these library functions (traditionally /etc/passwd and
148/etc/group). If these resources are not available, rsync will only be
faa82484 149able to copy the IDs, just as if the bf(--numeric-ids) option had been
d99b4ccf
WD
150specified.
151
152Note that you are free to setup user/group information in the chroot area
153differently from your normal system. For example, you could abbreviate
553f9375 154the list of users and groups. Also, you can protect this information from
d802ea54 155being downloaded/uploaded by adding an exclude rule to the rsyncd.conf file
0abe148f 156(e.g. "bf(exclude = /etc/**)"). Note that having the exclusion affect uploads
d90338ce 157is a relatively new feature in rsync, so make sure your daemon is
78bcddcc
WD
158at least 2.6.3 to effect this. Also note that it is safest to exclude a
159directory and all its contents combining the rule "/some/dir/" with the
160rule "/some/dir/**" just to be sure that rsync will not allow deeper
161access to some of the excluded files inside the directory (rsync tries to
162do this automatically, but you might as well specify both to be extra
163sure).
cb290916 164
9585b276
WD
165dit(bf(munge symlinks)) The "munge symlinks" option tells rsync to modify
166all incoming symlinks in a way that makes them unusable but recoverable
167(see below). This should help protect your files from user trickery when
168your daemon module is writable. The default is disabled when "use chroot"
169is on and enabled when "use chroot" is off.
170
171If you disable this option on a daemon that is not read-only, there
172are tricks that a user can play with uploaded symlinks to access
173daemon-excluded items (if your module has any), and, if "use chroot"
174is off, rsync can even be tricked into showing or changing data that
175is outside the module's path (as access-permissions allow).
176
177The way rsync disables the use of symlinks is to prefix each one with
178the string "/rsyncd-munged/". This prevents the links from being used
179as long as that directory does not exist. When this option is enabled,
180rsync will refuse to run if that path is a directory or a symlink to
181a directory. When using the "munge symlinks" option in a chroot area,
182you should add this path to the exclude setting for the module so that
183the user can't try to create it.
184
185Note: rsync makes no attempt to verify that any pre-existing symlinks in
186the hierarchy are as safe as you want them to be. If you setup an rsync
187daemon on a new area or locally add symlinks, you can manually protect your
188symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
189every symlink's value. There is a perl script in the support directory
190of the source code named "munge-symlinks" that can be used to add or remove
191this prefix from your symlinks.
192
5e71c444 193dit(bf(max connections)) The "max connections" option allows you to
9ef1cc7c
DD
194specify the maximum number of simultaneous connections you will allow.
195Any clients connecting when the maximum has been reached will receive a
3170b209
WD
196message telling them to try later. The default is 0, which means no limit.
197A negative value disables the module.
9ef1cc7c 198See also the "lock file" option.
5e71c444 199
ccd2966d
WD
200dit(bf(log file)) When the "log file" option is set to a non-empty
201string, the rsync daemon will log messages to the indicated file rather
202than using syslog. This is particularly useful on systems (such as AIX)
203where code(syslog()) doesn't work for chrooted programs. The file is
204opened before code(chroot()) is called, allowing it to be placed outside
205the transfer. If this value is set on a per-module basis instead of
206globally, the global log will still contain any authorization failures
207or config-file error messages.
208
209If the daemon fails to open to specified file, it will fall back to
210using syslog and output an error about the failure. (Note that the
211failure to open the specified log file used to be a fatal error.)
212
213dit(bf(syslog facility)) The "syslog facility" option allows you to
214specify the syslog facility name to use when logging messages from the
215rsync daemon. You may use any standard syslog facility name which is
216defined on your system. Common names are auth, authpriv, cron, daemon,
217ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0,
218local1, local2, local3, local4, local5, local6 and local7. The default
219is daemon. This setting has no effect if the "log file" setting is a
220non-empty string (either set in the per-modules settings, or inherited
221from the global settings).
222
21611119
WD
223dit(bf(max verbosity)) The "max verbosity" option allows you to control
224the maximum amount of verbose information that you'll allow the daemon to
225generate (since the information goes into the log file). The default is 1,
226which allows the client to request one level of verbosity.
227
5e71c444 228dit(bf(lock file)) The "lock file" option specifies the file to use to
d90338ce 229support the "max connections" option. The rsync daemon uses record
5e71c444 230locking on this file to ensure that the max connections limit is not
f97c2d4a 231exceeded for the modules sharing the lock file.
9ef1cc7c 232The default is tt(/var/run/rsyncd.lock).
5e71c444 233
41059f75
AT
234dit(bf(read only)) The "read only" option determines whether clients
235will be able to upload files or not. If "read only" is true then any
236attempted uploads will fail. If "read only" is false then uploads will
d90338ce 237be possible if file permissions on the daemon side allow them. The default
41059f75
AT
238is for all modules to be read only.
239
7a92ded3
WD
240dit(bf(write only)) The "write only" option determines whether clients
241will be able to download files or not. If "write only" is true then any
242attempted downloads will fail. If "write only" is false then downloads
d90338ce 243will be possible if file permissions on the daemon side allow them. The
7a92ded3
WD
244default is for this option to be disabled.
245
41059f75
AT
246dit(bf(list)) The "list" option determines if this module should be
247listed when the client asks for a listing of available modules. By
248setting this to false you can create hidden modules. The default is
249for modules to be listable.
250
58811a0a 251dit(bf(uid)) The "uid" option specifies the user name or user ID that
716baed7
DD
252file transfers to and from that module should take place as when the daemon
253was run as root. In combination with the "gid" option this determines what
2af27ad9
MP
254file permissions are available. The default is uid -2, which is normally
255the user "nobody".
41059f75 256
58811a0a 257dit(bf(gid)) The "gid" option specifies the group name or group ID that
716baed7 258file transfers to and from that module should take place as when the daemon
2af27ad9
MP
259was run as root. This complements the "uid" option. The default is gid -2,
260which is normally the group "nobody".
41059f75 261
9439c0cb
WD
262dit(bf(fake super)) Setting "fake super = yes" for a module causes the
263daemon side to behave as if the bf(--fake-user) command-line option had
264been specified. This allows the full attributes of a file to be stored
265without having to have the daemon actually running as root.
266
dd69b397 267dit(bf(filter)) The "filter" option allows you to specify a space-separated
d90338ce 268list of filter rules that the daemon will not allow to be read or written.
dd69b397 269This is only superficially equivalent to the client specifying these
faa82484 270patterns with the bf(--filter) option. Only one "filter" option may be
dd69b397
WD
271specified, but it may contain as many rules as you like, including
272merge-file rules. Note that per-directory merge-file rules do not provide
faa82484 273as much protection as global rules, but they can be used to make bf(--delete)
d90338ce 274work better when a client downloads the daemon's files (if the per-dir
dd69b397
WD
275merge files are included in the transfer).
276
553f9375 277dit(bf(exclude)) The "exclude" option allows you to specify a
d90338ce 278space-separated list of patterns that the daemon will not allow to be read
553f9375 279or written. This is only superficially equivalent to the client
faa82484 280specifying these patterns with the bf(--exclude) option. Only one "exclude"
553f9375
WD
281option may be specified, but you can use "-" and "+" before patterns to
282specify exclude/include.
83fd337d
S
283
284Because this exclude list is not passed to the client it only applies on
d90338ce
WD
285the daemon: that is, it excludes files received by a client when receiving
286from a daemon and files deleted on a daemon when sending to a daemon, but
553f9375 287it doesn't exclude files from being deleted on a client when receiving
f97c2d4a 288from a daemon.
8f3a2d54
AT
289
290dit(bf(exclude from)) The "exclude from" option specifies a filename
d90338ce 291on the daemon that contains exclude patterns, one per line.
83fd337d 292This is only superficially equivalent
faa82484 293to the client specifying the bf(--exclude-from) option with an equivalent file.
83fd337d 294See the "exclude" option above.
8f3a2d54 295
553f9375
WD
296dit(bf(include)) The "include" option allows you to specify a
297space-separated list of patterns which rsync should not exclude. This is
298only superficially equivalent to the client specifying these patterns with
d90338ce 299the bf(--include) option because it applies only on the daemon. This is
553f9375
WD
300useful as it allows you to build up quite complex exclude/include rules.
301Only one "include" option may be specified, but you can use "+" and "-"
302before patterns to switch include/exclude. See the "exclude" option
303above.
cd64343a
DD
304
305dit(bf(include from)) The "include from" option specifies a filename
d90338ce 306on the daemon that contains include patterns, one per line. This is
83fd337d 307only superficially equivalent to the client specifying the
faa82484 308bf(--include-from) option with a equivalent file.
83fd337d 309See the "exclude" option above.
cd64343a 310
c094d932
WD
311dit(bf(incoming chmod)) This option allows you to specify a set of
312comma-separated chmod strings that will affect the permissions of all
313incoming files (files that are being received by the daemon). These
44a8e86d
WD
314changes happen after all other permission calculations, and this will
315even override destination-default and/or existing permissions when the
316client does not specify bf(--perms).
fa3e4a05
WD
317See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
318manpage for information on the format of this string.
c094d932
WD
319
320dit(bf(outgoing chmod)) This option allows you to specify a set of
321comma-separated chmod strings that will affect the permissions of all
322outgoing files (files that are being sent out from the daemon). These
323changes happen first, making the sent permissions appear to be different
2243a935
WD
324than those stored in the filesystem itself. For instance, you could
325disable group write permissions on the server while having it appear to
326be on to the clients.
fa3e4a05
WD
327See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
328manpage for information on the format of this string.
17af842d 329
5d78a102 330dit(bf(auth users)) The "auth users" option specifies a comma and
553f9375 331space-separated list of usernames that will be allowed to connect to
5d78a102
AT
332this module. The usernames do not need to exist on the local
333system. The usernames may also contain shell wildcard characters. If
334"auth users" is set then the client will be challenged to supply a
335username and password to connect to the module. A challenge response
336authentication protocol is used for this exchange. The plain text
9aacb4df 337usernames and passwords are stored in the file specified by the
41059f75
AT
338"secrets file" option. The default is for all users to be able to
339connect without a password (this is called "anonymous rsync").
340
d90338ce 341See also the "CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL
19826af5 342PROGRAM" section in bf(rsync)(1) for information on how handle an
bef49340 343rsyncd.conf-level username that differs from the remote-shell-level
d90338ce 344username when using a remote shell to connect to an rsync daemon.
bef49340 345
41059f75
AT
346dit(bf(secrets file)) The "secrets file" option specifies the name of
347a file that contains the username:password pairs used for
348authenticating this module. This file is only consulted if the "auth
349users" option is specified. The file is line based and contains
350username:password pairs separated by a single colon. Any line starting
351with a hash (#) is considered a comment and is skipped. The passwords
352can contain any characters but be warned that many operating systems
353limit the length of passwords that can be typed at the client end, so
f97c2d4a 354you may find that passwords longer than 8 characters don't work.
41059f75 355
3ca8e68f 356There is no default for the "secrets file" option, you must choose a name
205c27ac
DD
357(such as tt(/etc/rsyncd.secrets)). The file must normally not be readable
358by "other"; see "strict modes".
3ca8e68f 359
f97c2d4a 360dit(bf(strict modes)) The "strict modes" option determines whether or not
3ca8e68f 361the permissions on the secrets file will be checked. If "strict modes" is
58811a0a 362true, then the secrets file must not be readable by any user ID other
3ca8e68f
DD
363than the one that the rsync daemon is running under. If "strict modes" is
364false, the check is not performed. The default is true. This option
365was added to accommodate rsync running on the Windows operating system.
41059f75
AT
366
367dit(bf(hosts allow)) The "hosts allow" option allows you to specify a
368list of patterns that are matched against a connecting clients
369hostname and IP address. If none of the patterns match then the
370connection is rejected.
371
372Each pattern can be in one of five forms:
373
b8a6dae0 374quote(itemization(
61ca7d59
DD
375 it() a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address
376 of the form a:b:c::d:e:f. In this case the incoming machine's IP address
bc2b4963 377 must match exactly.
61ca7d59
DD
378 it() an address/mask in the form ipaddr/n where ipaddr is the IP address
379 and n is the number of one bits in the netmask. All IP addresses which
380 match the masked IP address will be allowed in.
61ca7d59
DD
381 it() an address/mask in the form ipaddr/maskaddr where ipaddr is the
382 IP address and maskaddr is the netmask in dotted decimal notation for IPv4,
383 or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
384 addresses which match the masked IP address will be allowed in.
41059f75 385 it() a hostname. The hostname as determined by a reverse lookup will
5315b793 386 be matched (case insensitive) against the pattern. Only an exact
41059f75 387 match is allowed in.
41059f75
AT
388 it() a hostname pattern using wildcards. These are matched using the
389 same rules as normal unix filename matching. If the pattern matches
5315b793 390 then the client is allowed in.
faa82484 391))
41059f75 392
61ca7d59
DD
393Note IPv6 link-local addresses can have a scope in the address specification:
394
faa82484
WD
395quote(
396tt( fe80::1%link1)nl()
397tt( fe80::%link1/64)nl()
398tt( fe80::%link1/ffff:ffff:ffff:ffff::)nl()
399)
61ca7d59 400
41059f75
AT
401You can also combine "hosts allow" with a separate "hosts deny"
402option. If both options are specified then the "hosts allow" option s
5315b793 403checked first and a match results in the client being able to
41059f75 404connect. The "hosts deny" option is then checked and a match means
f97c2d4a 405that the host is rejected. If the host does not match either the
41059f75
AT
406"hosts allow" or the "hosts deny" patterns then it is allowed to
407connect.
408
409The default is no "hosts allow" option, which means all hosts can connect.
410
de2fd20e 411dit(bf(hosts deny)) The "hosts deny" option allows you to specify a
41059f75
AT
412list of patterns that are matched against a connecting clients
413hostname and IP address. If the pattern matches then the connection is
414rejected. See the "hosts allow" option for more information.
415
416The default is no "hosts deny" option, which means all hosts can connect.
417
cda2ae84 418dit(bf(ignore errors)) The "ignore errors" option tells rsyncd to
d90338ce 419ignore I/O errors on the daemon when deciding whether to run the delete
faa82484 420phase of the transfer. Normally rsync skips the bf(--delete) step if any
ae283632 421I/O errors have occurred in order to prevent disastrous deletion due
58811a0a 422to a temporary resource shortage or other I/O error. In some cases this
cda2ae84 423test is counter productive so you can use this option to turn off this
f97c2d4a 424behavior.
cda2ae84 425
d90338ce 426dit(bf(ignore nonreadable)) This tells the rsync daemon to completely
78043d19
AT
427ignore files that are not readable by the user. This is useful for
428public archives that may have some non-readable files among the
429directories, and the sysadmin doesn't want those files to be seen at all.
430
f97c2d4a 431dit(bf(transfer logging)) The "transfer logging" option enables per-file
81791cfc 432logging of downloads and uploads in a format somewhat similar to that
d90338ce 433used by ftp daemons. The daemon always logs the transfer at the end, so
3b2bebbf
WD
434if a transfer is aborted, no mention will be made in the log file.
435
436If you want to customize the log lines, see the "log format" option.
81791cfc
AT
437
438dit(bf(log format)) The "log format" option allows you to specify the
9e453674
WD
439format used for logging file transfers when transfer logging is enabled.
440The format is a text string containing embedded single-character escape
80a24d52
WD
441sequences prefixed with a percent (%) character. An optional numeric
442field width may also be specified between the percent and the escape
0abe148f 443letter (e.g. "bf(%-50n %8l %07p)").
81791cfc 444
9e453674
WD
445The default log format is "%o %h [%a] %m (%u) %f %l", and a "%t [%p] "
446is always prefixed when using the "log file" option.
447(A perl script that will summarize this default log format is included
448in the rsync source code distribution in the "support" subdirectory:
449rsyncstats.)
450
451The single-character escapes that are understood are as follows:
81791cfc 452
b8a6dae0 453quote(itemization(
aca5500a 454 it() %a the remote IP address
f97c2d4a 455 it() %b the number of bytes actually transferred
aca5500a
WD
456 it() %B the permission bits of the file (e.g. rwxrwxrwt)
457 it() %c the checksum bytes received for this file (only when sending)
458 it() %f the filename (long form on sender; no trailing "/")
459 it() %G the gid of the file (decimal) or "DEFAULT"
460 it() %h the remote host name
527a010f 461 it() %i an itemized list of what is being updated
aca5500a
WD
462 it() %l the length of the file in bytes
463 it() %L the string " -> SYMLINK", " => HARDLINK", or "" (where bf(SYMLINK) or bf(HARDLINK) is a filename)
464 it() %m the module name
465 it() %M the last-modified time of the file
466 it() %n the filename (short form; trailing "/" on dir)
467 it() %o the operation, which is "send", "recv", or "del." (the latter includes the trailing period)
468 it() %p the process ID of this rsync session
469 it() %P the module path
470 it() %t the current date time
471 it() %u the authenticated username or an empty string
472 it() %U the uid of the file (decimal)
faa82484 473))
81791cfc 474
9e453674
WD
475For a list of what the characters mean that are output by "%i", see the
476bf(--itemize-changes) option in the rsync manpage.
527a010f 477
9e453674 478Note that some of the logged output changes when talking with older
80a24d52 479rsync versions. For instance, deleted files were only output as verbose
8ebdc972 480messages prior to rsync 2.6.4.
a85a1514 481
81791cfc 482dit(bf(timeout)) The "timeout" option allows you to override the
58811a0a 483clients choice for I/O timeout for this module. Using this option you
81791cfc
AT
484can ensure that rsync won't wait on a dead client forever. The timeout
485is specified in seconds. A value of zero means no timeout and is the
d90338ce 486default. A good choice for anonymous rsync daemons may be 600 (giving
81791cfc
AT
487a 10 minute timeout).
488
cd8185f2 489dit(bf(refuse options)) The "refuse options" option allows you to
553f9375 490specify a space-separated list of rsync command line options that will
d90338ce 491be refused by your rsync daemon.
1cb0a3ed
WD
492You may specify the full option name, its one-letter abbreviation, or a
493wild-card string that matches multiple options.
9eef8f0b
WD
494For example, this would refuse bf(--checksum) (bf(-c)) and all the various
495delete options:
1cb0a3ed 496
9eef8f0b
WD
497quote(tt( refuse options = c delete))
498
499The reason the above refuses all delete options is that the options imply
500bf(--delete), and implied options are refused just like explicit options.
e1636830
WD
501As an additional safety feature, the refusal of "delete" also refuses
502bf(remove-sent-files) when the daemon is the sender; if you want the latter
503without the former, instead refuse "delete-*" -- that refuses all the
504delete modes without affecting bf(--remove-sent-files).
1cb0a3ed 505
d90338ce 506When an option is refused, the daemon prints an error message and exits.
f97c2d4a
WD
507To prevent all compression when serving files,
508you can use "dont compress = *" (see below)
63f0774f
DD
509instead of "refuse options = compress" to avoid returning an error to a
510client that requests compression.
cd8185f2 511
83fff1aa
AT
512dit(bf(dont compress)) The "dont compress" option allows you to select
513filenames based on wildcard patterns that should not be compressed
f97c2d4a
WD
514when pulling files from the daemon (no analogous option exists to
515govern the pushing of files to a daemon).
516Compression is expensive in terms of CPU usage, so it
83fff1aa 517is usually good to not try to compress files that won't compress well,
f97c2d4a 518such as already compressed files.
83fff1aa 519
553f9375 520The "dont compress" option takes a space-separated list of
83fff1aa
AT
521case-insensitive wildcard patterns. Any source filename matching one
522of the patterns will not be compressed during transfer.
523
34ca58d4
WD
524See the bf(--skip-compress) option in the bf(rsync)(1) manpage for the list
525of file suffixes that are not compressed by default. Specifying a value
526for the bf(dont compress) option changes the default when the daemon is
527the sender.
83fff1aa 528
c20936b8
WD
529dit(bf(pre-xfer exec), bf(post-xfer exec)) You may specify a command to be run
530before and/or after the transfer. If the bf(pre-xfer exec) command fails, the
531transfer is aborted before it begins.
532
37439b36
WD
533The following environment variables will be set, though some are
534specific to the pre-xfer or the post-xfer environment:
c20936b8 535
b8a6dae0 536quote(itemization(
c20936b8
WD
537 it() bf(RSYNC_MODULE_NAME): The name of the module being accessed.
538 it() bf(RSYNC_MODULE_PATH): The path configured for the module.
539 it() bf(RSYNC_HOST_ADDR): The accessing host's IP address.
540 it() bf(RSYNC_HOST_NAME): The accessing host's name.
541 it() bf(RSYNC_USER_NAME): The accessing user's name (empty if no user).
a739128d 542 it() bf(RSYNC_PID): A unique number for this transfer.
37439b36
WD
543 it() bf(RSYNC_REQUEST): (pre-xfer only) The module/path info specified
544 by the user (note that the user can specify multiple source files,
545 so the request can be something like "mod/path1 mod/path2", etc.).
70e98a43 546 it() bf(RSYNC_ARG#): (pre-xfer only) The pre-request arguments are set
fddf529d
WD
547 in these numbered values. RSYNC_ARG0 is always "rsyncd", and the last
548 value contains a single period.
a6333519
WD
549 it() bf(RSYNC_EXIT_STATUS): (post-xfer only) the server side's exit value.
550 This will be 0 for a successful run, a positive value for an error that the
551 server generated, or a -1 if rsync failed to exit properly. Note that an
552 error that occurs on the client side does not currently get sent to the
553 server side, so this is not the final exit status for the whole transfer.
19826af5 554 it() bf(RSYNC_RAW_STATUS): (post-xfer only) the raw exit value from code(waitpid()).
c20936b8
WD
555))
556
557Even though the commands can be associated with a particular module, they
558are run using the permissions of the user that started the daemon (not the
37439b36 559module's uid/gid setting) without any chroot restrictions.
c20936b8 560
41059f75
AT
561enddit()
562
4c3d16be
AT
563manpagesection(AUTHENTICATION STRENGTH)
564
565The authentication protocol used in rsync is a 128 bit MD4 based
2b7e1292
WD
566challenge response system. This is fairly weak protection, though (with
567at least one brute-force hash-finding algorithm publicly available), so
568if you want really top-quality security, then I recommend that you run
569rsync over ssh. (Yes, a future version of rsync will switch over to a
570stronger hashing method.)
4c3d16be 571
d90338ce 572Also note that the rsync daemon protocol does not currently provide any
f39281ae 573encryption of the data that is transferred over the connection. Only
4c3d16be
AT
574authentication is provided. Use ssh as the transport if you want
575encryption.
576
577Future versions of rsync may support SSL for better authentication and
578encryption, but that is still being investigated.
579
41059f75
AT
580manpagesection(EXAMPLES)
581
582A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
e22de162 583tt(/home/ftp) would be:
41059f75
AT
584
585verb(
586[ftp]
e22de162
AT
587 path = /home/ftp
588 comment = ftp export area
41059f75
AT
589)
590
41059f75
AT
591A more sophisticated example would be:
592
faa82484
WD
593verb(
594uid = nobody
595gid = nobody
596use chroot = no
597max connections = 4
598syslog facility = local5
0f621785 599pid file = /var/run/rsyncd.pid
41059f75 600
faa82484 601[ftp]
41059f75
AT
602 path = /var/ftp/pub
603 comment = whole ftp area (approx 6.1 GB)
604
605[sambaftp]
606 path = /var/ftp/pub/samba
607 comment = Samba ftp area (approx 300 MB)
608
609[rsyncftp]
610 path = /var/ftp/pub/rsync
611 comment = rsync ftp area (approx 6 MB)
f97c2d4a 612
41059f75
AT
613[sambawww]
614 path = /public_html/samba
615 comment = Samba WWW pages (approx 240 MB)
616
617[cvs]
618 path = /data/cvs
619 comment = CVS repository (requires authentication)
620 auth users = tridge, susan
621 secrets file = /etc/rsyncd.secrets
622)
623
624The /etc/rsyncd.secrets file would look something like this:
625
faa82484
WD
626quote(
627tt(tridge:mypass)nl()
628tt(susan:herpass)nl()
629)
41059f75
AT
630
631manpagefiles()
632
30e8c8e1 633/etc/rsyncd.conf or rsyncd.conf
41059f75
AT
634
635manpageseealso()
636
b8a6dae0 637bf(rsync)(1)
41059f75
AT
638
639manpagediagnostics()
640
641manpagebugs()
642
41059f75 643Please report bugs! The rsync bug tracking system is online at
9e3c856a 644url(http://rsync.samba.org/)(http://rsync.samba.org/)
41059f75
AT
645
646manpagesection(VERSION)
d90338ce 647
732b3917 648This man page is current for version 3.0.0pre5 of rsync.
41059f75
AT
649
650manpagesection(CREDITS)
651
652rsync is distributed under the GNU public license. See the file
653COPYING for details.
654
655The primary ftp site for rsync is
9e3c856a 656url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
41059f75
AT
657
658A WEB site is available at
9e3c856a 659url(http://rsync.samba.org/)(http://rsync.samba.org/)
41059f75
AT
660
661We would be delighted to hear from you if you like this program.
662
663This program uses the zlib compression library written by Jean-loup
664Gailly and Mark Adler.
665
666manpagesection(THANKS)
667
668Thanks to Warren Stanley for his original idea and patch for the rsync
d90338ce 669daemon. Thanks to Karsten Thygesen for his many suggestions and
f97c2d4a 670documentation!
41059f75
AT
671
672manpageauthor()
673
ae283632
WD
674rsync was written by Andrew Tridgell and Paul Mackerras.
675Many people have later contributed to it.
41059f75 676
ae283632 677Mailing lists for support and development are available at
f97c2d4a 678url(http://lists.samba.org)(lists.samba.org)