mailto(rsync-bugs@samba.org)
-manpage(rsyncd.conf)(5)(17 May 2008)()()
+manpage(rsyncd.conf)(5)(29 Jun 2008)()()
manpagename(rsyncd.conf)(configuration file for rsync in daemon mode)
manpagesynopsis()
config file in which case the supplied value will override the
default for that parameter.
+You may use references to environment variables in the values of parameters.
+String parameters will have %VAR% references expanded as late as possible (when
+the string is used in the program), allowing for the use of variables that
+rsync sets at connection time, such as RSYNC_USER_NAME. Non-string parameters
+(such as true/false settings) are expanded when read from the config file. If
+a variable does not exist in the environment, or if a sequence of characters is
+not a valid reference (such as an un-paired percent sign), the raw characters
+are passed through unchanged. This helps with backward compatibility and
+safety (e.g. expanding a non-existent %VAR% to an empty string in a path could
+result in a very unsafe path). The safest way to insert a literal % into a
+value is to use %%.
+
startdit()
dit(bf(motd file)) This parameter allows you to specify a
"message of the day" to display to clients on each connect. This
usually contains site information and any legal notices. The default
is no motd file.
+This can be overridden by the bf(--dparam=motdfile=FILE)
+command-line option when starting the daemon.
dit(bf(pid file)) 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.
+This can be overridden by the bf(--dparam=pidfile=FILE)
+command-line option when starting the daemon.
dit(bf(port)) You can override the default port the daemon will listen on
by specifying this value (defaults to 873). This is ignored if the daemon
sorts of socket options which may make transfers faster (or
slower!). Read the man page for the code(setsockopt()) 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 are superseded by the
-bf(--sockopts) command-line option.
+special socket options are set. These settings can also be specified
+via the bf(--sockopts) command-line option.
-enddit()
+dit(bf(listen backlog)) You can override the default backlog value when the
+daemon listens for connections. It defaults to 5.
+enddit()
manpagesection(MODULE PARAMETERS)
changed into a single space, while leading or trailing whitespace will be
discarded.
+As with GLOBAL PARAMETERS, you may use references to environment variables in
+the values of parameters. See the GLOBAL PARAMETERS section for more details.
+
startdit()
dit(bf(comment)) This parameter specifies a description string
filesystem to make available in this module. You must specify this parameter
for each module in tt(rsyncd.conf).
+You may base the path's value off of an environment variable by surrounding
+the variable name with percent signs. You can even reference a variable
+that is set by rsync when the user connects.
+For example, this would use the authorizing user's name in the path:
+
+verb( path = /home/%RSYNC_USER_NAME% )
+
dit(bf(use chroot)) If "use chroot" is true, the rsync daemon will chroot
to the "path" before starting the file transfer with the client. This has
the advantage of extra protection against possible implementation security
resources.
dit(bf(munge symlinks)) 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
+all symlinks in the same way as the (non-daemon-affecting)
+bf(--munge-links) command-line option (using a method described below).
+This should help protect your files from user trickery when
your daemon module is writable. The default is disabled when "use chroot"
is on and the inside-chroot path is "/", otherwise it is enabled.
a user can't try to create it.
Note: rsync makes no attempt to verify that any pre-existing symlinks in
-the hierarchy are as safe as you want them to be. If you setup an rsync
+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 "/rsyncd-munged/" to the start of
every symlink's value. There is a perl script in the support directory
globally, the global log will still contain any authorization failures
or config-file error messages.
-If the daemon fails to open to specified file, it will fall back to
+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.)
+This setting can be overridden by using the bf(--log-file=FILE) or
+bf(--dparam=logfile=FILE) command-line options. The former overrides
+all the log-file parameters of the daemon and all module settings.
+The latter sets the daemon's log file and the default for all the
+modules, which still allows modules to override the default setting.
+
dit(bf(syslog facility)) 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
be possible if file permissions on the daemon side allow them. The default
is for all modules to be read only.
+Note that "auth users" can override this setting on a per-user basis.
+
dit(bf(write only)) This parameter determines whether clients
will be able to download files or not. If "write only" is true then any
attempted downloads will fail. If "write only" 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.
-dit(bf(list)) 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.
+dit(bf(list)) This parameter determines whether this module is
+listed when the client asks for a listing of available modules. In addition,
+if this is false, the daemon will pretend the module does not exist
+when a client denied by "hosts allow" or "hosts deny" attempts to access it.
+Realize that if "reverse lookup" is disabled globally but enabled for the
+module, the resulting reverse lookup to a potentially client-controlled DNS
+server may still reveal to the client that it hit an existing module.
+The default is for modules to be listable.
dit(bf(uid)) 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 "gid" parameter this determines what
-file permissions are available. The default is uid -2, which is normally
-the user "nobody".
-
-dit(bf(gid)) 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 "uid" parameter. The default is gid -2,
-which is normally the group "nobody".
+file permissions are available. The default when run by a super-user is to
+switch to the system's "nobody" user. The default for a non-super-user is to
+not try to change the user. See also the "gid" parameter.
+
+The RSYNC_USER_NAME environment variable may be used to request that rsync run
+as the authorizing user. For example, if you want a rsync to run as the same
+user that was received for the rsync authentication, this setup is useful:
+
+verb( uid = %RSYNC_USER_NAME%
+ gid = * )
+
+dit(bf(gid)) This parameter specifies one or more group names/IDs that will be
+used when accessing the module. The first one will be the default group, and
+any extra ones be set as supplemental groups. You may also specify a "*" as
+the first gid in the list, which will be replaced by all the normal groups for
+the transfer's user (see "uid"). The default when run by a super-user is to
+switch to your OS's "nobody" (or perhaps "nogroup") group with no other
+supplementary groups. The default for a non-super-user is to not change any
+group attributes (and indeed, your OS may not allow a non-super-user to try to
+change their group settings).
dit(bf(fake super)) Setting "fake super = yes" for a module causes the
-daemon side to behave as if the bf(--fake-user) command-line option had
+daemon side to behave as if the bf(--fake-super) 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.
See the description of the bf(--chmod) rsync option and the bf(chmod)(1)
manpage for information on the format of this string.
-dit(bf(auth users)) This parameter specifies a comma and
-space-separated list of usernames that will be allowed to connect to
+dit(bf(auth users)) This parameter specifies a comma and/or space-separated
+list of authorization rules. In its simplest form, you list the 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
+system. The rules may contain shell wildcard characters that will be matched
+against the username provided by the client for authentication. If
"auth users" 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
"secrets file" parameter. The default is for all users to be able to
connect without a password (this is called "anonymous rsync").
-See also the "CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL
-PROGRAM" section in bf(rsync)(1) for information on how handle an
+In addition to username matching, you can specify groupname matching via a '@'
+prefix. When using groupname matching, the authenticating username must be a
+real user on the system, or it will be assumed to be a member of no groups.
+For example, specifying "@rsync" will match the authenticating user if the
+named user is a member of the rsync group.
+
+Finally, options may be specified after a colon (:). The options allow you to
+"deny" a user or a group, set the access to "ro" (read-only), or set the access
+to "rw" (read/write). Setting an auth-rule-specific ro/rw setting overrides
+the module's "read only" setting.
+
+Be sure to put the rules in the order you want them to be matched, because the
+checking stops at the first matching user or group, and that is the only auth
+that is checked. For example:
+
+verb( auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam )
+
+In the above rule, user joe will be denied access no matter what. Any user
+that is in the group "guest" is also denied access. The user "admin" gets
+access in read/write mode, but only if the admin user is not in group "guest"
+(because the admin user-matching rule would never be reached if the user is in
+group "guest"). Any other user who is in group "rsync" will get read-only
+access. Finally, users susan, joe, and sam get the ro/rw setting of the
+module, but only if the user didn't match an earlier group-matching rule.
+
+See the description of the secrets file for how you can have per-user passwords
+as well as per-group passwords. It also explains how a user can authenticate
+using their user password or (when applicable) a group password, depending on
+what rule is being authenticated.
+
+See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE
+SHELL CONNECTION" in bf(rsync)(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.
-dit(bf(secrets file)) 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 "auth
-users" 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't work.
+dit(bf(secrets file)) This parameter specifies the name of a file that contains
+the username:password and/or @groupname:password pairs used for authenticating
+this module. This file is only consulted if the "auth users" parameter is
+specified. The file is line-based and contains one name:password pair per
+line. Any line has a hash (#) as the very first character on the line 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't work.
+
+The use of group-specific lines are only relevant when the module is being
+authorized using a matching "@groupname" rule. When that happens, the user
+can be authorized via either their "username:password" line or the
+"@groupname:password" line for the group that triggered the authentication.
+
+It is up to you what kind of password entries you want to include, either
+users, groups, or both. The use of group rules in "auth users" does not
+require that you specify a group password if you do not want to use shared
+passwords.
There is no default for the "secrets file" parameter, you must choose a name
(such as tt(/etc/rsyncd.secrets)). The file must normally not be readable
-by "other"; see "strict modes".
+by "other"; see "strict modes". If the file is not found or is rejected, no
+logins for a "user auth" module will be possible.
dit(bf(strict modes)) This parameter determines whether or not
the permissions on the secrets file will be checked. If "strict modes" is
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.
- it() 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.
- it() 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.
+ it() a hostname pattern using wildcards. If the hostname of the connecting IP
+ (as determined by a reverse lookup) matches the wildcarded name (using the
+ same rules as normal unix filename matching), the client is allowed in. This
+ only works if "reverse lookup" is enabled (the default).
+ it() a hostname. A plain hostname is matched against the reverse DNS of the
+ connecting IP (if "reverse lookup" is enabled), and/or the IP of the given
+ hostname is matched against the connecting IP (if "forward lookup" is
+ enabled, as it is by default). Any match will be allowed in.
))
Note IPv6 link-local addresses can have a scope in the address specification:
The default is no "hosts deny" parameter, which means all hosts can connect.
+dit(bf(reverse lookup)) Controls whether the daemon performs a reverse lookup
+on the client's IP address to determine its hostname, which is used for
+"hosts allow"/"hosts deny" checks and the "%h" log escape. This is enabled by
+default, but you may wish to disable it to save time if you know the lookup will
+not return a useful result, in which case the daemon will use the name
+"UNDETERMINED" instead.
+
+If this parameter is enabled globally (even by default), rsync performs the
+lookup as soon as a client connects, so disabling it for a module will not
+avoid the lookup. Thus, you probably want to disable it globally and then
+enable it for modules that need the information.
+
+dit(bf(forward lookup)) Controls whether the daemon performs a forward lookup
+on any hostname specified in an hosts allow/deny setting. By default this is
+enabled, allowing the use of an explicit hostname that would not be returned
+by reverse DNS of the connecting IP.
+
dit(bf(ignore errors)) 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 bf(--delete) step if any
sequences prefixed with a percent (%) character. An optional numeric
field width may also be specified between the percent and the escape
letter (e.g. "bf(%-50n %8l %07p)").
+In addition, one or more apostrophes may be specified prior to a numerical
+escape to indicate that the numerical value should be made more human-readable.
+The 3 supported levels are the same as for the bf(--human-readable)
+command-line option, though the default is for human-readability to be off.
+Each added apostrophe increases the level (e.g. "bf(%''l %'b %f)").
The default log format is "%o %h [%a] %m (%u) %f %l", and a "%t [%p] "
is always prefixed when using the "log file" parameter.
it() %a the remote IP address
it() %b the number of bytes actually transferred
it() %B the permission bits of the file (e.g. rwxrwxrwt)
- it() %c the checksum bytes received for this file (only when sending)
+ it() %c the total size of the block checksums received for the basis file (only when sending)
+ it() %C the full-file MD5 checksum if bf(--checksum) is enabled or a file was transferred (only for protocol 30 or above).
it() %f the filename (long form on sender; no trailing "/")
it() %G the gid of the file (decimal) or "DEFAULT"
it() %h the remote host name
enddit()
+manpagesection(CONFIG DIRECTIVES)
+
+There are currently two config directives available that allow a config file to
+incorporate the contents of other files: bf(&include) and bf(&merge). Both
+allow a reference to either a file or a directory. They differ in how
+segregated the file's contents are considered to be.
+
+The bf(&include) directive treats each file as more distinct, with each one
+inheriting the defaults of the parent file, starting the parameter parsing
+as globals/defaults, and leaving the defaults unchanged for the parsing of
+the rest of the parent file.
+
+The bf(&merge) directive, on the other hand, treats the file's contents as
+if it were simply inserted in place of the directive, and thus it can set
+parameters in a module started in another file, can affect the defaults for
+other files, etc.
+
+When an bf(&include) or bf(&merge) directive refers to a directory, it will read
+in all the bf(*.conf) or bf(*.inc) files (respectively) that are contained inside
+that directory (without any
+recursive scanning), with the files sorted into alpha order. So, if you have a
+directory named "rsyncd.d" with the files "foo.conf", "bar.conf", and
+"baz.conf" inside it, this directive:
+
+verb( &include /path/rsyncd.d )
+
+would be the same as this set of directives:
+
+verb( &include /path/rsyncd.d/bar.conf
+ &include /path/rsyncd.d/baz.conf
+ &include /path/rsyncd.d/foo.conf )
+
+except that it adjusts as files are added and removed from the directory.
+
+The advantage of the bf(&include) directive is that you can define one or more
+modules in a separate file without worrying about unintended side-effects
+between the self-contained module files.
+
+The advantage of the bf(&merge) directive is that you can load config snippets
+that can be included into multiple module definitions, and you can also set
+global values that will affect connections (such as bf(motd file)), or globals
+that will affect other include files.
+
+For example, this is a useful /etc/rsyncd.conf file:
+
+verb( port = 873
+ log file = /var/log/rsync.log
+ pid file = /var/lock/rsync.lock
+
+ &merge /etc/rsyncd.d
+ &include /etc/rsyncd.d )
+
+This would merge any /etc/rsyncd.d/*.inc files (for global values that should
+stay in effect), and then include any /etc/rsyncd.d/*.conf files (defining
+modules without any global-value cross-talk).
+
manpagesection(AUTHENTICATION STRENGTH)
The authentication protocol used in rsync is a 128 bit MD4 based
manpagesection(VERSION)
-This man page is current for version 3.0.3pre2 of rsync.
+This man page is current for version 3.0.3 of rsync.
manpagesection(CREDITS)
git.samba.org / rsync.git / blobdiff