rsyncd.conf.5

Rsync 3.0.5 source code

.TH "rsyncd.conf" "5" "28 Dec 2008" "" ""
.SH "NAME"
rsyncd.conf \(em configuration file for rsync in daemon mode
.SH "SYNOPSIS"

.PP 
rsyncd.conf
.PP 
.SH "DESCRIPTION"

.PP 
The rsyncd.conf file is the runtime configuration file for rsync when
run as an rsync daemon.
.PP 
The rsyncd.conf file controls authentication, access, logging and
available modules.
.PP 
.SH "FILE FORMAT"

.PP 
The file consists of modules and parameters. A module begins with the
name of the module in square brackets and continues until the next
module begins. Modules contain parameters of the form \(lqname = value\(rq.
.PP 
The file is line-based \(em that is, each newline-terminated line represents
either a comment, a module name or a parameter.
.PP 
Only the first equals sign in a parameter is significant. Whitespace before
or after the first equals sign is discarded. Leading, trailing and internal
whitespace in module and parameter names is irrelevant. Leading and
trailing whitespace in a parameter value is discarded. Internal whitespace
within a parameter value is retained verbatim.
.PP 
Any line beginning with a hash (#) is ignored, as are lines containing
only whitespace.
.PP 
Any line ending in a \e is \(lqcontinued\(rq on the next line in the
customary UNIX fashion.
.PP 
The values following the equals sign in parameters are all either a string
(no quotes needed) or a boolean, which may be given as yes/no, 0/1 or
true/false. Case is not significant in boolean values, but is preserved
in string values.
.PP 
.SH "LAUNCHING THE RSYNC DAEMON"

.PP 
The rsync daemon is launched by specifying the \fB\-\-daemon\fP option to
rsync.
.PP 
The daemon must run with root privileges if you wish to use chroot, to
bind to a port numbered under 1024 (as is the default 873), or to set
file ownership.  Otherwise, it must just have permission to read and
write the appropriate data, log, and lock files.
.PP 
You can launch it either via inetd, as a stand-alone daemon, or from
an rsync client via a remote shell.  If run as a stand-alone daemon then
just run the command \(lq\fBrsync \-\-daemon\fP\(rq from a suitable startup script.
.PP 
When run via inetd you should add a line like this to /etc/services:
.PP 
.nf 
  rsync           873/tcp
.fi 

.PP 
and a single line something like this to /etc/inetd.conf:
.PP 
.nf 
  rsync   stream  tcp     nowait  root   /usr/bin/rsync rsyncd \-\-daemon
.fi 

.PP 
Replace \(lq/usr/bin/rsync\(rq with the path to where you have rsync installed on
your system.  You will then need to send inetd a HUP signal to tell it to
reread its config file.
.PP 
Note that you should \fBnot\fP send the rsync daemon a HUP signal to force
it to reread the \f(CWrsyncd.conf\fP file. The file is re-read on each client
connection.
.PP 
.SH "GLOBAL PARAMETERS"

.PP 
The first parameters in the file (before a [module] header) are the
global parameters.
.PP 
You may also include any module parameters in the global part of the
config file in which case the supplied value will override the
default for that parameter.
.PP 
.IP "\fBmotd file\fP"
This parameter allows you to specify a
\(lqmessage of the day\(rq to display to clients on each connect. This
usually contains site information and any legal notices. The default
is no motd file.
.IP 
.IP "\fBpid file\fP"
This parameter tells the rsync daemon to write
its process ID to that file.  If the file already exists, the rsync
daemon will abort rather than overwrite the file.
.IP 
.IP "\fBport\fP"
You can override the default port the daemon will listen on
by specifying this value (defaults to 873).  This is ignored if the daemon
is being run by inetd, and is superseded by the \fB\-\-port\fP command-line option.
.IP 
.IP "\fBaddress\fP"
You can override the default IP address the daemon
will listen on by specifying this value.  This is ignored if the daemon is
being run by inetd, and is superseded by the \fB\-\-address\fP command-line option.
.IP 
.IP "\fBsocket options\fP"
This parameter can provide endless fun for people
who like to tune their systems to the utmost degree. You can set all
sorts of socket options which may make transfers faster (or
slower!). Read the man page for the 
\f(CWsetsockopt()\fP
system call for
details on some of the options you may be able to set. By default no
special socket options are set.  These settings can also be specified
via the \fB\-\-sockopts\fP command-line option.
.IP 
.SH "MODULE PARAMETERS"

.PP 
After the global parameters you should define a number of modules, each
module exports a directory tree as a symbolic name. Modules are
exported by specifying a module name in square brackets [module]
followed by the parameters for that module.
The module name cannot contain a slash or a closing square bracket.  If the
name contains whitespace, each internal sequence of whitespace will be
changed into a single space, while leading or trailing whitespace will be
discarded.
.PP 
.IP "\fBcomment\fP"
This parameter specifies a description string
that is displayed next to the module name when clients obtain a list
of available modules. The default is no comment.
.IP 
.IP "\fBpath\fP"
This parameter specifies the directory in the daemon's
filesystem to make available in this module.  You must specify this parameter
for each module in \f(CWrsyncd.conf\fP.
.IP 
.IP "\fBuse chroot\fP"
If \(lquse chroot\(rq is true, the rsync daemon will chroot
to the \(lqpath\(rq before starting the file transfer with the client.  This has
the advantage of extra protection against possible implementation security
holes, but it has the disadvantages of requiring super-user privileges,
of not being able to follow symbolic links that are either absolute or outside
of the new root path, and of complicating the preservation of users and groups
by name (see below).
.IP 
As an additional safety feature, you can specify a dot-dir in the module's
\(lqpath\(rq to indicate the point where the chroot should occur.  This allows rsync
to run in a chroot with a non\-"/\(rq path for the top of the transfer hierarchy.
Doing this guards against unintended library loading (since those absolute
paths will not be inside the transfer hierarchy unless you have used an unwise
pathname), and lets you setup libraries for the chroot that are outside of the
transfer.  For example, specifying \(lq/var/rsync/./module1\(rq will chroot to the
\(lq/var/rsync\(rq directory and set the inside-chroot path to \(lq/module1\(rq.  If you
had omitted the dot-dir, the chroot would have used the whole path, and the
inside-chroot path would have been \(lq/\(rq.
.IP 
When \(lquse chroot\(rq is false or the inside-chroot path is not \(lq/\(rq, rsync will:
(1) munge symlinks by
default for security reasons (see \(lqmunge symlinks\(rq for a way to turn this
off, but only if you trust your users), (2) substitute leading slashes in
absolute paths with the module's path (so that options such as
\fB\-\-backup\-dir\fP, \fB\-\-compare\-dest\fP, etc. interpret an absolute path as
rooted in the module's \(lqpath\(rq dir), and (3) trim \(lq..\(rq path elements from
args if rsync believes they would escape the module hierarchy.
The default for \(lquse chroot\(rq is true, and is the safer choice (especially
if the module is not read-only).
.IP 
When this parameter is enabled, rsync will not attempt to map users and groups
by name (by default), but instead copy IDs as though \fB\-\-numeric\-ids\fP had
been specified.  In order to enable name-mapping, rsync needs to be able to
use the standard library functions for looking up names and IDs (i.e.
\f(CWgetpwuid()\fP
, 
\f(CWgetgrgid()\fP
, 
\f(CWgetpwname()\fP
, and 
\f(CWgetgrnam()\fP
).
This means the rsync
process in the chroot hierarchy will need to have access to the resources
used by these library functions (traditionally /etc/passwd and
/etc/group, but perhaps additional dynamic libraries as well).
.IP 
If you copy the necessary resources into the module's chroot area, you
should protect them through your OS's normal user/group or ACL settings (to
prevent the rsync module's user from being able to change them), and then
hide them from the user's view via \(lqexclude\(rq (see how in the discussion of
that parameter).  At that point it will be safe to enable the mapping of users
and groups by name using the \(lqnumeric ids\(rq daemon parameter (see below).
.IP 
Note also that you are free to setup custom user/group information in the
chroot area that is different from your normal system.  For example, you
could abbreviate the list of users and groups.
.IP 
.IP "\fBnumeric ids\fP"
Enabling this parameter disables the mapping
of users and groups by name for the current daemon module.  This prevents
the daemon from trying to load any user/group-related files or libraries.
This enabling makes the transfer behave as if the client had passed
the \fB\-\-numeric\-ids\fP command-line option.  By default, this parameter is
enabled for chroot modules and disabled for non-chroot modules.
.IP 
A chroot-enabled module should not have this parameter enabled unless you've
taken steps to ensure that the module has the necessary resources it needs
to translate names, and that it is not possible for a user to change those
resources.
.IP 
.IP "\fBmunge symlinks\fP"
This parameter tells rsync to modify
all incoming symlinks in a way that makes them unusable but recoverable
(see below).  This should help protect your files from user trickery when
your daemon module is writable.  The default is disabled when \(lquse chroot\(rq
is on and the inside-chroot path is \(lq/\(rq, otherwise it is enabled.
.IP 
If you disable this parameter on a daemon that is not read-only, there
are tricks that a user can play with uploaded symlinks to access
daemon-excluded items (if your module has any), and, if \(lquse chroot\(rq
is off, rsync can even be tricked into showing or changing data that
is outside the module's path (as access-permissions allow).
.IP 
The way rsync disables the use of symlinks is to prefix each one with
the string \(lq/rsyncd-munged/\(rq.  This prevents the links from being used
as long as that directory does not exist.  When this parameter is enabled,
rsync will refuse to run if that path is a directory or a symlink to
a directory.  When using the \(lqmunge symlinks\(rq parameter in a chroot area
that has an inside-chroot path of \(lq/\(rq, you should add \(lq/rsyncd-munged/\(rq
to the exclude setting for the module so that
a user can't try to create it.
.IP 
Note:  rsync makes no attempt to verify that any pre-existing symlinks in
the module's hierarchy are as safe as you want them to be (unless, of
course, it just copied in the whole hierarchy).  If you setup an rsync
daemon on a new area or locally add symlinks, you can manually protect your
symlinks from being abused by prefixing \(lq/rsyncd-munged/\(rq to the start of
every symlink's value.  There is a perl script in the support directory
of the source code named \(lqmunge-symlinks\(rq that can be used to add or remove
this prefix from your symlinks.
.IP 
When this parameter is disabled on a writable module and \(lquse chroot\(rq is off
(or the inside-chroot path is not \(lq/\(rq),
incoming symlinks will be modified to drop a leading slash and to remove \(lq..\(rq
path elements that rsync believes will allow a symlink to escape the module's
hierarchy.  There are tricky ways to work around this, though, so you had
better trust your users if you choose this combination of parameters.
.IP 
.IP "\fBcharset\fP"
This specifies the name of the character set in which the
module's filenames are stored.  If the client uses an \fB\-\-iconv\fP option,
the daemon will use the value of the \(lqcharset\(rq parameter regardless of the
character set the client actually passed.  This allows the daemon to
support charset conversion in a chroot module without extra files in the
chroot area, and also ensures that name-translation is done in a consistent
manner.  If the \(lqcharset\(rq parameter is not set, the \fB\-\-iconv\fP option is
refused, just as if \(lqiconv\(rq had been specified via \(lqrefuse options\(rq.
.IP 
If you wish to force users to always use \fB\-\-iconv\fP for a particular
module, add \(lqno-iconv\(rq to the \(lqrefuse options\(rq parameter.  Keep in mind
that this will restrict access to your module to very new rsync clients.
.IP 
.IP "\fBmax connections\fP"
This parameter allows you to
specify the maximum number of simultaneous connections you will allow.
Any clients connecting when the maximum has been reached will receive a
message telling them to try later.  The default is 0, which means no limit.
A negative value disables the module.
See also the \(lqlock file\(rq parameter.
.IP 
.IP "\fBlog file\fP"
When the \(lqlog file\(rq parameter is set to a non-empty
string, the rsync daemon will log messages to the indicated file rather
than using syslog. This is particularly useful on systems (such as AIX)
where 
\f(CWsyslog()\fP
doesn't work for chrooted programs.  The file is
opened before 
\f(CWchroot()\fP
is called, allowing it to be placed outside