Move var declaration for older C compilers.
[rsync.git] / rsyncd.conf.yo
index d2d8f45647383f50b8d31f53308dae07c9b964c6..49d252260af392287a9d1c87868bd650dad431f2 100644 (file)
@@ -87,8 +87,8 @@ 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).  Anyone that needs to insert a literal % string
-into a value should use %%.
+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
@@ -120,6 +120,9 @@ 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 bf(--sockopts) command-line option.
 
+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)
@@ -144,10 +147,12 @@ of available modules. The default is no comment.
 
 dit(bf(path)) 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 tt(rsyncd.conf).  You may base the path's value off
-of an environment variable, even one that is set by rsync when the user
-connects.  For example, this would use the authorizing user's name in the
-path:
+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% )
 
@@ -318,6 +323,8 @@ attempted uploads will fail. If "read only" 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.
 
+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
@@ -358,7 +365,7 @@ 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.
 
@@ -430,10 +437,12 @@ be on to the clients.
 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
@@ -441,24 +450,65 @@ usernames and passwords are stored in the file specified by the
 "secrets file" parameter. The default is for all users to be able to
 connect without a password (this is called "anonymous rsync").
 
+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
@@ -485,13 +535,14 @@ quote(itemization(
   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.  This only works if "reverse lookup" is enabled
-  (the default).
-  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:
@@ -531,6 +582,11 @@ 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
@@ -700,7 +756,8 @@ 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) files contained inside that directory (without any
+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:
@@ -717,17 +774,25 @@ 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.  For instance, this is a useful
-/etc/rsyncd.conf file:
+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 )
 
-The advantage of the bf(&merge) directive is that you can load config snippets
-that can be included into multiple module definitions.
+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)