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