123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865 |
- .TH "rsyncd.conf" "5" "23 Sep 2011" "" ""
- .SH "NAME"
- rsyncd.conf \- 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 \(dq\&name = value\(dq\&.
- .PP
- The file is line\-based \-\- 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 \(dq\&continued\(dq\& 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 \(dq\&\fBrsync \-\-daemon\fP\(dq\& 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 \(dq\&/usr/bin/rsync\(dq\& 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
- \(dq\&message of the day\(dq\& 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\(cq\&s
- filesystem to make available in this module. You must specify this parameter
- for each module in \f(CWrsyncd.conf\fP.
- .IP
- It is fine if the path includes internal spaces \-\- they will be retained
- verbatim (which means that you shouldn\(cq\&t try to escape them). If your final
- directory has a trailing space (and this is somehow not something you wish to
- fix), append a trailing slash to the path to avoid losing the trailing
- whitespace.
- .IP
- .IP "\fBuse chroot\fP"
- If \(dq\&use chroot\(dq\& is true, the rsync daemon will chroot
- to the \(dq\&path\(dq\& 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\(cq\&s
- \(dq\&path\(dq\& to indicate the point where the chroot should occur. This allows rsync
- to run in a chroot with a non\-\(dq\&/\(dq\& 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 \(dq\&/var/rsync/./module1\(dq\& will chroot to the
- \(dq\&/var/rsync\(dq\& directory and set the inside\-chroot path to \(dq\&/module1\(dq\&. If you
- had omitted the dot\-dir, the chroot would have used the whole path, and the
- inside\-chroot path would have been \(dq\&/\(dq\&.
- .IP
- When \(dq\&use chroot\(dq\& is false or the inside\-chroot path is not \(dq\&/\(dq\&, rsync will:
- (1) munge symlinks by
- default for security reasons (see \(dq\&munge symlinks\(dq\& for a way to turn this
- off, but only if you trust your users), (2) substitute leading slashes in
- absolute paths with the module\(cq\&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\(cq\&s \(dq\&path\(dq\& dir), and (3) trim \(dq\&..\(dq\& path elements from
- args if rsync believes they would escape the module hierarchy.
- The default for \(dq\&use chroot\(dq\& 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\(cq\&s chroot area, you
- should protect them through your OS\(cq\&s normal user/group or ACL settings (to
- prevent the rsync module\(cq\&s user from being able to change them), and then
- hide them from the user\(cq\&s view via \(dq\&exclude\(dq\& (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 \(dq\&numeric ids\(dq\& 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\(cq\&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 \(dq\&use chroot\(dq\&
- is on and the inside\-chroot path is \(dq\&/\(dq\&, 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 \(dq\&use chroot\(dq\&
- is off, rsync can even be tricked into showing or changing data that
- is outside the module\(cq\&s path (as access\-permissions allow).
- .IP
- The way rsync disables the use of symlinks is to prefix each one with
- the string \(dq\&/rsyncd\-munged/\(dq\&. 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 \(dq\&munge symlinks\(dq\& parameter in a chroot area
- that has an inside\-chroot path of \(dq\&/\(dq\&, you should add \(dq\&/rsyncd\-munged/\(dq\&
- to the exclude setting for the module so that
- a user can\(cq\&t try to create it.
- .IP
- Note: rsync makes no attempt to verify that any pre\-existing symlinks in
- the module\(cq\&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 \(dq\&/rsyncd\-munged/\(dq\& to the start of
- every symlink\(cq\&s value. There is a perl script in the support directory
- of the source code named \(dq\&munge\-symlinks\(dq\& that can be used to add or remove
- this prefix from your symlinks.
- .IP
- When this parameter is disabled on a writable module and \(dq\&use chroot\(dq\& is off
- (or the inside\-chroot path is not \(dq\&/\(dq\&),
- incoming symlinks will be modified to drop a leading slash and to remove \(dq\&..\(dq\&
- path elements that rsync believes will allow a symlink to escape the module\(cq\&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\(cq\&s filenames are stored. If the client uses an \fB\-\-iconv\fP option,
- the daemon will use the value of the \(dq\&charset\(dq\& 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 \(dq\&charset\(dq\& parameter is not set, the \fB\-\-iconv\fP option is
- refused, just as if \(dq\&iconv\(dq\& had been specified via \(dq\&refuse options\(dq\&.
- .IP
- If you wish to force users to always use \fB\-\-iconv\fP for a particular
- module, add \(dq\&no\-iconv\(dq\& to the \(dq\&refuse options\(dq\& 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 \(dq\&lock file\(dq\& parameter.
- .IP
- .IP "\fBlog file\fP"
- When the \(dq\&log file\(dq\& 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\(cq\&t work for chrooted programs. The file is
- opened before
- \f(CWchroot()\fP
- is called, allowing it to be placed outside
- the transfer. If this value is set on a per\-module basis instead of
- globally, the global log will still contain any authorization failures
- or config\-file error messages.
- .IP
- If the daemon fails to open the specified file, it will fall back to
- using syslog and output an error about the failure. (Note that the
- failure to open the specified log file used to be a fatal error.)
- .IP
- .IP "\fBsyslog facility\fP"
- This parameter allows you to
- specify the syslog facility name to use when logging messages from the
- rsync daemon. You may use any standard syslog facility name which is
- defined on your system. Common names are auth, authpriv, cron, daemon,
- ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0,
- local1, local2, local3, local4, local5, local6 and local7. The default
- is daemon. This setting has no effect if the \(dq\&log file\(dq\& setting is a
- non\-empty string (either set in the per\-modules settings, or inherited
- from the global settings).
- .IP
- .IP "\fBmax verbosity\fP"
- This parameter allows you to control
- the maximum amount of verbose information that you\(cq\&ll allow the daemon to
- generate (since the information goes into the log file). The default is 1,
- which allows the client to request one level of verbosity.
- .IP
- .IP "\fBlock file\fP"
- This parameter specifies the file to use to
- support the \(dq\&max connections\(dq\& parameter. The rsync daemon uses record
- locking on this file to ensure that the max connections limit is not
- exceeded for the modules sharing the lock file.
- The default is \f(CW/var/run/rsyncd.lock\fP.
- .IP
- .IP "\fBread only\fP"
- This parameter determines whether clients
- will be able to upload files or not. If \(dq\&read only\(dq\& is true then any
- attempted uploads will fail. If \(dq\&read only\(dq\& is false then uploads will
- be possible if file permissions on the daemon side allow them. The default
- is for all modules to be read only.
- .IP
- .IP "\fBwrite only\fP"
- This parameter determines whether clients
- will be able to download files or not. If \(dq\&write only\(dq\& is true then any
- attempted downloads will fail. If \(dq\&write only\(dq\& is false then downloads
- will be possible if file permissions on the daemon side allow them. The
- default is for this parameter to be disabled.
- .IP
- .IP "\fBlist\fP"
- This parameter determines if this module should be
- listed when the client asks for a listing of available modules. By
- setting this to false you can create hidden modules. The default is
- for modules to be listable.
- .IP
- .IP "\fBuid\fP"
- This parameter specifies the user name or user ID that
- file transfers to and from that module should take place as when the daemon
- was run as root. In combination with the \(dq\&gid\(dq\& parameter this determines what
- file permissions are available. The default is uid \-2, which is normally
- the user \(dq\&nobody\(dq\&.
- .IP
- .IP "\fBgid\fP"
- This parameter specifies the group name or group ID that
- file transfers to and from that module should take place as when the daemon
- was run as root. This complements the \(dq\&uid\(dq\& parameter. The default is gid \-2,
- which is normally the group \(dq\&nobody\(dq\&.
- .IP
- .IP "\fBfake super\fP"
- Setting \(dq\&fake super = yes\(dq\& for a module causes the
- daemon side to behave as if the \fB\-\-fake\-super\fP command\-line option had
- been specified. This allows the full attributes of a file to be stored
- without having to have the daemon actually running as root.
- .IP
- .IP "\fBfilter\fP"
- The daemon has its own filter chain that determines what files
- it will let the client access. This chain is not sent to the client and is
- independent of any filters the client may have specified. Files excluded by
- the daemon filter chain (\fBdaemon\-excluded\fP files) are treated as non\-existent
- if the client tries to pull them, are skipped with an error message if the
- client tries to push them (triggering exit code 23), and are never deleted from
- the module. You can use daemon filters to prevent clients from downloading or
- tampering with private administrative files, such as files you may add to
- support uid/gid name translations.
- .IP
- The daemon filter chain is built from the \(dq\&filter\(dq\&, \(dq\&include from\(dq\&, \(dq\&include\(dq\&,
- \(dq\&exclude from\(dq\&, and \(dq\&exclude\(dq\& parameters, in that order of priority. Anchored
- patterns are anchored at the root of the module. To prevent access to an
- entire subtree, for example, \(dq\&/secret\(dq\&, you \fImust\fP exclude everything in the
- subtree; the easiest way to do this is with a triple\-star pattern like
- \(dq\&/secret/***\(dq\&.
- .IP
- The \(dq\&filter\(dq\& parameter takes a space\-separated list of daemon filter rules,
- though it is smart enough to know not to split a token at an internal space in
- a rule (e.g. \(dq\&\- /foo \- /bar\(dq\& is parsed as two rules). You may specify one or
- more merge\-file rules using the normal syntax. Only one \(dq\&filter\(dq\& parameter can
- apply to a given module in the config file, so put all the rules you want in a
- single parameter. Note that per\-directory merge\-file rules do not provide as
- much protection as global rules, but they can be used to make \fB\-\-delete\fP work
- better during a client download operation if the per\-dir merge files are
- included in the transfer and the client requests that they be used.
- .IP
- .IP "\fBexclude\fP"
- This parameter takes a space\-separated list of daemon
- exclude patterns. As with the client \fB\-\-exclude\fP option, patterns can be
- qualified with \(dq\&\- \(dq\& or \(dq\&+ \(dq\& to explicitly indicate exclude/include. Only one
- \(dq\&exclude\(dq\& parameter can apply to a given module. See the \(dq\&filter\(dq\& parameter
- for a description of how excluded files affect the daemon.
- .IP
- .IP "\fBinclude\fP"
- Use an \(dq\&include\(dq\& to override the effects of the \(dq\&exclude\(dq\&
- parameter. Only one \(dq\&include\(dq\& parameter can apply to a given module. See the
- \(dq\&filter\(dq\& parameter for a description of how excluded files affect the daemon.
- .IP
- .IP "\fBexclude from\fP"
- This parameter specifies the name of a file
- on the daemon that contains daemon exclude patterns, one per line. Only one
- \(dq\&exclude from\(dq\& parameter can apply to a given module; if you have multiple
- exclude\-from files, you can specify them as a merge file in the \(dq\&filter\(dq\&
- parameter. See the \(dq\&filter\(dq\& parameter for a description of how excluded files
- affect the daemon.
- .IP
- .IP "\fBinclude from\fP"
- Analogue of \(dq\&exclude from\(dq\& for a file of daemon include
- patterns. Only one \(dq\&include from\(dq\& parameter can apply to a given module. See
- the \(dq\&filter\(dq\& parameter for a description of how excluded files affect the
- daemon.
- .IP
- .IP "\fBincoming chmod\fP"
- This parameter allows you to specify a set of
- comma\-separated chmod strings that will affect the permissions of all
- incoming files (files that are being received by the daemon). These
- changes happen after all other permission calculations, and this will
- even override destination\-default and/or existing permissions when the
- client does not specify \fB\-\-perms\fP.
- See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
- manpage for information on the format of this string.
- .IP
- .IP "\fBoutgoing chmod\fP"
- This parameter allows you to specify a set of
- comma\-separated chmod strings that will affect the permissions of all
- outgoing files (files that are being sent out from the daemon). These
- changes happen first, making the sent permissions appear to be different
- than those stored in the filesystem itself. For instance, you could
- disable group write permissions on the server while having it appear to
- be on to the clients.
- See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
- manpage for information on the format of this string.
- .IP
- .IP "\fBauth users\fP"
- This parameter specifies a comma and
- space\-separated list of usernames that will be allowed to connect to
- this module. The usernames do not need to exist on the local
- system. The usernames may also contain shell wildcard characters. If
- \(dq\&auth users\(dq\& is set then the client will be challenged to supply a
- username and password to connect to the module. A challenge response
- authentication protocol is used for this exchange. The plain text
- usernames and passwords are stored in the file specified by the
- \(dq\&secrets file\(dq\& parameter. The default is for all users to be able to
- connect without a password (this is called \(dq\&anonymous rsync\(dq\&).
- .IP
- See also the section entitled \(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE
- SHELL CONNECTION\(dq\& in \fBrsync\fP(1) for information on how handle an
- rsyncd.conf\-level username that differs from the remote\-shell\-level
- username when using a remote shell to connect to an rsync daemon.
- .IP
- .IP "\fBsecrets file\fP"
- This parameter specifies the name of
- a file that contains the username:password pairs used for
- authenticating this module. This file is only consulted if the \(dq\&auth
- users\(dq\& parameter is specified. The file is line based and contains
- username:password pairs separated by a single colon. Any line starting
- with a hash (#) is considered a comment and is skipped. The passwords
- can contain any characters but be warned that many operating systems
- limit the length of passwords that can be typed at the client end, so
- you may find that passwords longer than 8 characters don\(cq\&t work.
- .IP
- There is no default for the \(dq\&secrets file\(dq\& parameter, you must choose a name
- (such as \f(CW/etc/rsyncd.secrets\fP). The file must normally not be readable
- by \(dq\&other\(dq\&; see \(dq\&strict modes\(dq\&.
- .IP
- .IP "\fBstrict modes\fP"
- This parameter determines whether or not
- the permissions on the secrets file will be checked. If \(dq\&strict modes\(dq\& is
- true, then the secrets file must not be readable by any user ID other
- than the one that the rsync daemon is running under. If \(dq\&strict modes\(dq\& is
- false, the check is not performed. The default is true. This parameter
- was added to accommodate rsync running on the Windows operating system.
- .IP
- .IP "\fBhosts allow\fP"
- This parameter allows you to specify a
- list of patterns that are matched against a connecting clients
- hostname and IP address. If none of the patterns match then the
- connection is rejected.
- .IP
- Each pattern can be in one of five forms:
- .IP
- .RS
- .IP o
- a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address
- of the form a:b:c::d:e:f. In this case the incoming machine\(cq\&s IP address
- must match exactly.
- .IP o
- an address/mask in the form ipaddr/n where ipaddr is the IP address
- and n is the number of one bits in the netmask. All IP addresses which
- match the masked IP address will be allowed in.
- .IP o
- an address/mask in the form ipaddr/maskaddr where ipaddr is the
- IP address and maskaddr is the netmask in dotted decimal notation for IPv4,
- or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
- addresses which match the masked IP address will be allowed in.
- .IP o
- a hostname. The hostname as determined by a reverse lookup will
- be matched (case insensitive) against the pattern. Only an exact
- match is allowed in.
- .IP o
- a hostname pattern using wildcards. These are matched using the
- same rules as normal unix filename matching. If the pattern matches
- then the client is allowed in.
- .RE
- .IP
- Note IPv6 link\-local addresses can have a scope in the address specification:
- .IP
- .RS
- \f(CW fe80::1%link1\fP
- .br
- \f(CW fe80::%link1/64\fP
- .br
- \f(CW fe80::%link1/ffff:ffff:ffff:ffff::\fP
- .br
- .RE
- .IP
- You can also combine \(dq\&hosts allow\(dq\& with a separate \(dq\&hosts deny\(dq\&
- parameter. If both parameters are specified then the \(dq\&hosts allow\(dq\& parameter is
- checked first and a match results in the client being able to
- connect. The \(dq\&hosts deny\(dq\& parameter is then checked and a match means
- that the host is rejected. If the host does not match either the
- \(dq\&hosts allow\(dq\& or the \(dq\&hosts deny\(dq\& patterns then it is allowed to
- connect.
- .IP
- The default is no \(dq\&hosts allow\(dq\& parameter, which means all hosts can connect.
- .IP
- .IP "\fBhosts deny\fP"
- This parameter allows you to specify a
- list of patterns that are matched against a connecting clients
- hostname and IP address. If the pattern matches then the connection is
- rejected. See the \(dq\&hosts allow\(dq\& parameter for more information.
- .IP
- The default is no \(dq\&hosts deny\(dq\& parameter, which means all hosts can connect.
- .IP
- .IP "\fBignore errors\fP"
- This parameter tells rsyncd to
- ignore I/O errors on the daemon when deciding whether to run the delete
- phase of the transfer. Normally rsync skips the \fB\-\-delete\fP step if any
- I/O errors have occurred in order to prevent disastrous deletion due
- to a temporary resource shortage or other I/O error. In some cases this
- test is counter productive so you can use this parameter to turn off this
- behavior.
- .IP
- .IP "\fBignore nonreadable\fP"
- This tells the rsync daemon to completely
- ignore files that are not readable by the user. This is useful for
- public archives that may have some non\-readable files among the
- directories, and the sysadmin doesn\(cq\&t want those files to be seen at all.
- .IP
- .IP "\fBtransfer logging\fP"
- This parameter enables per\-file
- logging of downloads and uploads in a format somewhat similar to that
- used by ftp daemons. The daemon always logs the transfer at the end, so
- if a transfer is aborted, no mention will be made in the log file.
- .IP
- If you want to customize the log lines, see the \(dq\&log format\(dq\& parameter.
- .IP
- .IP "\fBlog format\fP"
- This parameter allows you to specify the
- format used for logging file transfers when transfer logging is enabled.
- The format is a text string containing embedded single\-character escape
- sequences prefixed with a percent (%) character. An optional numeric
- field width may also be specified between the percent and the escape
- letter (e.g. \(dq\&\fB%\-50n %8l %07p\fP\(dq\&).
- .IP
- The default log format is \(dq\&%o %h [%a] %m (%u) %f %l\(dq\&, and a \(dq\&%t [%p] \(dq\&
- is always prefixed when using the \(dq\&log file\(dq\& parameter.
- (A perl script that will summarize this default log format is included
- in the rsync source code distribution in the \(dq\&support\(dq\& subdirectory:
- rsyncstats.)
- .IP
- The single\-character escapes that are understood are as follows:
- .IP
- .RS
- .IP o
- %a the remote IP address
- .IP o
- %b the number of bytes actually transferred
- .IP o
- %B the permission bits of the file (e.g. rwxrwxrwt)
- .IP o
- %c the total size of the block checksums received for the basis file (only when sending)
- .IP o
- %f the filename (long form on sender; no trailing \(dq\&/\(dq\&)
- .IP o
- %G the gid of the file (decimal) or \(dq\&DEFAULT\(dq\&
- .IP o
- %h the remote host name
- .IP o
- %i an itemized list of what is being updated
- .IP o
- %l the length of the file in bytes
- .IP o
- %L the string \(dq\& \-> SYMLINK\(dq\&, \(dq\& => HARDLINK\(dq\&, or \(dq\&\(dq\& (where \fBSYMLINK\fP or \fBHARDLINK\fP is a filename)
- .IP o
- %m the module name
- .IP o
- %M the last\-modified time of the file
- .IP o
- %n the filename (short form; trailing \(dq\&/\(dq\& on dir)
- .IP o
- %o the operation, which is \(dq\&send\(dq\&, \(dq\&recv\(dq\&, or \(dq\&del.\(dq\& (the latter includes the trailing period)
- .IP o
- %p the process ID of this rsync session
- .IP o
- %P the module path
- .IP o
- %t the current date time
- .IP o
- %u the authenticated username or an empty string
- .IP o
- %U the uid of the file (decimal)
- .RE
- .IP
- For a list of what the characters mean that are output by \(dq\&%i\(dq\&, see the
- \fB\-\-itemize\-changes\fP option in the rsync manpage.
- .IP
- Note that some of the logged output changes when talking with older
- rsync versions. For instance, deleted files were only output as verbose
- messages prior to rsync 2.6.4.
- .IP
- .IP "\fBtimeout\fP"
- This parameter allows you to override the
- clients choice for I/O timeout for this module. Using this parameter you
- can ensure that rsync won\(cq\&t wait on a dead client forever. The timeout
- is specified in seconds. A value of zero means no timeout and is the
- default. A good choice for anonymous rsync daemons may be 600 (giving
- a 10 minute timeout).
- .IP
- .IP "\fBrefuse options\fP"
- This parameter allows you to
- specify a space\-separated list of rsync command line options that will
- be refused by your rsync daemon.
- You may specify the full option name, its one\-letter abbreviation, or a
- wild\-card string that matches multiple options.
- For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various
- delete options:
- .IP
- .RS
- \f(CW refuse options = c delete\fP
- .RE
- .IP
- The reason the above refuses all delete options is that the options imply
- \fB\-\-delete\fP, and implied options are refused just like explicit options.
- As an additional safety feature, the refusal of \(dq\&delete\(dq\& also refuses
- \fBremove\-source\-files\fP when the daemon is the sender; if you want the latter
- without the former, instead refuse \(dq\&delete\-*\(dq\& \-\- that refuses all the
- delete modes without affecting \fB\-\-remove\-source\-files\fP.
- .IP
- When an option is refused, the daemon prints an error message and exits.
- To prevent all compression when serving files,
- you can use \(dq\&dont compress = *\(dq\& (see below)
- instead of \(dq\&refuse options = compress\(dq\& to avoid returning an error to a
- client that requests compression.
- .IP
- .IP "\fBdont compress\fP"
- This parameter allows you to select
- filenames based on wildcard patterns that should not be compressed
- when pulling files from the daemon (no analogous parameter exists to
- govern the pushing of files to a daemon).
- Compression is expensive in terms of CPU usage, so it
- is usually good to not try to compress files that won\(cq\&t compress well,
- such as already compressed files.
- .IP
- The \(dq\&dont compress\(dq\& parameter takes a space\-separated list of
- case\-insensitive wildcard patterns. Any source filename matching one
- of the patterns will not be compressed during transfer.
- .IP
- See the \fB\-\-skip\-compress\fP parameter in the \fBrsync\fP(1) manpage for the list
- of file suffixes that are not compressed by default. Specifying a value
- for the \(dq\&dont compress\(dq\& parameter changes the default when the daemon is
- the sender.
- .IP
- .IP "\fBpre\-xfer exec\fP, \fBpost\-xfer exec\fP"
- You may specify a command to be run
- before and/or after the transfer. If the \fBpre\-xfer exec\fP command fails, the
- transfer is aborted before it begins.
- .IP
- The following environment variables will be set, though some are
- specific to the pre\-xfer or the post\-xfer environment:
- .IP
- .RS
- .IP o
- \fBRSYNC_MODULE_NAME\fP: The name of the module being accessed.
- .IP o
- \fBRSYNC_MODULE_PATH\fP: The path configured for the module.
- .IP o
- \fBRSYNC_HOST_ADDR\fP: The accessing host\(cq\&s IP address.
- .IP o
- \fBRSYNC_HOST_NAME\fP: The accessing host\(cq\&s name.
- .IP o
- \fBRSYNC_USER_NAME\fP: The accessing user\(cq\&s name (empty if no user).
- .IP o
- \fBRSYNC_PID\fP: A unique number for this transfer.
- .IP o
- \fBRSYNC_REQUEST\fP: (pre\-xfer only) The module/path info specified
- by the user (note that the user can specify multiple source files,
- so the request can be something like \(dq\&mod/path1 mod/path2\(dq\&, etc.).
- .IP o
- \fBRSYNC_ARG#\fP: (pre\-xfer only) The pre\-request arguments are set
- in these numbered values. RSYNC_ARG0 is always \(dq\&rsyncd\(dq\&, and the last
- value contains a single period.
- .IP o
- \fBRSYNC_EXIT_STATUS\fP: (post\-xfer only) the server side\(cq\&s exit value.
- This will be 0 for a successful run, a positive value for an error that the
- server generated, or a \-1 if rsync failed to exit properly. Note that an
- error that occurs on the client side does not currently get sent to the
- server side, so this is not the final exit status for the whole transfer.
- .IP o
- \fBRSYNC_RAW_STATUS\fP: (post\-xfer only) the raw exit value from
- \f(CWwaitpid()\fP
- \&.
- .RE
- .IP
- Even though the commands can be associated with a particular module, they
- are run using the permissions of the user that started the daemon (not the
- module\(cq\&s uid/gid setting) without any chroot restrictions.
- .IP
- .SH "AUTHENTICATION STRENGTH"
- .PP
- The authentication protocol used in rsync is a 128 bit MD4 based
- challenge response system. This is fairly weak protection, though (with
- at least one brute\-force hash\-finding algorithm publicly available), so
- if you want really top\-quality security, then I recommend that you run
- rsync over ssh. (Yes, a future version of rsync will switch over to a
- stronger hashing method.)
- .PP
- Also note that the rsync daemon protocol does not currently provide any
- encryption of the data that is transferred over the connection. Only
- authentication is provided. Use ssh as the transport if you want
- encryption.
- .PP
- Future versions of rsync may support SSL for better authentication and
- encryption, but that is still being investigated.
- .PP
- .SH "EXAMPLES"
- .PP
- A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
- \f(CW/home/ftp\fP would be:
- .PP
- .nf
- [ftp]
- path = /home/ftp
- comment = ftp export area
- .fi
- .PP
- A more sophisticated example would be:
- .PP
- .nf
- uid = nobody
- gid = nobody
- use chroot = yes
- max connections = 4
- syslog facility = local5
- pid file = /var/run/rsyncd.pid
- [ftp]
- path = /var/ftp/./pub
- comment = whole ftp area (approx 6.1 GB)
- [sambaftp]
- path = /var/ftp/./pub/samba
- comment = Samba ftp area (approx 300 MB)
- [rsyncftp]
- path = /var/ftp/./pub/rsync
- comment = rsync ftp area (approx 6 MB)
- [sambawww]
- path = /public_html/samba
- comment = Samba WWW pages (approx 240 MB)
- [cvs]
- path = /data/cvs
- comment = CVS repository (requires authentication)
- auth users = tridge, susan
- secrets file = /etc/rsyncd.secrets
- .fi
- .PP
- The /etc/rsyncd.secrets file would look something like this:
- .PP
- .RS
- \f(CWtridge:mypass\fP
- .br
- \f(CWsusan:herpass\fP
- .br
- .RE
- .PP
- .SH "FILES"
- .PP
- /etc/rsyncd.conf or rsyncd.conf
- .PP
- .SH "SEE ALSO"
- .PP
- \fBrsync\fP(1)
- .PP
- .SH "DIAGNOSTICS"
- .PP
- .SH "BUGS"
- .PP
- Please report bugs! The rsync bug tracking system is online at
- http://rsync.samba.org/
- .PP
- .SH "VERSION"
- .PP
- This man page is current for version 3.0.9 of rsync.
- .PP
- .SH "CREDITS"
- .PP
- rsync is distributed under the GNU public license. See the file
- COPYING for details.
- .PP
- The primary ftp site for rsync is
- ftp://rsync.samba.org/pub/rsync.
- .PP
- A WEB site is available at
- http://rsync.samba.org/
- .PP
- We would be delighted to hear from you if you like this program.
- .PP
- This program uses the zlib compression library written by Jean\-loup
- Gailly and Mark Adler.
- .PP
- .SH "THANKS"
- .PP
- Thanks to Warren Stanley for his original idea and patch for the rsync
- daemon. Thanks to Karsten Thygesen for his many suggestions and
- documentation!
- .PP
- .SH "AUTHOR"
- .PP
- rsync was written by Andrew Tridgell and Paul Mackerras.
- Many people have later contributed to it.
- .PP
- Mailing lists for support and development are available at
- http://lists.samba.org
|