Annotation of embedaddon/rsync/rsyncd.conf.5, revision 1.1
1.1 ! misho 1: .TH "rsyncd.conf" "5" "23 Sep 2011" "" ""
! 2: .SH "NAME"
! 3: rsyncd.conf \- configuration file for rsync in daemon mode
! 4: .SH "SYNOPSIS"
! 5:
! 6: .PP
! 7: rsyncd.conf
! 8: .PP
! 9: .SH "DESCRIPTION"
! 10:
! 11: .PP
! 12: The rsyncd.conf file is the runtime configuration file for rsync when
! 13: run as an rsync daemon.
! 14: .PP
! 15: The rsyncd.conf file controls authentication, access, logging and
! 16: available modules.
! 17: .PP
! 18: .SH "FILE FORMAT"
! 19:
! 20: .PP
! 21: The file consists of modules and parameters. A module begins with the
! 22: name of the module in square brackets and continues until the next
! 23: module begins. Modules contain parameters of the form \(dq\&name = value\(dq\&.
! 24: .PP
! 25: The file is line\-based \-\- that is, each newline\-terminated line represents
! 26: either a comment, a module name or a parameter.
! 27: .PP
! 28: Only the first equals sign in a parameter is significant. Whitespace before
! 29: or after the first equals sign is discarded. Leading, trailing and internal
! 30: whitespace in module and parameter names is irrelevant. Leading and
! 31: trailing whitespace in a parameter value is discarded. Internal whitespace
! 32: within a parameter value is retained verbatim.
! 33: .PP
! 34: Any line beginning with a hash (#) is ignored, as are lines containing
! 35: only whitespace.
! 36: .PP
! 37: Any line ending in a \e is \(dq\&continued\(dq\& on the next line in the
! 38: customary UNIX fashion.
! 39: .PP
! 40: The values following the equals sign in parameters are all either a string
! 41: (no quotes needed) or a boolean, which may be given as yes/no, 0/1 or
! 42: true/false. Case is not significant in boolean values, but is preserved
! 43: in string values.
! 44: .PP
! 45: .SH "LAUNCHING THE RSYNC DAEMON"
! 46:
! 47: .PP
! 48: The rsync daemon is launched by specifying the \fB\-\-daemon\fP option to
! 49: rsync.
! 50: .PP
! 51: The daemon must run with root privileges if you wish to use chroot, to
! 52: bind to a port numbered under 1024 (as is the default 873), or to set
! 53: file ownership. Otherwise, it must just have permission to read and
! 54: write the appropriate data, log, and lock files.
! 55: .PP
! 56: You can launch it either via inetd, as a stand\-alone daemon, or from
! 57: an rsync client via a remote shell. If run as a stand\-alone daemon then
! 58: just run the command \(dq\&\fBrsync \-\-daemon\fP\(dq\& from a suitable startup script.
! 59: .PP
! 60: When run via inetd you should add a line like this to /etc/services:
! 61: .PP
! 62: .nf
! 63: rsync 873/tcp
! 64: .fi
! 65:
! 66: .PP
! 67: and a single line something like this to /etc/inetd.conf:
! 68: .PP
! 69: .nf
! 70: rsync stream tcp nowait root /usr/bin/rsync rsyncd \-\-daemon
! 71: .fi
! 72:
! 73: .PP
! 74: Replace \(dq\&/usr/bin/rsync\(dq\& with the path to where you have rsync installed on
! 75: your system. You will then need to send inetd a HUP signal to tell it to
! 76: reread its config file.
! 77: .PP
! 78: Note that you should \fBnot\fP send the rsync daemon a HUP signal to force
! 79: it to reread the \f(CWrsyncd.conf\fP file. The file is re\-read on each client
! 80: connection.
! 81: .PP
! 82: .SH "GLOBAL PARAMETERS"
! 83:
! 84: .PP
! 85: The first parameters in the file (before a [module] header) are the
! 86: global parameters.
! 87: .PP
! 88: You may also include any module parameters in the global part of the
! 89: config file in which case the supplied value will override the
! 90: default for that parameter.
! 91: .PP
! 92: .IP "\fBmotd file\fP"
! 93: This parameter allows you to specify a
! 94: \(dq\&message of the day\(dq\& to display to clients on each connect. This
! 95: usually contains site information and any legal notices. The default
! 96: is no motd file.
! 97: .IP
! 98: .IP "\fBpid file\fP"
! 99: This parameter tells the rsync daemon to write
! 100: its process ID to that file. If the file already exists, the rsync
! 101: daemon will abort rather than overwrite the file.
! 102: .IP
! 103: .IP "\fBport\fP"
! 104: You can override the default port the daemon will listen on
! 105: by specifying this value (defaults to 873). This is ignored if the daemon
! 106: is being run by inetd, and is superseded by the \fB\-\-port\fP command\-line option.
! 107: .IP
! 108: .IP "\fBaddress\fP"
! 109: You can override the default IP address the daemon
! 110: will listen on by specifying this value. This is ignored if the daemon is
! 111: being run by inetd, and is superseded by the \fB\-\-address\fP command\-line option.
! 112: .IP
! 113: .IP "\fBsocket options\fP"
! 114: This parameter can provide endless fun for people
! 115: who like to tune their systems to the utmost degree. You can set all
! 116: sorts of socket options which may make transfers faster (or
! 117: slower!). Read the man page for the
! 118: \f(CWsetsockopt()\fP
! 119: system call for
! 120: details on some of the options you may be able to set. By default no
! 121: special socket options are set. These settings can also be specified
! 122: via the \fB\-\-sockopts\fP command\-line option.
! 123: .IP
! 124: .SH "MODULE PARAMETERS"
! 125:
! 126: .PP
! 127: After the global parameters you should define a number of modules, each
! 128: module exports a directory tree as a symbolic name. Modules are
! 129: exported by specifying a module name in square brackets [module]
! 130: followed by the parameters for that module.
! 131: The module name cannot contain a slash or a closing square bracket. If the
! 132: name contains whitespace, each internal sequence of whitespace will be
! 133: changed into a single space, while leading or trailing whitespace will be
! 134: discarded.
! 135: .PP
! 136: .IP "\fBcomment\fP"
! 137: This parameter specifies a description string
! 138: that is displayed next to the module name when clients obtain a list
! 139: of available modules. The default is no comment.
! 140: .IP
! 141: .IP "\fBpath\fP"
! 142: This parameter specifies the directory in the daemon\(cq\&s
! 143: filesystem to make available in this module. You must specify this parameter
! 144: for each module in \f(CWrsyncd.conf\fP.
! 145: .IP
! 146: It is fine if the path includes internal spaces \-\- they will be retained
! 147: verbatim (which means that you shouldn\(cq\&t try to escape them). If your final
! 148: directory has a trailing space (and this is somehow not something you wish to
! 149: fix), append a trailing slash to the path to avoid losing the trailing
! 150: whitespace.
! 151: .IP
! 152: .IP "\fBuse chroot\fP"
! 153: If \(dq\&use chroot\(dq\& is true, the rsync daemon will chroot
! 154: to the \(dq\&path\(dq\& before starting the file transfer with the client. This has
! 155: the advantage of extra protection against possible implementation security
! 156: holes, but it has the disadvantages of requiring super\-user privileges,
! 157: of not being able to follow symbolic links that are either absolute or outside
! 158: of the new root path, and of complicating the preservation of users and groups
! 159: by name (see below).
! 160: .IP
! 161: As an additional safety feature, you can specify a dot\-dir in the module\(cq\&s
! 162: \(dq\&path\(dq\& to indicate the point where the chroot should occur. This allows rsync
! 163: to run in a chroot with a non\-\(dq\&/\(dq\& path for the top of the transfer hierarchy.
! 164: Doing this guards against unintended library loading (since those absolute
! 165: paths will not be inside the transfer hierarchy unless you have used an unwise
! 166: pathname), and lets you setup libraries for the chroot that are outside of the
! 167: transfer. For example, specifying \(dq\&/var/rsync/./module1\(dq\& will chroot to the
! 168: \(dq\&/var/rsync\(dq\& directory and set the inside\-chroot path to \(dq\&/module1\(dq\&. If you
! 169: had omitted the dot\-dir, the chroot would have used the whole path, and the
! 170: inside\-chroot path would have been \(dq\&/\(dq\&.
! 171: .IP
! 172: When \(dq\&use chroot\(dq\& is false or the inside\-chroot path is not \(dq\&/\(dq\&, rsync will:
! 173: (1) munge symlinks by
! 174: default for security reasons (see \(dq\&munge symlinks\(dq\& for a way to turn this
! 175: off, but only if you trust your users), (2) substitute leading slashes in
! 176: absolute paths with the module\(cq\&s path (so that options such as
! 177: \fB\-\-backup\-dir\fP, \fB\-\-compare\-dest\fP, etc. interpret an absolute path as
! 178: rooted in the module\(cq\&s \(dq\&path\(dq\& dir), and (3) trim \(dq\&..\(dq\& path elements from
! 179: args if rsync believes they would escape the module hierarchy.
! 180: The default for \(dq\&use chroot\(dq\& is true, and is the safer choice (especially
! 181: if the module is not read\-only).
! 182: .IP
! 183: When this parameter is enabled, rsync will not attempt to map users and groups
! 184: by name (by default), but instead copy IDs as though \fB\-\-numeric\-ids\fP had
! 185: been specified. In order to enable name\-mapping, rsync needs to be able to
! 186: use the standard library functions for looking up names and IDs (i.e.
! 187: \f(CWgetpwuid()\fP
! 188: ,
! 189: \f(CWgetgrgid()\fP
! 190: ,
! 191: \f(CWgetpwname()\fP
! 192: , and
! 193: \f(CWgetgrnam()\fP
! 194: ).
! 195: This means the rsync
! 196: process in the chroot hierarchy will need to have access to the resources
! 197: used by these library functions (traditionally /etc/passwd and
! 198: /etc/group, but perhaps additional dynamic libraries as well).
! 199: .IP
! 200: If you copy the necessary resources into the module\(cq\&s chroot area, you
! 201: should protect them through your OS\(cq\&s normal user/group or ACL settings (to
! 202: prevent the rsync module\(cq\&s user from being able to change them), and then
! 203: hide them from the user\(cq\&s view via \(dq\&exclude\(dq\& (see how in the discussion of
! 204: that parameter). At that point it will be safe to enable the mapping of users
! 205: and groups by name using the \(dq\&numeric ids\(dq\& daemon parameter (see below).
! 206: .IP
! 207: Note also that you are free to setup custom user/group information in the
! 208: chroot area that is different from your normal system. For example, you
! 209: could abbreviate the list of users and groups.
! 210: .IP
! 211: .IP "\fBnumeric ids\fP"
! 212: Enabling this parameter disables the mapping
! 213: of users and groups by name for the current daemon module. This prevents
! 214: the daemon from trying to load any user/group\-related files or libraries.
! 215: This enabling makes the transfer behave as if the client had passed
! 216: the \fB\-\-numeric\-ids\fP command\-line option. By default, this parameter is
! 217: enabled for chroot modules and disabled for non\-chroot modules.
! 218: .IP
! 219: A chroot\-enabled module should not have this parameter enabled unless you\(cq\&ve
! 220: taken steps to ensure that the module has the necessary resources it needs
! 221: to translate names, and that it is not possible for a user to change those
! 222: resources.
! 223: .IP
! 224: .IP "\fBmunge symlinks\fP"
! 225: This parameter tells rsync to modify
! 226: all incoming symlinks in a way that makes them unusable but recoverable
! 227: (see below). This should help protect your files from user trickery when
! 228: your daemon module is writable. The default is disabled when \(dq\&use chroot\(dq\&
! 229: is on and the inside\-chroot path is \(dq\&/\(dq\&, otherwise it is enabled.
! 230: .IP
! 231: If you disable this parameter on a daemon that is not read\-only, there
! 232: are tricks that a user can play with uploaded symlinks to access
! 233: daemon\-excluded items (if your module has any), and, if \(dq\&use chroot\(dq\&
! 234: is off, rsync can even be tricked into showing or changing data that
! 235: is outside the module\(cq\&s path (as access\-permissions allow).
! 236: .IP
! 237: The way rsync disables the use of symlinks is to prefix each one with
! 238: the string \(dq\&/rsyncd\-munged/\(dq\&. This prevents the links from being used
! 239: as long as that directory does not exist. When this parameter is enabled,
! 240: rsync will refuse to run if that path is a directory or a symlink to
! 241: a directory. When using the \(dq\&munge symlinks\(dq\& parameter in a chroot area
! 242: that has an inside\-chroot path of \(dq\&/\(dq\&, you should add \(dq\&/rsyncd\-munged/\(dq\&
! 243: to the exclude setting for the module so that
! 244: a user can\(cq\&t try to create it.
! 245: .IP
! 246: Note: rsync makes no attempt to verify that any pre\-existing symlinks in
! 247: the module\(cq\&s hierarchy are as safe as you want them to be (unless, of
! 248: course, it just copied in the whole hierarchy). If you setup an rsync
! 249: daemon on a new area or locally add symlinks, you can manually protect your
! 250: symlinks from being abused by prefixing \(dq\&/rsyncd\-munged/\(dq\& to the start of
! 251: every symlink\(cq\&s value. There is a perl script in the support directory
! 252: of the source code named \(dq\&munge\-symlinks\(dq\& that can be used to add or remove
! 253: this prefix from your symlinks.
! 254: .IP
! 255: When this parameter is disabled on a writable module and \(dq\&use chroot\(dq\& is off
! 256: (or the inside\-chroot path is not \(dq\&/\(dq\&),
! 257: incoming symlinks will be modified to drop a leading slash and to remove \(dq\&..\(dq\&
! 258: path elements that rsync believes will allow a symlink to escape the module\(cq\&s
! 259: hierarchy. There are tricky ways to work around this, though, so you had
! 260: better trust your users if you choose this combination of parameters.
! 261: .IP
! 262: .IP "\fBcharset\fP"
! 263: This specifies the name of the character set in which the
! 264: module\(cq\&s filenames are stored. If the client uses an \fB\-\-iconv\fP option,
! 265: the daemon will use the value of the \(dq\&charset\(dq\& parameter regardless of the
! 266: character set the client actually passed. This allows the daemon to
! 267: support charset conversion in a chroot module without extra files in the
! 268: chroot area, and also ensures that name\-translation is done in a consistent
! 269: manner. If the \(dq\&charset\(dq\& parameter is not set, the \fB\-\-iconv\fP option is
! 270: refused, just as if \(dq\&iconv\(dq\& had been specified via \(dq\&refuse options\(dq\&.
! 271: .IP
! 272: If you wish to force users to always use \fB\-\-iconv\fP for a particular
! 273: module, add \(dq\&no\-iconv\(dq\& to the \(dq\&refuse options\(dq\& parameter. Keep in mind
! 274: that this will restrict access to your module to very new rsync clients.
! 275: .IP
! 276: .IP "\fBmax connections\fP"
! 277: This parameter allows you to
! 278: specify the maximum number of simultaneous connections you will allow.
! 279: Any clients connecting when the maximum has been reached will receive a
! 280: message telling them to try later. The default is 0, which means no limit.
! 281: A negative value disables the module.
! 282: See also the \(dq\&lock file\(dq\& parameter.
! 283: .IP
! 284: .IP "\fBlog file\fP"
! 285: When the \(dq\&log file\(dq\& parameter is set to a non\-empty
! 286: string, the rsync daemon will log messages to the indicated file rather
! 287: than using syslog. This is particularly useful on systems (such as AIX)
! 288: where
! 289: \f(CWsyslog()\fP
! 290: doesn\(cq\&t work for chrooted programs. The file is
! 291: opened before
! 292: \f(CWchroot()\fP
! 293: is called, allowing it to be placed outside
! 294: the transfer. If this value is set on a per\-module basis instead of
! 295: globally, the global log will still contain any authorization failures
! 296: or config\-file error messages.
! 297: .IP
! 298: If the daemon fails to open the specified file, it will fall back to
! 299: using syslog and output an error about the failure. (Note that the
! 300: failure to open the specified log file used to be a fatal error.)
! 301: .IP
! 302: .IP "\fBsyslog facility\fP"
! 303: This parameter allows you to
! 304: specify the syslog facility name to use when logging messages from the
! 305: rsync daemon. You may use any standard syslog facility name which is
! 306: defined on your system. Common names are auth, authpriv, cron, daemon,
! 307: ftp, kern, lpr, mail, news, security, syslog, user, uucp, local0,
! 308: local1, local2, local3, local4, local5, local6 and local7. The default
! 309: is daemon. This setting has no effect if the \(dq\&log file\(dq\& setting is a
! 310: non\-empty string (either set in the per\-modules settings, or inherited
! 311: from the global settings).
! 312: .IP
! 313: .IP "\fBmax verbosity\fP"
! 314: This parameter allows you to control
! 315: the maximum amount of verbose information that you\(cq\&ll allow the daemon to
! 316: generate (since the information goes into the log file). The default is 1,
! 317: which allows the client to request one level of verbosity.
! 318: .IP
! 319: .IP "\fBlock file\fP"
! 320: This parameter specifies the file to use to
! 321: support the \(dq\&max connections\(dq\& parameter. The rsync daemon uses record
! 322: locking on this file to ensure that the max connections limit is not
! 323: exceeded for the modules sharing the lock file.
! 324: The default is \f(CW/var/run/rsyncd.lock\fP.
! 325: .IP
! 326: .IP "\fBread only\fP"
! 327: This parameter determines whether clients
! 328: will be able to upload files or not. If \(dq\&read only\(dq\& is true then any
! 329: attempted uploads will fail. If \(dq\&read only\(dq\& is false then uploads will
! 330: be possible if file permissions on the daemon side allow them. The default
! 331: is for all modules to be read only.
! 332: .IP
! 333: .IP "\fBwrite only\fP"
! 334: This parameter determines whether clients
! 335: will be able to download files or not. If \(dq\&write only\(dq\& is true then any
! 336: attempted downloads will fail. If \(dq\&write only\(dq\& is false then downloads
! 337: will be possible if file permissions on the daemon side allow them. The
! 338: default is for this parameter to be disabled.
! 339: .IP
! 340: .IP "\fBlist\fP"
! 341: This parameter determines if this module should be
! 342: listed when the client asks for a listing of available modules. By
! 343: setting this to false you can create hidden modules. The default is
! 344: for modules to be listable.
! 345: .IP
! 346: .IP "\fBuid\fP"
! 347: This parameter specifies the user name or user ID that
! 348: file transfers to and from that module should take place as when the daemon
! 349: was run as root. In combination with the \(dq\&gid\(dq\& parameter this determines what
! 350: file permissions are available. The default is uid \-2, which is normally
! 351: the user \(dq\&nobody\(dq\&.
! 352: .IP
! 353: .IP "\fBgid\fP"
! 354: This parameter specifies the group name or group ID that
! 355: file transfers to and from that module should take place as when the daemon
! 356: was run as root. This complements the \(dq\&uid\(dq\& parameter. The default is gid \-2,
! 357: which is normally the group \(dq\&nobody\(dq\&.
! 358: .IP
! 359: .IP "\fBfake super\fP"
! 360: Setting \(dq\&fake super = yes\(dq\& for a module causes the
! 361: daemon side to behave as if the \fB\-\-fake\-super\fP command\-line option had
! 362: been specified. This allows the full attributes of a file to be stored
! 363: without having to have the daemon actually running as root.
! 364: .IP
! 365: .IP "\fBfilter\fP"
! 366: The daemon has its own filter chain that determines what files
! 367: it will let the client access. This chain is not sent to the client and is
! 368: independent of any filters the client may have specified. Files excluded by
! 369: the daemon filter chain (\fBdaemon\-excluded\fP files) are treated as non\-existent
! 370: if the client tries to pull them, are skipped with an error message if the
! 371: client tries to push them (triggering exit code 23), and are never deleted from
! 372: the module. You can use daemon filters to prevent clients from downloading or
! 373: tampering with private administrative files, such as files you may add to
! 374: support uid/gid name translations.
! 375: .IP
! 376: The daemon filter chain is built from the \(dq\&filter\(dq\&, \(dq\&include from\(dq\&, \(dq\&include\(dq\&,
! 377: \(dq\&exclude from\(dq\&, and \(dq\&exclude\(dq\& parameters, in that order of priority. Anchored
! 378: patterns are anchored at the root of the module. To prevent access to an
! 379: entire subtree, for example, \(dq\&/secret\(dq\&, you \fImust\fP exclude everything in the
! 380: subtree; the easiest way to do this is with a triple\-star pattern like
! 381: \(dq\&/secret/***\(dq\&.
! 382: .IP
! 383: The \(dq\&filter\(dq\& parameter takes a space\-separated list of daemon filter rules,
! 384: though it is smart enough to know not to split a token at an internal space in
! 385: a rule (e.g. \(dq\&\- /foo \- /bar\(dq\& is parsed as two rules). You may specify one or
! 386: more merge\-file rules using the normal syntax. Only one \(dq\&filter\(dq\& parameter can
! 387: apply to a given module in the config file, so put all the rules you want in a
! 388: single parameter. Note that per\-directory merge\-file rules do not provide as
! 389: much protection as global rules, but they can be used to make \fB\-\-delete\fP work
! 390: better during a client download operation if the per\-dir merge files are
! 391: included in the transfer and the client requests that they be used.
! 392: .IP
! 393: .IP "\fBexclude\fP"
! 394: This parameter takes a space\-separated list of daemon
! 395: exclude patterns. As with the client \fB\-\-exclude\fP option, patterns can be
! 396: qualified with \(dq\&\- \(dq\& or \(dq\&+ \(dq\& to explicitly indicate exclude/include. Only one
! 397: \(dq\&exclude\(dq\& parameter can apply to a given module. See the \(dq\&filter\(dq\& parameter
! 398: for a description of how excluded files affect the daemon.
! 399: .IP
! 400: .IP "\fBinclude\fP"
! 401: Use an \(dq\&include\(dq\& to override the effects of the \(dq\&exclude\(dq\&
! 402: parameter. Only one \(dq\&include\(dq\& parameter can apply to a given module. See the
! 403: \(dq\&filter\(dq\& parameter for a description of how excluded files affect the daemon.
! 404: .IP
! 405: .IP "\fBexclude from\fP"
! 406: This parameter specifies the name of a file
! 407: on the daemon that contains daemon exclude patterns, one per line. Only one
! 408: \(dq\&exclude from\(dq\& parameter can apply to a given module; if you have multiple
! 409: exclude\-from files, you can specify them as a merge file in the \(dq\&filter\(dq\&
! 410: parameter. See the \(dq\&filter\(dq\& parameter for a description of how excluded files
! 411: affect the daemon.
! 412: .IP
! 413: .IP "\fBinclude from\fP"
! 414: Analogue of \(dq\&exclude from\(dq\& for a file of daemon include
! 415: patterns. Only one \(dq\&include from\(dq\& parameter can apply to a given module. See
! 416: the \(dq\&filter\(dq\& parameter for a description of how excluded files affect the
! 417: daemon.
! 418: .IP
! 419: .IP "\fBincoming chmod\fP"
! 420: This parameter allows you to specify a set of
! 421: comma\-separated chmod strings that will affect the permissions of all
! 422: incoming files (files that are being received by the daemon). These
! 423: changes happen after all other permission calculations, and this will
! 424: even override destination\-default and/or existing permissions when the
! 425: client does not specify \fB\-\-perms\fP.
! 426: See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
! 427: manpage for information on the format of this string.
! 428: .IP
! 429: .IP "\fBoutgoing chmod\fP"
! 430: This parameter allows you to specify a set of
! 431: comma\-separated chmod strings that will affect the permissions of all
! 432: outgoing files (files that are being sent out from the daemon). These
! 433: changes happen first, making the sent permissions appear to be different
! 434: than those stored in the filesystem itself. For instance, you could
! 435: disable group write permissions on the server while having it appear to
! 436: be on to the clients.
! 437: See the description of the \fB\-\-chmod\fP rsync option and the \fBchmod\fP(1)
! 438: manpage for information on the format of this string.
! 439: .IP
! 440: .IP "\fBauth users\fP"
! 441: This parameter specifies a comma and
! 442: space\-separated list of usernames that will be allowed to connect to
! 443: this module. The usernames do not need to exist on the local
! 444: system. The usernames may also contain shell wildcard characters. If
! 445: \(dq\&auth users\(dq\& is set then the client will be challenged to supply a
! 446: username and password to connect to the module. A challenge response
! 447: authentication protocol is used for this exchange. The plain text
! 448: usernames and passwords are stored in the file specified by the
! 449: \(dq\&secrets file\(dq\& parameter. The default is for all users to be able to
! 450: connect without a password (this is called \(dq\&anonymous rsync\(dq\&).
! 451: .IP
! 452: See also the section entitled \(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE
! 453: SHELL CONNECTION\(dq\& in \fBrsync\fP(1) for information on how handle an
! 454: rsyncd.conf\-level username that differs from the remote\-shell\-level
! 455: username when using a remote shell to connect to an rsync daemon.
! 456: .IP
! 457: .IP "\fBsecrets file\fP"
! 458: This parameter specifies the name of
! 459: a file that contains the username:password pairs used for
! 460: authenticating this module. This file is only consulted if the \(dq\&auth
! 461: users\(dq\& parameter is specified. The file is line based and contains
! 462: username:password pairs separated by a single colon. Any line starting
! 463: with a hash (#) is considered a comment and is skipped. The passwords
! 464: can contain any characters but be warned that many operating systems
! 465: limit the length of passwords that can be typed at the client end, so
! 466: you may find that passwords longer than 8 characters don\(cq\&t work.
! 467: .IP
! 468: There is no default for the \(dq\&secrets file\(dq\& parameter, you must choose a name
! 469: (such as \f(CW/etc/rsyncd.secrets\fP). The file must normally not be readable
! 470: by \(dq\&other\(dq\&; see \(dq\&strict modes\(dq\&.
! 471: .IP
! 472: .IP "\fBstrict modes\fP"
! 473: This parameter determines whether or not
! 474: the permissions on the secrets file will be checked. If \(dq\&strict modes\(dq\& is
! 475: true, then the secrets file must not be readable by any user ID other
! 476: than the one that the rsync daemon is running under. If \(dq\&strict modes\(dq\& is
! 477: false, the check is not performed. The default is true. This parameter
! 478: was added to accommodate rsync running on the Windows operating system.
! 479: .IP
! 480: .IP "\fBhosts allow\fP"
! 481: This parameter allows you to specify a
! 482: list of patterns that are matched against a connecting clients
! 483: hostname and IP address. If none of the patterns match then the
! 484: connection is rejected.
! 485: .IP
! 486: Each pattern can be in one of five forms:
! 487: .IP
! 488: .RS
! 489: .IP o
! 490: a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address
! 491: of the form a:b:c::d:e:f. In this case the incoming machine\(cq\&s IP address
! 492: must match exactly.
! 493: .IP o
! 494: an address/mask in the form ipaddr/n where ipaddr is the IP address
! 495: and n is the number of one bits in the netmask. All IP addresses which
! 496: match the masked IP address will be allowed in.
! 497: .IP o
! 498: an address/mask in the form ipaddr/maskaddr where ipaddr is the
! 499: IP address and maskaddr is the netmask in dotted decimal notation for IPv4,
! 500: or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
! 501: addresses which match the masked IP address will be allowed in.
! 502: .IP o
! 503: a hostname. The hostname as determined by a reverse lookup will
! 504: be matched (case insensitive) against the pattern. Only an exact
! 505: match is allowed in.
! 506: .IP o
! 507: a hostname pattern using wildcards. These are matched using the
! 508: same rules as normal unix filename matching. If the pattern matches
! 509: then the client is allowed in.
! 510: .RE
! 511:
! 512: .IP
! 513: Note IPv6 link\-local addresses can have a scope in the address specification:
! 514: .IP
! 515: .RS
! 516: \f(CW fe80::1%link1\fP
! 517: .br
! 518: \f(CW fe80::%link1/64\fP
! 519: .br
! 520: \f(CW fe80::%link1/ffff:ffff:ffff:ffff::\fP
! 521: .br
! 522: .RE
! 523:
! 524: .IP
! 525: You can also combine \(dq\&hosts allow\(dq\& with a separate \(dq\&hosts deny\(dq\&
! 526: parameter. If both parameters are specified then the \(dq\&hosts allow\(dq\& parameter is
! 527: checked first and a match results in the client being able to
! 528: connect. The \(dq\&hosts deny\(dq\& parameter is then checked and a match means
! 529: that the host is rejected. If the host does not match either the
! 530: \(dq\&hosts allow\(dq\& or the \(dq\&hosts deny\(dq\& patterns then it is allowed to
! 531: connect.
! 532: .IP
! 533: The default is no \(dq\&hosts allow\(dq\& parameter, which means all hosts can connect.
! 534: .IP
! 535: .IP "\fBhosts deny\fP"
! 536: This parameter allows you to specify a
! 537: list of patterns that are matched against a connecting clients
! 538: hostname and IP address. If the pattern matches then the connection is
! 539: rejected. See the \(dq\&hosts allow\(dq\& parameter for more information.
! 540: .IP
! 541: The default is no \(dq\&hosts deny\(dq\& parameter, which means all hosts can connect.
! 542: .IP
! 543: .IP "\fBignore errors\fP"
! 544: This parameter tells rsyncd to
! 545: ignore I/O errors on the daemon when deciding whether to run the delete
! 546: phase of the transfer. Normally rsync skips the \fB\-\-delete\fP step if any
! 547: I/O errors have occurred in order to prevent disastrous deletion due
! 548: to a temporary resource shortage or other I/O error. In some cases this
! 549: test is counter productive so you can use this parameter to turn off this
! 550: behavior.
! 551: .IP
! 552: .IP "\fBignore nonreadable\fP"
! 553: This tells the rsync daemon to completely
! 554: ignore files that are not readable by the user. This is useful for
! 555: public archives that may have some non\-readable files among the
! 556: directories, and the sysadmin doesn\(cq\&t want those files to be seen at all.
! 557: .IP
! 558: .IP "\fBtransfer logging\fP"
! 559: This parameter enables per\-file
! 560: logging of downloads and uploads in a format somewhat similar to that
! 561: used by ftp daemons. The daemon always logs the transfer at the end, so
! 562: if a transfer is aborted, no mention will be made in the log file.
! 563: .IP
! 564: If you want to customize the log lines, see the \(dq\&log format\(dq\& parameter.
! 565: .IP
! 566: .IP "\fBlog format\fP"
! 567: This parameter allows you to specify the
! 568: format used for logging file transfers when transfer logging is enabled.
! 569: The format is a text string containing embedded single\-character escape
! 570: sequences prefixed with a percent (%) character. An optional numeric
! 571: field width may also be specified between the percent and the escape
! 572: letter (e.g. \(dq\&\fB%\-50n %8l %07p\fP\(dq\&).
! 573: .IP
! 574: The default log format is \(dq\&%o %h [%a] %m (%u) %f %l\(dq\&, and a \(dq\&%t [%p] \(dq\&
! 575: is always prefixed when using the \(dq\&log file\(dq\& parameter.
! 576: (A perl script that will summarize this default log format is included
! 577: in the rsync source code distribution in the \(dq\&support\(dq\& subdirectory:
! 578: rsyncstats.)
! 579: .IP
! 580: The single\-character escapes that are understood are as follows:
! 581: .IP
! 582: .RS
! 583: .IP o
! 584: %a the remote IP address
! 585: .IP o
! 586: %b the number of bytes actually transferred
! 587: .IP o
! 588: %B the permission bits of the file (e.g. rwxrwxrwt)
! 589: .IP o
! 590: %c the total size of the block checksums received for the basis file (only when sending)
! 591: .IP o
! 592: %f the filename (long form on sender; no trailing \(dq\&/\(dq\&)
! 593: .IP o
! 594: %G the gid of the file (decimal) or \(dq\&DEFAULT\(dq\&
! 595: .IP o
! 596: %h the remote host name
! 597: .IP o
! 598: %i an itemized list of what is being updated
! 599: .IP o
! 600: %l the length of the file in bytes
! 601: .IP o
! 602: %L the string \(dq\& \-> SYMLINK\(dq\&, \(dq\& => HARDLINK\(dq\&, or \(dq\&\(dq\& (where \fBSYMLINK\fP or \fBHARDLINK\fP is a filename)
! 603: .IP o
! 604: %m the module name
! 605: .IP o
! 606: %M the last\-modified time of the file
! 607: .IP o
! 608: %n the filename (short form; trailing \(dq\&/\(dq\& on dir)
! 609: .IP o
! 610: %o the operation, which is \(dq\&send\(dq\&, \(dq\&recv\(dq\&, or \(dq\&del.\(dq\& (the latter includes the trailing period)
! 611: .IP o
! 612: %p the process ID of this rsync session
! 613: .IP o
! 614: %P the module path
! 615: .IP o
! 616: %t the current date time
! 617: .IP o
! 618: %u the authenticated username or an empty string
! 619: .IP o
! 620: %U the uid of the file (decimal)
! 621: .RE
! 622:
! 623: .IP
! 624: For a list of what the characters mean that are output by \(dq\&%i\(dq\&, see the
! 625: \fB\-\-itemize\-changes\fP option in the rsync manpage.
! 626: .IP
! 627: Note that some of the logged output changes when talking with older
! 628: rsync versions. For instance, deleted files were only output as verbose
! 629: messages prior to rsync 2.6.4.
! 630: .IP
! 631: .IP "\fBtimeout\fP"
! 632: This parameter allows you to override the
! 633: clients choice for I/O timeout for this module. Using this parameter you
! 634: can ensure that rsync won\(cq\&t wait on a dead client forever. The timeout
! 635: is specified in seconds. A value of zero means no timeout and is the
! 636: default. A good choice for anonymous rsync daemons may be 600 (giving
! 637: a 10 minute timeout).
! 638: .IP
! 639: .IP "\fBrefuse options\fP"
! 640: This parameter allows you to
! 641: specify a space\-separated list of rsync command line options that will
! 642: be refused by your rsync daemon.
! 643: You may specify the full option name, its one\-letter abbreviation, or a
! 644: wild\-card string that matches multiple options.
! 645: For example, this would refuse \fB\-\-checksum\fP (\fB\-c\fP) and all the various
! 646: delete options:
! 647: .IP
! 648: .RS
! 649: \f(CW refuse options = c delete\fP
! 650: .RE
! 651:
! 652: .IP
! 653: The reason the above refuses all delete options is that the options imply
! 654: \fB\-\-delete\fP, and implied options are refused just like explicit options.
! 655: As an additional safety feature, the refusal of \(dq\&delete\(dq\& also refuses
! 656: \fBremove\-source\-files\fP when the daemon is the sender; if you want the latter
! 657: without the former, instead refuse \(dq\&delete\-*\(dq\& \-\- that refuses all the
! 658: delete modes without affecting \fB\-\-remove\-source\-files\fP.
! 659: .IP
! 660: When an option is refused, the daemon prints an error message and exits.
! 661: To prevent all compression when serving files,
! 662: you can use \(dq\&dont compress = *\(dq\& (see below)
! 663: instead of \(dq\&refuse options = compress\(dq\& to avoid returning an error to a
! 664: client that requests compression.
! 665: .IP
! 666: .IP "\fBdont compress\fP"
! 667: This parameter allows you to select
! 668: filenames based on wildcard patterns that should not be compressed
! 669: when pulling files from the daemon (no analogous parameter exists to
! 670: govern the pushing of files to a daemon).
! 671: Compression is expensive in terms of CPU usage, so it
! 672: is usually good to not try to compress files that won\(cq\&t compress well,
! 673: such as already compressed files.
! 674: .IP
! 675: The \(dq\&dont compress\(dq\& parameter takes a space\-separated list of
! 676: case\-insensitive wildcard patterns. Any source filename matching one
! 677: of the patterns will not be compressed during transfer.
! 678: .IP
! 679: See the \fB\-\-skip\-compress\fP parameter in the \fBrsync\fP(1) manpage for the list
! 680: of file suffixes that are not compressed by default. Specifying a value
! 681: for the \(dq\&dont compress\(dq\& parameter changes the default when the daemon is
! 682: the sender.
! 683: .IP
! 684: .IP "\fBpre\-xfer exec\fP, \fBpost\-xfer exec\fP"
! 685: You may specify a command to be run
! 686: before and/or after the transfer. If the \fBpre\-xfer exec\fP command fails, the
! 687: transfer is aborted before it begins.
! 688: .IP
! 689: The following environment variables will be set, though some are
! 690: specific to the pre\-xfer or the post\-xfer environment:
! 691: .IP
! 692: .RS
! 693: .IP o
! 694: \fBRSYNC_MODULE_NAME\fP: The name of the module being accessed.
! 695: .IP o
! 696: \fBRSYNC_MODULE_PATH\fP: The path configured for the module.
! 697: .IP o
! 698: \fBRSYNC_HOST_ADDR\fP: The accessing host\(cq\&s IP address.
! 699: .IP o
! 700: \fBRSYNC_HOST_NAME\fP: The accessing host\(cq\&s name.
! 701: .IP o
! 702: \fBRSYNC_USER_NAME\fP: The accessing user\(cq\&s name (empty if no user).
! 703: .IP o
! 704: \fBRSYNC_PID\fP: A unique number for this transfer.
! 705: .IP o
! 706: \fBRSYNC_REQUEST\fP: (pre\-xfer only) The module/path info specified
! 707: by the user (note that the user can specify multiple source files,
! 708: so the request can be something like \(dq\&mod/path1 mod/path2\(dq\&, etc.).
! 709: .IP o
! 710: \fBRSYNC_ARG#\fP: (pre\-xfer only) The pre\-request arguments are set
! 711: in these numbered values. RSYNC_ARG0 is always \(dq\&rsyncd\(dq\&, and the last
! 712: value contains a single period.
! 713: .IP o
! 714: \fBRSYNC_EXIT_STATUS\fP: (post\-xfer only) the server side\(cq\&s exit value.
! 715: This will be 0 for a successful run, a positive value for an error that the
! 716: server generated, or a \-1 if rsync failed to exit properly. Note that an
! 717: error that occurs on the client side does not currently get sent to the
! 718: server side, so this is not the final exit status for the whole transfer.
! 719: .IP o
! 720: \fBRSYNC_RAW_STATUS\fP: (post\-xfer only) the raw exit value from
! 721: \f(CWwaitpid()\fP
! 722: \&.
! 723: .RE
! 724:
! 725: .IP
! 726: Even though the commands can be associated with a particular module, they
! 727: are run using the permissions of the user that started the daemon (not the
! 728: module\(cq\&s uid/gid setting) without any chroot restrictions.
! 729: .IP
! 730: .SH "AUTHENTICATION STRENGTH"
! 731:
! 732: .PP
! 733: The authentication protocol used in rsync is a 128 bit MD4 based
! 734: challenge response system. This is fairly weak protection, though (with
! 735: at least one brute\-force hash\-finding algorithm publicly available), so
! 736: if you want really top\-quality security, then I recommend that you run
! 737: rsync over ssh. (Yes, a future version of rsync will switch over to a
! 738: stronger hashing method.)
! 739: .PP
! 740: Also note that the rsync daemon protocol does not currently provide any
! 741: encryption of the data that is transferred over the connection. Only
! 742: authentication is provided. Use ssh as the transport if you want
! 743: encryption.
! 744: .PP
! 745: Future versions of rsync may support SSL for better authentication and
! 746: encryption, but that is still being investigated.
! 747: .PP
! 748: .SH "EXAMPLES"
! 749:
! 750: .PP
! 751: A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
! 752: \f(CW/home/ftp\fP would be:
! 753: .PP
! 754: .nf
! 755:
! 756: [ftp]
! 757: path = /home/ftp
! 758: comment = ftp export area
! 759:
! 760: .fi
! 761:
! 762: .PP
! 763: A more sophisticated example would be:
! 764: .PP
! 765: .nf
! 766:
! 767: uid = nobody
! 768: gid = nobody
! 769: use chroot = yes
! 770: max connections = 4
! 771: syslog facility = local5
! 772: pid file = /var/run/rsyncd.pid
! 773:
! 774: [ftp]
! 775: path = /var/ftp/./pub
! 776: comment = whole ftp area (approx 6.1 GB)
! 777:
! 778: [sambaftp]
! 779: path = /var/ftp/./pub/samba
! 780: comment = Samba ftp area (approx 300 MB)
! 781:
! 782: [rsyncftp]
! 783: path = /var/ftp/./pub/rsync
! 784: comment = rsync ftp area (approx 6 MB)
! 785:
! 786: [sambawww]
! 787: path = /public_html/samba
! 788: comment = Samba WWW pages (approx 240 MB)
! 789:
! 790: [cvs]
! 791: path = /data/cvs
! 792: comment = CVS repository (requires authentication)
! 793: auth users = tridge, susan
! 794: secrets file = /etc/rsyncd.secrets
! 795:
! 796: .fi
! 797:
! 798: .PP
! 799: The /etc/rsyncd.secrets file would look something like this:
! 800: .PP
! 801: .RS
! 802: \f(CWtridge:mypass\fP
! 803: .br
! 804: \f(CWsusan:herpass\fP
! 805: .br
! 806: .RE
! 807:
! 808: .PP
! 809: .SH "FILES"
! 810:
! 811: .PP
! 812: /etc/rsyncd.conf or rsyncd.conf
! 813: .PP
! 814: .SH "SEE ALSO"
! 815:
! 816: .PP
! 817: \fBrsync\fP(1)
! 818: .PP
! 819: .SH "DIAGNOSTICS"
! 820:
! 821: .PP
! 822: .SH "BUGS"
! 823:
! 824: .PP
! 825: Please report bugs! The rsync bug tracking system is online at
! 826: http://rsync.samba.org/
! 827: .PP
! 828: .SH "VERSION"
! 829:
! 830: .PP
! 831: This man page is current for version 3.0.9 of rsync.
! 832: .PP
! 833: .SH "CREDITS"
! 834:
! 835: .PP
! 836: rsync is distributed under the GNU public license. See the file
! 837: COPYING for details.
! 838: .PP
! 839: The primary ftp site for rsync is
! 840: ftp://rsync.samba.org/pub/rsync.
! 841: .PP
! 842: A WEB site is available at
! 843: http://rsync.samba.org/
! 844: .PP
! 845: We would be delighted to hear from you if you like this program.
! 846: .PP
! 847: This program uses the zlib compression library written by Jean\-loup
! 848: Gailly and Mark Adler.
! 849: .PP
! 850: .SH "THANKS"
! 851:
! 852: .PP
! 853: Thanks to Warren Stanley for his original idea and patch for the rsync
! 854: daemon. Thanks to Karsten Thygesen for his many suggestions and
! 855: documentation!
! 856: .PP
! 857: .SH "AUTHOR"
! 858:
! 859: .PP
! 860: rsync was written by Andrew Tridgell and Paul Mackerras.
! 861: Many people have later contributed to it.
! 862: .PP
! 863: Mailing lists for support and development are available at
! 864: http://lists.samba.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rsyncd.conf.5 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync