Annotation of embedaddon/rsync/rsyncd.conf.5.md, revision 1.1
1.1 ! misho 1: # NAME
! 2:
! 3: rsyncd.conf - configuration file for rsync in daemon mode
! 4:
! 5: # SYNOPSIS
! 6:
! 7: rsyncd.conf
! 8:
! 9: # DESCRIPTION
! 10:
! 11: The rsyncd.conf file is the runtime configuration file for rsync when run as an
! 12: rsync daemon.
! 13:
! 14: The rsyncd.conf file controls authentication, access, logging and available
! 15: modules.
! 16:
! 17: # FILE FORMAT
! 18:
! 19: The file consists of modules and parameters. A module begins with the name of
! 20: the module in square brackets and continues until the next module begins.
! 21: Modules contain parameters of the form `name = value`.
! 22:
! 23: The file is line-based -- that is, each newline-terminated line represents
! 24: either a comment, a module name or a parameter.
! 25:
! 26: Only the first equals sign in a parameter is significant. Whitespace before or
! 27: after the first equals sign is discarded. Leading, trailing and internal
! 28: whitespace in module and parameter names is irrelevant. Leading and trailing
! 29: whitespace in a parameter value is discarded. Internal whitespace within a
! 30: parameter value is retained verbatim.
! 31:
! 32: Any line **beginning** with a hash (`#`) is ignored, as are lines containing
! 33: only whitespace. (If a hash occurs after anything other than leading
! 34: whitespace, it is considered a part of the line's content.)
! 35:
! 36: Any line ending in a `\` is "continued" on the next line in the customary UNIX
! 37: fashion.
! 38:
! 39: The values following the equals sign in parameters are all either a string (no
! 40: quotes needed) or a boolean, which may be given as yes/no, 0/1 or true/false.
! 41: Case is not significant in boolean values, but is preserved in string values.
! 42:
! 43: # LAUNCHING THE RSYNC DAEMON
! 44:
! 45: The rsync daemon is launched by specifying the `--daemon` option to
! 46: rsync.
! 47:
! 48: The daemon must run with root privileges if you wish to use chroot, to bind to
! 49: a port numbered under 1024 (as is the default 873), or to set file ownership.
! 50: Otherwise, it must just have permission to read and write the appropriate data,
! 51: log, and lock files.
! 52:
! 53: You can launch it either via inetd, as a stand-alone daemon, or from an rsync
! 54: client via a remote shell. If run as a stand-alone daemon then just run the
! 55: command "`rsync --daemon`" from a suitable startup script.
! 56:
! 57: When run via inetd you should add a line like this to /etc/services:
! 58:
! 59: > rsync 873/tcp
! 60:
! 61: and a single line something like this to /etc/inetd.conf:
! 62:
! 63: > rsync stream tcp nowait root /usr/bin/rsync rsyncd --daemon
! 64:
! 65: Replace "/usr/bin/rsync" with the path to where you have rsync installed on
! 66: your system. You will then need to send inetd a HUP signal to tell it to
! 67: reread its config file.
! 68:
! 69: Note that you should **not** send the rsync daemon a HUP signal to force it to
! 70: reread the `rsyncd.conf` file. The file is re-read on each client connection.
! 71:
! 72: # GLOBAL PARAMETERS
! 73:
! 74: The first parameters in the file (before a [module] header) are the global
! 75: parameters. Rsync also allows for the use of a "[global]" module name to
! 76: indicate the start of one or more global-parameter sections (the name must be
! 77: lower case).
! 78:
! 79: You may also include any module parameters in the global part of the config
! 80: file in which case the supplied value will override the default for that
! 81: parameter.
! 82:
! 83: You may use references to environment variables in the values of parameters.
! 84: String parameters will have %VAR% references expanded as late as possible (when
! 85: the string is first used in the program), allowing for the use of variables
! 86: that rsync sets at connection time, such as RSYNC_USER_NAME. Non-string
! 87: parameters (such as true/false settings) are expanded when read from the config
! 88: file. If a variable does not exist in the environment, or if a sequence of
! 89: characters is not a valid reference (such as an un-paired percent sign), the
! 90: raw characters are passed through unchanged. This helps with backward
! 91: compatibility and safety (e.g. expanding a non-existent %VAR% to an empty
! 92: string in a path could result in a very unsafe path). The safest way to insert
! 93: a literal % into a value is to use %%.
! 94:
! 95: [comment]: # (An OL starting at 0 is converted into a DL by the parser.)
! 96:
! 97: 0. `motd file`
! 98:
! 99: This parameter allows you to specify a "message of the day" to display to
! 100: clients on each connect. This usually contains site information and any
! 101: legal notices. The default is no motd file. This can be overridden by the
! 102: `--dparam=motdfile=FILE` command-line option when starting the daemon.
! 103:
! 104: 0. `pid file`
! 105:
! 106: This parameter tells the rsync daemon to write its process ID to that file.
! 107: The rsync keeps the file locked so that it can know when it is safe to
! 108: overwrite an existing file.
! 109:
! 110: The filename can be overridden by the `--dparam=pidfile=FILE` command-line
! 111: option when starting the daemon.
! 112:
! 113: 0. `port`
! 114:
! 115: You can override the default port the daemon will listen on by specifying
! 116: this value (defaults to 873). This is ignored if the daemon is being run
! 117: by inetd, and is superseded by the `--port` command-line option.
! 118:
! 119: 0. `address`
! 120:
! 121: You can override the default IP address the daemon will listen on by
! 122: specifying this value. This is ignored if the daemon is being run by
! 123: inetd, and is superseded by the `--address` command-line option.
! 124:
! 125: 0. `socket options`
! 126:
! 127: This parameter can provide endless fun for people who like to tune their
! 128: systems to the utmost degree. You can set all sorts of socket options which
! 129: may make transfers faster (or slower!). Read the man page for the
! 130: **setsockopt()** system call for details on some of the options you may be
! 131: able to set. By default no special socket options are set. These settings
! 132: can also be specified via the `--sockopts` command-line option.
! 133:
! 134: 0. `listen backlog`
! 135:
! 136: You can override the default backlog value when the daemon listens for
! 137: connections. It defaults to 5.
! 138:
! 139: 0. `use slp`
! 140:
! 141: You can enable Service Location Protocol support by enabling this global
! 142: parameter. The default is "false".
! 143:
! 144: 0. `slp refresh`
! 145:
! 146: This parameter is used to determine how long service advertisements are
! 147: valid (measured in seconds), and is only applicable if you have Service
! 148: Location Protocol support compiled in. If this is not set or is set to
! 149: zero, then service advertisements never time out. If this is set to less
! 150: than 120 seconds, then 120 seconds is used. If it is set to more than
! 151: 65535, then 65535 is used (which is a limitation of SLP). Using 3600
! 152: (one hour) is a good number if you tend to change your configuration.
! 153:
! 154: # MODULE PARAMETERS
! 155:
! 156: After the global parameters you should define a number of modules, each module
! 157: exports a directory tree as a symbolic name. Modules are exported by specifying
! 158: a module name in square brackets [module] followed by the parameters for that
! 159: module. The module name cannot contain a slash or a closing square bracket.
! 160: If the name contains whitespace, each internal sequence of whitespace will be
! 161: changed into a single space, while leading or trailing whitespace will be
! 162: discarded. Also, the name cannot be "global" as that exact name indicates that
! 163: global parameters follow (see above).
! 164:
! 165: As with GLOBAL PARAMETERS, you may use references to environment variables in
! 166: the values of parameters. See the GLOBAL PARAMETERS section for more details.
! 167:
! 168: 0. `comment`
! 169:
! 170: This parameter specifies a description string that is displayed next to the
! 171: module name when clients obtain a list of available modules. The default is
! 172: no comment.
! 173:
! 174: 0. `path`
! 175:
! 176: This parameter specifies the directory in the daemon's filesystem to make
! 177: available in this module. You must specify this parameter for each module
! 178: in `rsyncd.conf`.
! 179:
! 180: You may base the path's value off of an environment variable by surrounding
! 181: the variable name with percent signs. You can even reference a variable
! 182: that is set by rsync when the user connects. For example, this would use
! 183: the authorizing user's name in the path:
! 184:
! 185: > path = /home/%RSYNC_USER_NAME%
! 186:
! 187: It is fine if the path includes internal spaces -- they will be retained
! 188: verbatim (which means that you shouldn't try to escape them). If your
! 189: final directory has a trailing space (and this is somehow not something you
! 190: wish to fix), append a trailing slash to the path to avoid losing the
! 191: trailing whitespace.
! 192:
! 193: 0. `use chroot`
! 194:
! 195: If "use chroot" is true, the rsync daemon will chroot to the "path" before
! 196: starting the file transfer with the client. This has the advantage of
! 197: extra protection against possible implementation security holes, but it has
! 198: the disadvantages of requiring super-user privileges, of not being able to
! 199: follow symbolic links that are either absolute or outside of the new root
! 200: path, and of complicating the preservation of users and groups by name (see
! 201: below).
! 202:
! 203: As an additional safety feature, you can specify a dot-dir in the module's
! 204: "path" to indicate the point where the chroot should occur. This allows
! 205: rsync to run in a chroot with a non-"/" path for the top of the transfer
! 206: hierarchy. Doing this guards against unintended library loading (since
! 207: those absolute paths will not be inside the transfer hierarchy unless you
! 208: have used an unwise pathname), and lets you setup libraries for the chroot
! 209: that are outside of the transfer. For example, specifying
! 210: "/var/rsync/./module1" will chroot to the "/var/rsync" directory and set
! 211: the inside-chroot path to "/module1". If you had omitted the dot-dir, the
! 212: chroot would have used the whole path, and the inside-chroot path would
! 213: have been "/".
! 214:
! 215: When both "use chroot" and "daemon chroot" are false, OR the inside-chroot
! 216: path of "use chroot" is not "/", rsync will: (1) munge symlinks by default
! 217: for security reasons (see "munge symlinks" for a way to turn this off, but
! 218: only if you trust your users), (2) substitute leading slashes in absolute
! 219: paths with the module's path (so that options such as `--backup-dir`,
! 220: `--compare-dest`, etc. interpret an absolute path as rooted in the module's
! 221: "path" dir), and (3) trim ".." path elements from args if rsync believes
! 222: they would escape the module hierarchy. The default for "use chroot" is
! 223: true, and is the safer choice (especially if the module is not read-only).
! 224:
! 225: When this parameter is enabled *and* the "name converter" parameter is
! 226: *not* set, the "numeric ids" parameter will default to being enabled
! 227: (disabling name lookups). This means that if you manually setup
! 228: name-lookup libraries in your chroot (instead of using a name converter)
! 229: that you need to explicitly set `numeric ids = false` for rsync to do name
! 230: lookups.
! 231:
! 232: If you copy library resources into the module's chroot area, you should
! 233: protect them through your OS's normal user/group or ACL settings (to
! 234: prevent the rsync module's user from being able to change them), and then
! 235: hide them from the user's view via "exclude" (see how in the discussion of
! 236: that parameter). However, it's easier and safer to setup a name converter.
! 237:
! 238: 0. `daemon chroot`
! 239:
! 240: This parameter specifies a path to which the daemon will chroot before
! 241: beginning communication with clients. Module paths (and any "use chroot"
! 242: settings) will then be related to this one. This lets you choose if you
! 243: want the whole daemon to be chrooted (with this setting), just the
! 244: transfers to be chrooted (with "use chroot"), or both. Keep in mind that
! 245: the "daemon chroot" area may need various OS/lib/etc files installed to
! 246: allow the daemon to function. By default the daemon runs without any
! 247: chrooting.
! 248:
! 249: 0. `proxy protocol`
! 250:
! 251: When this parameter is enabled, all incoming connections must start with a
! 252: V1 or V2 proxy protocol header. If the header is not found, the connection
! 253: is closed.
! 254:
! 255: Setting this to `true` requires a proxy server to forward source IP
! 256: information to rsync, allowing you to log proper IP/host info and make use
! 257: of client-oriented IP restrictions. The default of `false` means that the
! 258: IP information comes directly from the socket's metadata. If rsync is not
! 259: behind a proxy, this should be disabled.
! 260:
! 261: _CAUTION_: using this option can be dangerous if you do not ensure that
! 262: only the proxy is allowed to connect to the rsync port. If any non-proxied
! 263: connections are allowed through, the client will be able to use a modified
! 264: rsync to spoof any remote IP address that they desire. You can lock this
! 265: down using something like iptables `-uid-owner root` rules (for strict
! 266: localhost access), various firewall rules, or you can require password
! 267: authorization so that any spoofing by users will not grant extra access.
! 268:
! 269: This setting is global. If you need some modules to require this and not
! 270: others, then you will need to setup multiple rsync daemon processes on
! 271: different ports.
! 272:
! 273: 0. `name converter`
! 274:
! 275: This parameter lets you specify a program that will be run by the rsync
! 276: daemon to do user & group conversions between names & ids. This script
! 277: is started prior to any chroot being setup, and runs as the daemon user
! 278: (not the transfer user). You can specify a fully qualified pathname or
! 279: a program name that is on the $PATH.
! 280:
! 281: The program can be used to do normal user & group lookups without having to
! 282: put any extra files into the chroot area of the module *or* you can do
! 283: customized conversions.
! 284:
! 285: The nameconvert program has access to all of the environment variables that
! 286: are described in the section on `pre-xfer exec`. This is useful if you
! 287: want to customize the conversion using information about the module and/or
! 288: the copy request.
! 289:
! 290: There is a sample python script in the support dir named "nameconvert" that
! 291: implements the normal user & group lookups. Feel free to customize it or
! 292: just use it as documentation to implement your own.
! 293:
! 294: 0. `numeric ids`
! 295:
! 296: Enabling this parameter disables the mapping of users and groups by name
! 297: for the current daemon module. This prevents the daemon from trying to
! 298: load any user/group-related files or libraries. This enabling makes the
! 299: transfer behave as if the client had passed the `--numeric-ids`
! 300: command-line option. By default, this parameter is enabled for chroot
! 301: modules and disabled for non-chroot modules. Also keep in mind that
! 302: uid/gid preservation requires the module to be running as root (see "uid")
! 303: or for "fake super" to be configured.
! 304:
! 305: A chroot-enabled module should not have this parameter set to false unless
! 306: you're using a "name converter" program *or* you've taken steps to ensure
! 307: that the module has the necessary resources it needs to translate names and
! 308: that it is not possible for a user to change those resources.
! 309:
! 310: 0. `munge symlinks`
! 311:
! 312: This parameter tells rsync to modify all symlinks in the same way as the
! 313: (non-daemon-affecting) `--munge-links` command-line option (using a method
! 314: described below). This should help protect your files from user trickery
! 315: when your daemon module is writable. The default is disabled when
! 316: "use chroot" is on with an inside-chroot path of "/", OR if "daemon chroot"
! 317: is on, otherwise it is enabled.
! 318:
! 319: If you disable this parameter on a daemon that is not read-only, there are
! 320: tricks that a user can play with uploaded symlinks to access
! 321: daemon-excluded items (if your module has any), and, if "use chroot" is
! 322: off, rsync can even be tricked into showing or changing data that is
! 323: outside the module's path (as access-permissions allow).
! 324:
! 325: The way rsync disables the use of symlinks is to prefix each one with the
! 326: string "/rsyncd-munged/". This prevents the links from being used as long
! 327: as that directory does not exist. When this parameter is enabled, rsync
! 328: will refuse to run if that path is a directory or a symlink to a directory.
! 329: When using the "munge symlinks" parameter in a chroot area that has an
! 330: inside-chroot path of "/", you should add "/rsyncd-munged/" to the exclude
! 331: setting for the module so that a user can't try to create it.
! 332:
! 333: Note: rsync makes no attempt to verify that any pre-existing symlinks in
! 334: the module's hierarchy are as safe as you want them to be (unless, of
! 335: course, it just copied in the whole hierarchy). If you setup an rsync
! 336: daemon on a new area or locally add symlinks, you can manually protect your
! 337: symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
! 338: every symlink's value. There is a perl script in the support directory of
! 339: the source code named "munge-symlinks" that can be used to add or remove
! 340: this prefix from your symlinks.
! 341:
! 342: When this parameter is disabled on a writable module and "use chroot" is
! 343: off (or the inside-chroot path is not "/"), incoming symlinks will be
! 344: modified to drop a leading slash and to remove ".." path elements that
! 345: rsync believes will allow a symlink to escape the module's hierarchy.
! 346: There are tricky ways to work around this, though, so you had better trust
! 347: your users if you choose this combination of parameters.
! 348:
! 349: 0. `charset`
! 350:
! 351: This specifies the name of the character set in which the module's
! 352: filenames are stored. If the client uses an `--iconv` option, the daemon
! 353: will use the value of the "charset" parameter regardless of the character
! 354: set the client actually passed. This allows the daemon to support charset
! 355: conversion in a chroot module without extra files in the chroot area, and
! 356: also ensures that name-translation is done in a consistent manner. If the
! 357: "charset" parameter is not set, the `--iconv` option is refused, just as if
! 358: "iconv" had been specified via "refuse options".
! 359:
! 360: If you wish to force users to always use `--iconv` for a particular module,
! 361: add "no-iconv" to the "refuse options" parameter. Keep in mind that this
! 362: will restrict access to your module to very new rsync clients.
! 363:
! 364: 0. `max connections`
! 365:
! 366: This parameter allows you to specify the maximum number of simultaneous
! 367: connections you will allow. Any clients connecting when the maximum has
! 368: been reached will receive a message telling them to try later. The default
! 369: is 0, which means no limit. A negative value disables the module. See
! 370: also the "lock file" parameter.
! 371:
! 372: 0. `link by hash dir`
! 373:
! 374: When the "link by hash dir" parameter is set to a non-empty string,
! 375: received files will be hard linked into **DIR**, a link farm arranged by
! 376: MD5 file hash. See the `--link-by-hash` option for a full explanation.
! 377:
! 378: The **DIR** must be accessible inside any chroot restrictions for the
! 379: module, but can exist outside the transfer location if there is an
! 380: inside-the-chroot path to the module (see "use chroot"). Note that a
! 381: user-specified option does not allow this outside-the-transfer-area
! 382: placement.
! 383:
! 384: If this parameter is set, it will disable the `--link-by-hash` command-line
! 385: option for copies into the module.
! 386:
! 387: The default is for this parameter to be unset.
! 388:
! 389: 0. `log file`
! 390:
! 391: When the "log file" parameter is set to a non-empty string, the rsync
! 392: daemon will log messages to the indicated file rather than using syslog.
! 393: This is particularly useful on systems (such as AIX) where **syslog()**
! 394: doesn't work for chrooted programs. The file is opened before **chroot()**
! 395: is called, allowing it to be placed outside the transfer. If this value is
! 396: set on a per-module basis instead of globally, the global log will still
! 397: contain any authorization failures or config-file error messages.
! 398:
! 399: If the daemon fails to open the specified file, it will fall back to using
! 400: syslog and output an error about the failure. (Note that the failure to
! 401: open the specified log file used to be a fatal error.)
! 402:
! 403: This setting can be overridden by using the `--log-file=FILE` or
! 404: `--dparam=logfile=FILE` command-line options. The former overrides all the
! 405: log-file parameters of the daemon and all module settings. The latter sets
! 406: the daemon's log file and the default for all the modules, which still
! 407: allows modules to override the default setting.
! 408:
! 409: 0. `syslog facility`
! 410:
! 411: This parameter allows you to specify the syslog facility name to use when
! 412: logging messages from the rsync daemon. You may use any standard syslog
! 413: facility name which is defined on your system. Common names are auth,
! 414: authpriv, cron, daemon, ftp, kern, lpr, mail, news, security, syslog, user,
! 415: uucp, local0, local1, local2, local3, local4, local5, local6 and local7.
! 416: The default is daemon. This setting has no effect if the "log file"
! 417: setting is a non-empty string (either set in the per-modules settings, or
! 418: inherited from the global settings).
! 419:
! 420: 0. `syslog tag`
! 421:
! 422: This parameter allows you to specify the syslog tag to use when logging
! 423: messages from the rsync daemon. The default is "rsyncd". This setting has
! 424: no effect if the "log file" setting is a non-empty string (either set in
! 425: the per-modules settings, or inherited from the global settings).
! 426:
! 427: For example, if you wanted each authenticated user's name to be included in
! 428: the syslog tag, you could do something like this:
! 429:
! 430: > syslog tag = rsyncd.%RSYNC_USER_NAME%
! 431:
! 432: 0. `max verbosity`
! 433:
! 434: This parameter allows you to control the maximum amount of verbose
! 435: information that you'll allow the daemon to generate (since the information
! 436: goes into the log file). The default is 1, which allows the client to
! 437: request one level of verbosity.
! 438:
! 439: This also affects the user's ability to request higher levels of `--info`
! 440: and `--debug` logging. If the max value is 2, then no info and/or debug
! 441: value that is higher than what would be set by `-vv` will be honored by the
! 442: daemon in its logging. To see how high of a verbosity level you need to
! 443: accept for a particular info/debug level, refer to `rsync --info=help` and
! 444: `rsync --debug=help`. For instance, it takes max-verbosity 4 to be able to
! 445: output debug TIME2 and FLIST3.
! 446:
! 447: 0. `lock file`
! 448:
! 449: This parameter specifies the file to use to support the "max connections"
! 450: parameter. The rsync daemon uses record locking on this file to ensure that
! 451: the max connections limit is not exceeded for the modules sharing the lock
! 452: file. The default is `/var/run/rsyncd.lock`.
! 453:
! 454: 0. `checksum files`
! 455:
! 456: This parameter tells rsync to make use of any cached checksum information
! 457: it finds in per-directory .rsyncsums files when the current transfer is
! 458: using the `--checksum` option. The value can be set to either "lax",
! 459: "strict", "+lax", "+strict", "++lax", "++strict", or +"none". See the
! 460: client's `--sumfiles` option for what these choices do.
! 461:
! 462: Note also that the client's command-line option, `--sumfiles`, has no
! 463: effect on a daemon. A daemon will only access checksum files if this
! 464: config option tells it to. You can configure updating of the .rsyncsums
! 465: files even if the module itself is configured to be read-only. See also
! 466: the `exclude` directive for a way to hide the .rsyncsums files from the
! 467: user.
! 468:
! 469: 0. `read only`
! 470:
! 471: This parameter determines whether clients will be able to upload files or
! 472: not. If "read only" is true then any attempted uploads will fail. If
! 473: "read only" is false then uploads will be possible if file permissions on
! 474: the daemon side allow them. The default is for all modules to be read only.
! 475:
! 476: Note that "auth users" can override this setting on a per-user basis.
! 477:
! 478: 0. `write only`
! 479:
! 480: This parameter determines whether clients will be able to download files or
! 481: not. If "write only" is true then any attempted downloads will fail. If
! 482: "write only" is false then downloads will be possible if file permissions
! 483: on the daemon side allow them. The default is for this parameter to be
! 484: disabled.
! 485:
! 486: Helpful hint: you probably want to specify "refuse options = delete" for a
! 487: write-only module.
! 488:
! 489: 0. `open noatime`
! 490:
! 491: When set to True, this parameter tells the rsync daemon to open files with
! 492: the O_NOATIME flag
! 493: (on systems that support it) to avoid changing the access time of the files
! 494: that are being transferred. If your OS does not support the O_NOATIME flag
! 495: then rsync will silently ignore this option. Note also that some
! 496: filesystems are mounted to avoid updating the atime on read access even
! 497: without the O_NOATIME flag being set.
! 498:
! 499: When set to False, this parameters ensures that files on the server are not
! 500: opened with O_NOATIME.
! 501:
! 502: When set to Unset (the default) the user controls the setting via
! 503: `--open-noatime`.
! 504:
! 505: 0. `list`
! 506:
! 507: This parameter determines whether this module is listed when the client
! 508: asks for a listing of available modules. In addition, if this is false,
! 509: the daemon will pretend the module does not exist when a client denied by
! 510: "hosts allow" or "hosts deny" attempts to access it. Realize that if
! 511: "reverse lookup" is disabled globally but enabled for the module, the
! 512: resulting reverse lookup to a potentially client-controlled DNS server may
! 513: still reveal to the client that it hit an existing module. The default is
! 514: for modules to be listable.
! 515:
! 516: 0. `uid`
! 517:
! 518: This parameter specifies the user name or user ID that file transfers to
! 519: and from that module should take place as when the daemon was run as root.
! 520: In combination with the "gid" parameter this determines what file
! 521: permissions are available. The default when run by a super-user is to
! 522: switch to the system's "nobody" user. The default for a non-super-user is
! 523: to not try to change the user. See also the "gid" parameter.
! 524:
! 525: The RSYNC_USER_NAME environment variable may be used to request that rsync
! 526: run as the authorizing user. For example, if you want a rsync to run as
! 527: the same user that was received for the rsync authentication, this setup is
! 528: useful:
! 529:
! 530: > uid = %RSYNC_USER_NAME%
! 531: > gid = *
! 532:
! 533: 0. `gid`
! 534:
! 535: This parameter specifies one or more group names/IDs that will be used when
! 536: accessing the module. The first one will be the default group, and any
! 537: extra ones be set as supplemental groups. You may also specify a "`*`" as
! 538: the first gid in the list, which will be replaced by all the normal groups
! 539: for the transfer's user (see "uid"). The default when run by a super-user
! 540: is to switch to your OS's "nobody" (or perhaps "nogroup") group with no
! 541: other supplementary groups. The default for a non-super-user is to not
! 542: change any group attributes (and indeed, your OS may not allow a
! 543: non-super-user to try to change their group settings).
! 544:
! 545: The specified list is normally split into tokens based on spaces and
! 546: commas. However, if the list starts with a comma, then the list is only
! 547: split on commas, which allows a group name to contain a space. In either
! 548: case any leading and/or trailing whitespace is removed from the tokens and
! 549: empty tokens are ignored.
! 550:
! 551: 0. `daemon uid`
! 552:
! 553: This parameter specifies a uid under which the daemon will run. The daemon
! 554: usually runs as user root, and when this is left unset the user is left
! 555: unchanged. See also the "uid" parameter.
! 556:
! 557: 0. `daemon gid`
! 558:
! 559: This parameter specifies a gid under which the daemon will run. The daemon
! 560: usually runs as group root, and when this is left unset, the group is left
! 561: unchanged. See also the "gid" parameter.
! 562:
! 563: 0. `fake super`
! 564:
! 565: Setting "fake super = yes" for a module causes the daemon side to behave as
! 566: if the `--fake-super` command-line option had been specified. This allows
! 567: the full attributes of a file to be stored without having to have the
! 568: daemon actually running as root.
! 569:
! 570: 0. `filter`
! 571:
! 572: The daemon has its own filter chain that determines what files it will let
! 573: the client access. This chain is not sent to the client and is independent
! 574: of any filters the client may have specified. Files excluded by the daemon
! 575: filter chain (`daemon-excluded` files) are treated as non-existent if the
! 576: client tries to pull them, are skipped with an error message if the client
! 577: tries to push them (triggering exit code 23), and are never deleted from
! 578: the module. You can use daemon filters to prevent clients from downloading
! 579: or tampering with private administrative files, such as files you may add
! 580: to support uid/gid name translations.
! 581:
! 582: The daemon filter chain is built from the "filter", "include from",
! 583: "include", "exclude from", and "exclude" parameters, in that order of
! 584: priority. Anchored patterns are anchored at the root of the module. To
! 585: prevent access to an entire subtree, for example, "`/secret`", you **must**
! 586: exclude everything in the subtree; the easiest way to do this is with a
! 587: triple-star pattern like "`/secret/***`".
! 588:
! 589: The "filter" parameter takes a space-separated list of daemon filter rules,
! 590: though it is smart enough to know not to split a token at an internal space
! 591: in a rule (e.g. "`- /foo - /bar`" is parsed as two rules). You may specify
! 592: one or more merge-file rules using the normal syntax. Only one "filter"
! 593: parameter can apply to a given module in the config file, so put all the
! 594: rules you want in a single parameter. Note that per-directory merge-file
! 595: rules do not provide as much protection as global rules, but they can be
! 596: used to make `--delete` work better during a client download operation if
! 597: the per-dir merge files are included in the transfer and the client
! 598: requests that they be used.
! 599:
! 600: 0. `exclude`
! 601:
! 602: This parameter takes a space-separated list of daemon exclude patterns. As
! 603: with the client `--exclude` option, patterns can be qualified with "`- `" or
! 604: "`+ `" to explicitly indicate exclude/include. Only one "exclude" parameter
! 605: can apply to a given module. See the "filter" parameter for a description
! 606: of how excluded files affect the daemon.
! 607:
! 608: 0. `include`
! 609:
! 610: Use an "include" to override the effects of the "exclude" parameter. Only
! 611: one "include" parameter can apply to a given module. See the "filter"
! 612: parameter for a description of how excluded files affect the daemon.
! 613:
! 614: 0. `exclude from`
! 615:
! 616: This parameter specifies the name of a file on the daemon that contains
! 617: daemon exclude patterns, one per line. Only one "exclude from" parameter
! 618: can apply to a given module; if you have multiple exclude-from files, you
! 619: can specify them as a merge file in the "filter" parameter. See the
! 620: "filter" parameter for a description of how excluded files affect the
! 621: daemon.
! 622:
! 623: 0. `include from`
! 624:
! 625: Analogue of "exclude from" for a file of daemon include patterns. Only one
! 626: "include from" parameter can apply to a given module. See the "filter"
! 627: parameter for a description of how excluded files affect the daemon.
! 628:
! 629: 0. `incoming chmod`
! 630:
! 631: This parameter allows you to specify a set of comma-separated chmod strings
! 632: that will affect the permissions of all incoming files (files that are
! 633: being received by the daemon). These changes happen after all other
! 634: permission calculations, and this will even override destination-default
! 635: and/or existing permissions when the client does not specify `--perms`.
! 636: See the description of the `--chmod` rsync option and the **chmod**(1)
! 637: manpage for information on the format of this string.
! 638:
! 639: 0. `outgoing chmod`
! 640:
! 641: This parameter allows you to specify a set of comma-separated chmod strings
! 642: that will affect the permissions of all outgoing files (files that are
! 643: being sent out from the daemon). These changes happen first, making the
! 644: sent permissions appear to be different than those stored in the filesystem
! 645: itself. For instance, you could disable group write permissions on the
! 646: server while having it appear to be on to the clients. See the description
! 647: of the `--chmod` rsync option and the **chmod**(1) manpage for information
! 648: on the format of this string.
! 649:
! 650: 0. `auth users`
! 651:
! 652: This parameter specifies a comma and/or space-separated list of
! 653: authorization rules. In its simplest form, you list the usernames that
! 654: will be allowed to connect to this module. The usernames do not need to
! 655: exist on the local system. The rules may contain shell wildcard characters
! 656: that will be matched against the username provided by the client for
! 657: authentication. If "auth users" is set then the client will be challenged
! 658: to supply a username and password to connect to the module. A challenge
! 659: response authentication protocol is used for this exchange. The plain text
! 660: usernames and passwords are stored in the file specified by the
! 661: "secrets file" parameter. The default is for all users to be able to
! 662: connect without a password (this is called "anonymous rsync").
! 663:
! 664: In addition to username matching, you can specify groupname matching via a
! 665: '@' prefix. When using groupname matching, the authenticating username
! 666: must be a real user on the system, or it will be assumed to be a member of
! 667: no groups. For example, specifying "@rsync" will match the authenticating
! 668: user if the named user is a member of the rsync group.
! 669:
! 670: Finally, options may be specified after a colon (:). The options allow you
! 671: to "deny" a user or a group, set the access to "ro" (read-only), or set the
! 672: access to "rw" (read/write). Setting an auth-rule-specific ro/rw setting
! 673: overrides the module's "read only" setting.
! 674:
! 675: Be sure to put the rules in the order you want them to be matched, because
! 676: the checking stops at the first matching user or group, and that is the
! 677: only auth that is checked. For example:
! 678:
! 679: > auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam
! 680:
! 681: In the above rule, user joe will be denied access no matter what. Any user
! 682: that is in the group "guest" is also denied access. The user "admin" gets
! 683: access in read/write mode, but only if the admin user is not in group
! 684: "guest" (because the admin user-matching rule would never be reached if the
! 685: user is in group "guest"). Any other user who is in group "rsync" will get
! 686: read-only access. Finally, users susan, joe, and sam get the ro/rw setting
! 687: of the module, but only if the user didn't match an earlier group-matching
! 688: rule.
! 689:
! 690: If you need to specify a user or group name with a space in it, start your
! 691: list with a comma to indicate that the list should only be split on commas
! 692: (though leading and trailing whitespace will also be removed, and empty
! 693: entries are just ignored). For example:
! 694:
! 695: > auth users = , joe:deny, @Some Group:deny, admin:rw, @RO Group:ro
! 696:
! 697: See the description of the secrets file for how you can have per-user
! 698: passwords as well as per-group passwords. It also explains how a user can
! 699: authenticate using their user password or (when applicable) a group
! 700: password, depending on what rule is being authenticated.
! 701:
! 702: See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE
! 703: SHELL CONNECTION" in **rsync**(1) for information on how handle an
! 704: rsyncd.conf-level username that differs from the remote-shell-level
! 705: username when using a remote shell to connect to an rsync daemon.
! 706:
! 707: 0. `secrets file`
! 708:
! 709: This parameter specifies the name of a file that contains the
! 710: username:password and/or @groupname:password pairs used for authenticating
! 711: this module. This file is only consulted if the "auth users" parameter is
! 712: specified. The file is line-based and contains one name:password pair per
! 713: line. Any line has a hash (#) as the very first character on the line is
! 714: considered a comment and is skipped. The passwords can contain any
! 715: characters but be warned that many operating systems limit the length of
! 716: passwords that can be typed at the client end, so you may find that
! 717: passwords longer than 8 characters don't work.
! 718:
! 719: The use of group-specific lines are only relevant when the module is being
! 720: authorized using a matching "@groupname" rule. When that happens, the user
! 721: can be authorized via either their "username:password" line or the
! 722: "@groupname:password" line for the group that triggered the authentication.
! 723:
! 724: It is up to you what kind of password entries you want to include, either
! 725: users, groups, or both. The use of group rules in "auth users" does not
! 726: require that you specify a group password if you do not want to use shared
! 727: passwords.
! 728:
! 729: There is no default for the "secrets file" parameter, you must choose a
! 730: name (such as `/etc/rsyncd.secrets`). The file must normally not be
! 731: readable by "other"; see "strict modes". If the file is not found or is
! 732: rejected, no logins for a "user auth" module will be possible.
! 733:
! 734: 0. `strict modes`
! 735:
! 736: This parameter determines whether or not the permissions on the secrets
! 737: file will be checked. If "strict modes" is true, then the secrets file
! 738: must not be readable by any user ID other than the one that the rsync
! 739: daemon is running under. If "strict modes" is false, the check is not
! 740: performed. The default is true. This parameter was added to accommodate
! 741: rsync running on the Windows operating system.
! 742:
! 743: 0. `hosts allow`
! 744:
! 745: This parameter allows you to specify a list of comma- and/or
! 746: whitespace-separated patterns that are matched against a connecting
! 747: client's hostname and IP address. If none of the patterns match, then the
! 748: connection is rejected.
! 749:
! 750: Each pattern can be in one of six forms:
! 751:
! 752: - a dotted decimal IPv4 address of the form a.b.c.d, or an IPv6 address of
! 753: the form a:b:c::d:e:f. In this case the incoming machine's IP address
! 754: must match exactly.
! 755: - an address/mask in the form ipaddr/n where ipaddr is the IP address and n
! 756: is the number of one bits in the netmask. All IP addresses which match
! 757: the masked IP address will be allowed in.
! 758: - an address/mask in the form ipaddr/maskaddr where ipaddr is the IP
! 759: address and maskaddr is the netmask in dotted decimal notation for IPv4,
! 760: or similar for IPv6, e.g. ffff:ffff:ffff:ffff:: instead of /64. All IP
! 761: addresses which match the masked IP address will be allowed in.
! 762: - a hostname pattern using wildcards. If the hostname of the connecting IP
! 763: (as determined by a reverse lookup) matches the wildcarded name (using
! 764: the same rules as normal unix filename matching), the client is allowed
! 765: in. This only works if "reverse lookup" is enabled (the default).
! 766: - a hostname. A plain hostname is matched against the reverse DNS of the
! 767: connecting IP (if "reverse lookup" is enabled), and/or the IP of the
! 768: given hostname is matched against the connecting IP (if "forward lookup"
! 769: is enabled, as it is by default). Any match will be allowed in.
! 770: - an '@' followed by a netgroup name, which will match if the reverse DNS
! 771: of the connecting IP is in the specified netgroup.
! 772:
! 773: Note IPv6 link-local addresses can have a scope in the address
! 774: specification:
! 775:
! 776: > fe80::1%link1
! 777: > fe80::%link1/64
! 778: > fe80::%link1/ffff:ffff:ffff:ffff::
! 779:
! 780: You can also combine "hosts allow" with "hosts deny" as a way to add
! 781: exceptions to your deny list. When both parameters are specified, the
! 782: "hosts allow" parameter is checked first and a match results in the client
! 783: being able to connect. A non-allowed host is then matched against the
! 784: "hosts deny" list to see if it should be rejected. A host that does not
! 785: match either list is allowed to connect.
! 786:
! 787: The default is no "hosts allow" parameter, which means all hosts can
! 788: connect.
! 789:
! 790: 0. `hosts deny`
! 791:
! 792: This parameter allows you to specify a list of comma- and/or
! 793: whitespace-separated patterns that are matched against a connecting clients
! 794: hostname and IP address. If the pattern matches then the connection is
! 795: rejected. See the "hosts allow" parameter for more information.
! 796:
! 797: The default is no "hosts deny" parameter, which means all hosts can
! 798: connect.
! 799:
! 800: 0. `reverse lookup`
! 801:
! 802: Controls whether the daemon performs a reverse lookup on the client's IP
! 803: address to determine its hostname, which is used for "hosts allow" &
! 804: "hosts deny" checks and the "%h" log escape. This is enabled by default,
! 805: but you may wish to disable it to save time if you know the lookup will not
! 806: return a useful result, in which case the daemon will use the name
! 807: "UNDETERMINED" instead.
! 808:
! 809: If this parameter is enabled globally (even by default), rsync performs the
! 810: lookup as soon as a client connects, so disabling it for a module will not
! 811: avoid the lookup. Thus, you probably want to disable it globally and then
! 812: enable it for modules that need the information.
! 813:
! 814: 0. `forward lookup`
! 815:
! 816: Controls whether the daemon performs a forward lookup on any hostname
! 817: specified in an hosts allow/deny setting. By default this is enabled,
! 818: allowing the use of an explicit hostname that would not be returned by
! 819: reverse DNS of the connecting IP.
! 820:
! 821: 0. `ignore errors`
! 822:
! 823: This parameter tells rsyncd to ignore I/O errors on the daemon when
! 824: deciding whether to run the delete phase of the transfer. Normally rsync
! 825: skips the `--delete` step if any I/O errors have occurred in order to
! 826: prevent disastrous deletion due to a temporary resource shortage or other
! 827: I/O error. In some cases this test is counter productive so you can use
! 828: this parameter to turn off this behavior.
! 829:
! 830: 0. `ignore nonreadable`
! 831:
! 832: This tells the rsync daemon to completely ignore files that are not
! 833: readable by the user. This is useful for public archives that may have some
! 834: non-readable files among the directories, and the sysadmin doesn't want
! 835: those files to be seen at all.
! 836:
! 837: 0. `transfer logging`
! 838:
! 839: This parameter enables per-file logging of downloads and uploads in a
! 840: format somewhat similar to that used by ftp daemons. The daemon always
! 841: logs the transfer at the end, so if a transfer is aborted, no mention will
! 842: be made in the log file.
! 843:
! 844: If you want to customize the log lines, see the "log format" parameter.
! 845:
! 846: 0. `log format`
! 847:
! 848: This parameter allows you to specify the format used for logging file
! 849: transfers when transfer logging is enabled. The format is a text string
! 850: containing embedded single-character escape sequences prefixed with a
! 851: percent (%) character. An optional numeric field width may also be
! 852: specified between the percent and the escape letter (e.g.
! 853: "`%-50n %8l %07p`"). In addition, one or more apostrophes may be specified
! 854: prior to a numerical escape to indicate that the numerical value should be
! 855: made more human-readable. The 3 supported levels are the same as for the
! 856: `--human-readable` command-line option, though the default is for
! 857: human-readability to be off. Each added apostrophe increases the level
! 858: (e.g. "`%''l %'b %f`").
! 859:
! 860: The default log format is "`%o %h [%a] %m (%u) %f %l`", and a "`%t [%p] `"
! 861: is always prefixed when using the "log file" parameter. (A perl script
! 862: that will summarize this default log format is included in the rsync source
! 863: code distribution in the "support" subdirectory: rsyncstats.)
! 864:
! 865: The single-character escapes that are understood are as follows:
! 866:
! 867: - %a the remote IP address (only available for a daemon)
! 868: - %b the number of bytes actually transferred
! 869: - %B the permission bits of the file (e.g. rwxrwxrwt)
! 870: - %c the total size of the block checksums received for the basis file
! 871: (only when sending)
! 872: - %C the full-file checksum if it is known for the file. For older rsync
! 873: protocols/versions, the checksum was salted, and is thus not a useful
! 874: value (and is not displayed when that is the case). For the checksum to
! 875: output for a file, either the `--checksum` option must be in-effect or
! 876: the file must have been transferred without a salted checksum being used.
! 877: See the `--checksum-choice` option for a way to choose the algorithm.
! 878: - %f the filename (long form on sender; no trailing "/")
! 879: - %G the gid of the file (decimal) or "DEFAULT"
! 880: - %h the remote host name (only available for a daemon)
! 881: - %i an itemized list of what is being updated
! 882: - %l the length of the file in bytes
! 883: - %L the string "` -> SYMLINK`", "` => HARDLINK`", or "" (where `SYMLINK`
! 884: or `HARDLINK` is a filename)
! 885: - %m the module name
! 886: - %M the last-modified time of the file
! 887: - %n the filename (short form; trailing "/" on dir)
! 888: - %o the operation, which is "send", "recv", or "del." (the latter includes
! 889: the trailing period)
! 890: - %p the process ID of this rsync session
! 891: - %P the module path
! 892: - %t the current date time
! 893: - %u the authenticated username or an empty string
! 894: - %U the uid of the file (decimal)
! 895:
! 896: For a list of what the characters mean that are output by "%i", see the
! 897: `--itemize-changes` option in the rsync manpage.
! 898:
! 899: Note that some of the logged output changes when talking with older rsync
! 900: versions. For instance, deleted files were only output as verbose messages
! 901: prior to rsync 2.6.4.
! 902:
! 903: 0. `timeout`
! 904:
! 905: This parameter allows you to override the clients choice for I/O timeout
! 906: for this module. Using this parameter you can ensure that rsync won't wait
! 907: on a dead client forever. The timeout is specified in seconds. A value of
! 908: zero means no timeout and is the default. A good choice for anonymous rsync
! 909: daemons may be 600 (giving a 10 minute timeout).
! 910:
! 911: 0. `refuse options`
! 912:
! 913: This parameter allows you to specify a space-separated list of rsync
! 914: command-line options that will be refused by your rsync daemon. You may
! 915: specify the full option name, its one-letter abbreviation, or a wild-card
! 916: string that matches multiple options. Beginning in 3.2.0, you can also
! 917: negate a match term by starting it with a "!".
! 918:
! 919: When an option is refused, the daemon prints an error message and exits.
! 920:
! 921: For example, this would refuse `--checksum` (`-c`) and all the various
! 922: delete options:
! 923:
! 924: > refuse options = c delete
! 925:
! 926: The reason the above refuses all delete options is that the options imply
! 927: `--delete`, and implied options are refused just like explicit options.
! 928:
! 929: The use of a negated match allows you to fine-tune your refusals after a
! 930: wild-card, such as this:
! 931:
! 932: > refuse options = delete-* !delete-during
! 933:
! 934: Negated matching can also turn your list of refused options into a list of
! 935: accepted options. To do this, begin the list with a "`*`" (to refuse all
! 936: options) and then specify one or more negated matches to accept. For
! 937: example:
! 938:
! 939: > refuse options = * !a !v !compress*
! 940:
! 941: Don't worry that the "`*`" will refuse certain vital options such as
! 942: `--dry-run`, `--server`, `--no-iconv`, `--protect-args`, etc. These
! 943: important options are not matched by wild-card, so they must be overridden
! 944: by their exact name. For instance, if you're forcing iconv transfers you
! 945: could use something like this:
! 946:
! 947: > refuse options = * no-iconv !a !v
! 948:
! 949: As an additional aid (beginning in 3.2.0), refusing (or "`!refusing`") the
! 950: "a" or "archive" option also affects all the options that the `--archive`
! 951: option implies (`-rdlptgoD`), but only if the option is matched explicitly
! 952: (not using a wildcard). If you want to do something tricky, you can use
! 953: "`archive*`" to avoid this side-effect, but keep in mind that no normal
! 954: rsync client ever sends the actual archive option to the server.
! 955:
! 956: As an additional safety feature, the refusal of "delete" also refuses
! 957: `remove-source-files` when the daemon is the sender; if you want the latter
! 958: without the former, instead refuse "`delete-*`" as that refuses all the
! 959: delete modes without affecting `--remove-source-files`. (Keep in mind that
! 960: the client's `--delete` option typically results in `--delete-during`.)
! 961:
! 962: When un-refusing delete options, you should either specify "`!delete*`" (to
! 963: accept all delete options) or specify a limited set that includes "delete",
! 964: such as:
! 965:
! 966: > refuse options = * !a !delete !delete-during
! 967:
! 968: ... whereas this accepts any delete option except `--delete-after`:
! 969:
! 970: > refuse options = * !a !delete* delete-after
! 971:
! 972: A note on refusing "compress" -- it is better to set the "dont compress"
! 973: daemon parameter to "`*`" because that disables compression silently
! 974: instead of returning an error that forces the client to remove the `-z`
! 975: option.
! 976:
! 977: If you are un-refusing the compress option, you probably want to match
! 978: "`!compress*`" so that you also accept the `--compress-level` option.
! 979:
! 980: Note that the "copy-devices" & "write-devices" options are refused by
! 981: default, but they can be explicitly accepted with "`!copy-devices`" and/or
! 982: "`!write-devices`". The options "log-file" and "log-file-format" are
! 983: forcibly refused and cannot be accepted.
! 984:
! 985: Here are all the options that are not matched by wild-cards:
! 986:
! 987: - `--server`: Required for rsync to even work.
! 988: - `--rsh`, `-e`: Required to convey compatibility flags to the server.
! 989: - `--out-format`: This is required to convey output behavior to a remote
! 990: receiver. While rsync passes the older alias `--log-format` for
! 991: compatibility reasons, this options should not be confused with
! 992: `--log-file-format`.
! 993: - `--sender`: Use "write only" parameter instead of refusing this.
! 994: - `--dry-run`, `-n`: Who would want to disable this?
! 995: - `--protect-args`, `-s`: This actually makes transfers safer.
! 996: - `--from0`, `-0`: Makes it easier to accept/refuse `--files-from` without
! 997: affecting this helpful modifier.
! 998: - `--iconv`: This is auto-disabled based on "charset" parameter.
! 999: - `--no-iconv`: Most transfers use this option.
! 1000: - `--checksum-seed`: Is a fairly rare, safe option.
! 1001: - `--write-devices`: Is non-wild but also auto-disabled.
! 1002:
! 1003: 0. `dont compress`
! 1004:
! 1005: This parameter allows you to select filenames based on wildcard patterns
! 1006: that should not be compressed when pulling files from the daemon (no
! 1007: analogous parameter exists to govern the pushing of files to a daemon).
! 1008: Compression can be expensive in terms of CPU usage, so it is usually good
! 1009: to not try to compress files that won't compress well, such as already
! 1010: compressed files.
! 1011:
! 1012: The "dont compress" parameter takes a space-separated list of
! 1013: case-insensitive wildcard patterns. Any source filename matching one of the
! 1014: patterns will be compressed as little as possible during the transfer. If
! 1015: the compression algorithm has an "off" level (such as zlib/zlibx) then no
! 1016: compression occurs for those files. Other algorithms have the level
! 1017: minimized to reduces the CPU usage as much as possible.
! 1018:
! 1019: See the `--skip-compress` parameter in the **rsync**(1) manpage for the
! 1020: list of file suffixes that are not compressed by default. Specifying a
! 1021: value for the "dont compress" parameter changes the default when the daemon
! 1022: is the sender.
! 1023:
! 1024: 0. `early exec`, `pre-xfer exec`, `post-xfer exec`
! 1025:
! 1026: You may specify a command to be run in the early stages of the connection,
! 1027: or right before and/or after the transfer. If the `early exec` or
! 1028: `pre-xfer exec` command returns an error code, the transfer is aborted
! 1029: before it begins. Any output from the `pre-xfer exec` command on stdout
! 1030: (up to several KB) will be displayed to the user when aborting, but is
! 1031: _not_ displayed if the script returns success. The other programs cannot
! 1032: send any text to the user. All output except for the `pre-xfer exec`
! 1033: stdout goes to the corresponding daemon's stdout/stderr, which is typically
! 1034: discarded. See the `--no-detatch` option for a way to see the daemon's
! 1035: output, which can assist with debugging.
! 1036:
! 1037: Note that the `early exec` command runs before any part of the transfer
! 1038: request is known except for the module name. This helper script can be
! 1039: used to setup a disk mount or decrypt some data into a module dir, but you
! 1040: may need to use `lock file` and `max connections` to avoid concurrency
! 1041: issues. If the client rsync specified the `--early-input=FILE` option, it
! 1042: can send up to about 5K of data to the stdin of the early script. The
! 1043: stdin will otherwise be empty.
! 1044:
! 1045: Note that the `post-xfer exec` command is still run even if one of the
! 1046: other scripts returns an error code. The `pre-xfer exec` command will _not_
! 1047: be run, however, if the `early exec` command fails.
! 1048:
! 1049: The following environment variables will be set, though some are specific
! 1050: to the pre-xfer or the post-xfer environment:
! 1051:
! 1052: - `RSYNC_MODULE_NAME`: The name of the module being accessed.
! 1053: - `RSYNC_MODULE_PATH`: The path configured for the module.
! 1054: - `RSYNC_HOST_ADDR`: The accessing host's IP address.
! 1055: - `RSYNC_HOST_NAME`: The accessing host's name.
! 1056: - `RSYNC_USER_NAME`: The accessing user's name (empty if no user).
! 1057: - `RSYNC_PID`: A unique number for this transfer.
! 1058: - `RSYNC_REQUEST`: (pre-xfer only) The module/path info specified by the
! 1059: user. Note that the user can specify multiple source files, so the
! 1060: request can be something like "mod/path1 mod/path2", etc.
! 1061: - `RSYNC_ARG#`: (pre-xfer only) The pre-request arguments are set in these
! 1062: numbered values. RSYNC_ARG0 is always "rsyncd", followed by the options
! 1063: that were used in RSYNC_ARG1, and so on. There will be a value of "."
! 1064: indicating that the options are done and the path args are beginning --
! 1065: these contain similar information to RSYNC_REQUEST, but with values
! 1066: separated and the module name stripped off.
! 1067: - `RSYNC_EXIT_STATUS`: (post-xfer only) the server side's exit value. This
! 1068: will be 0 for a successful run, a positive value for an error that the
! 1069: server generated, or a -1 if rsync failed to exit properly. Note that an
! 1070: error that occurs on the client side does not currently get sent to the
! 1071: server side, so this is not the final exit status for the whole transfer.
! 1072: - `RSYNC_RAW_STATUS`: (post-xfer only) the raw exit value from
! 1073: **waitpid()**.
! 1074:
! 1075: Even though the commands can be associated with a particular module, they
! 1076: are run using the permissions of the user that started the daemon (not the
! 1077: module's uid/gid setting) without any chroot restrictions.
! 1078:
! 1079: These settings honor 2 environment variables: use RSYNC_SHELL to set a
! 1080: shell to use when running the command (which otherwise uses your
! 1081: **system()** call's default shell), and use RSYNC_NO_XFER_EXEC to disable
! 1082: both options completely.
! 1083:
! 1084: # CONFIG DIRECTIVES
! 1085:
! 1086: There are currently two config directives available that allow a config file to
! 1087: incorporate the contents of other files: `&include` and `&merge`. Both allow
! 1088: a reference to either a file or a directory. They differ in how segregated the
! 1089: file's contents are considered to be.
! 1090:
! 1091: The `&include` directive treats each file as more distinct, with each one
! 1092: inheriting the defaults of the parent file, starting the parameter parsing as
! 1093: globals/defaults, and leaving the defaults unchanged for the parsing of the
! 1094: rest of the parent file.
! 1095:
! 1096: The `&merge` directive, on the other hand, treats the file's contents as if it
! 1097: were simply inserted in place of the directive, and thus it can set parameters
! 1098: in a module started in another file, can affect the defaults for other files,
! 1099: etc.
! 1100:
! 1101: When an `&include` or `&merge` directive refers to a directory, it will read in
! 1102: all the `*.conf` or `*.inc` files (respectively) that are contained inside that
! 1103: directory (without any recursive scanning), with the files sorted into alpha
! 1104: order. So, if you have a directory named "rsyncd.d" with the files "foo.conf",
! 1105: "bar.conf", and "baz.conf" inside it, this directive:
! 1106:
! 1107: > &include /path/rsyncd.d
! 1108:
! 1109: would be the same as this set of directives:
! 1110:
! 1111: > &include /path/rsyncd.d/bar.conf
! 1112: > &include /path/rsyncd.d/baz.conf
! 1113: > &include /path/rsyncd.d/foo.conf
! 1114:
! 1115: except that it adjusts as files are added and removed from the directory.
! 1116:
! 1117: The advantage of the `&include` directive is that you can define one or more
! 1118: modules in a separate file without worrying about unintended side-effects
! 1119: between the self-contained module files.
! 1120:
! 1121: The advantage of the `&merge` directive is that you can load config snippets
! 1122: that can be included into multiple module definitions, and you can also set
! 1123: global values that will affect connections (such as `motd file`), or globals
! 1124: that will affect other include files.
! 1125:
! 1126: For example, this is a useful /etc/rsyncd.conf file:
! 1127:
! 1128: > port = 873
! 1129: > log file = /var/log/rsync.log
! 1130: > pid file = /var/lock/rsync.lock
! 1131: >
! 1132: > &merge /etc/rsyncd.d
! 1133: > &include /etc/rsyncd.d
! 1134:
! 1135: This would merge any `/etc/rsyncd.d/*.inc` files (for global values that should
! 1136: stay in effect), and then include any `/etc/rsyncd.d/*.conf` files (defining
! 1137: modules without any global-value cross-talk).
! 1138:
! 1139: # AUTHENTICATION STRENGTH
! 1140:
! 1141: The authentication protocol used in rsync is a 128 bit MD4 based challenge
! 1142: response system. This is fairly weak protection, though (with at least one
! 1143: brute-force hash-finding algorithm publicly available), so if you want really
! 1144: top-quality security, then I recommend that you run rsync over ssh. (Yes, a
! 1145: future version of rsync will switch over to a stronger hashing method.)
! 1146:
! 1147: Also note that the rsync daemon protocol does not currently provide any
! 1148: encryption of the data that is transferred over the connection. Only
! 1149: authentication is provided. Use ssh as the transport if you want encryption.
! 1150:
! 1151: You can also make use of SSL/TLS encryption if you put rsync behind an
! 1152: SSL proxy.
! 1153:
! 1154: # SSL/TLS Daemon Setup
! 1155:
! 1156: When setting up an rsync daemon for access via SSL/TLS, you will need to
! 1157: configure a proxy (such as haproxy or nginx) as the front-end that handles the
! 1158: encryption.
! 1159:
! 1160: - You should limit the access to the backend-rsyncd port to only allow the
! 1161: proxy to connect. If it is on the same host as the proxy, then configuring
! 1162: it to only listen on localhost is a good idea.
! 1163: - You should consider turning on the `proxy protocol` parameter if your proxy
! 1164: supports sending that information. The examples below assume that this is
! 1165: enabled.
! 1166:
! 1167: An example haproxy setup is as follows:
! 1168:
! 1169: > ```
! 1170: > frontend fe_rsync-ssl
! 1171: > bind :::874 ssl crt /etc/letsencrypt/example.com/combined.pem
! 1172: > mode tcp
! 1173: > use_backend be_rsync
! 1174: >
! 1175: > backend be_rsync
! 1176: > mode tcp
! 1177: > server local-rsync 127.0.0.1:873 check send-proxy
! 1178: > ```
! 1179:
! 1180: An example nginx proxy setup is as follows:
! 1181:
! 1182: > ```
! 1183: > stream {
! 1184: > server {
! 1185: > listen 874 ssl;
! 1186: > listen [::]:874 ssl;
! 1187: >
! 1188: > ssl_certificate /etc/letsencrypt/example.com/fullchain.pem;
! 1189: > ssl_certificate_key /etc/letsencrypt/example.com/privkey.pem;
! 1190: >
! 1191: > proxy_pass localhost:873;
! 1192: > proxy_protocol on; # Requires "proxy protocol = true"
! 1193: > proxy_timeout 1m;
! 1194: > proxy_connect_timeout 5s;
! 1195: > }
! 1196: > }
! 1197: > ```
! 1198:
! 1199: # EXAMPLES
! 1200:
! 1201: A simple rsyncd.conf file that allow anonymous rsync to a ftp area at
! 1202: `/home/ftp` would be:
! 1203:
! 1204: > ```
! 1205: > [ftp]
! 1206: > path = /home/ftp
! 1207: > comment = ftp export area
! 1208: > ```
! 1209:
! 1210: A more sophisticated example would be:
! 1211:
! 1212: > ```
! 1213: > uid = nobody
! 1214: > gid = nobody
! 1215: > use chroot = yes
! 1216: > max connections = 4
! 1217: > syslog facility = local5
! 1218: > pid file = /var/run/rsyncd.pid
! 1219: > slp refresh = 3600
! 1220: >
! 1221: > [ftp]
! 1222: > path = /var/ftp/./pub
! 1223: > comment = whole ftp area (approx 6.1 GB)
! 1224: >
! 1225: > [sambaftp]
! 1226: > path = /var/ftp/./pub/samba
! 1227: > comment = Samba ftp area (approx 300 MB)
! 1228: >
! 1229: > [rsyncftp]
! 1230: > path = /var/ftp/./pub/rsync
! 1231: > comment = rsync ftp area (approx 6 MB)
! 1232: >
! 1233: > [sambawww]
! 1234: > path = /public_html/samba
! 1235: > comment = Samba WWW pages (approx 240 MB)
! 1236: >
! 1237: > [cvs]
! 1238: > path = /data/cvs
! 1239: > comment = CVS repository (requires authentication)
! 1240: > auth users = tridge, susan
! 1241: > secrets file = /etc/rsyncd.secrets
! 1242: > ```
! 1243:
! 1244: The /etc/rsyncd.secrets file would look something like this:
! 1245:
! 1246: > tridge:mypass
! 1247: > susan:herpass
! 1248:
! 1249: # FILES
! 1250:
! 1251: /etc/rsyncd.conf or rsyncd.conf
! 1252:
! 1253: # SEE ALSO
! 1254:
! 1255: **rsync**(1), **rsync-ssl**(1)
! 1256:
! 1257: # BUGS
! 1258:
! 1259: Please report bugs! The rsync bug tracking system is online at
! 1260: <https://rsync.samba.org/>.
! 1261:
! 1262: # VERSION
! 1263:
! 1264: This man page is current for version @VERSION@ of rsync.
! 1265:
! 1266: # CREDITS
! 1267:
! 1268: rsync is distributed under the GNU General Public License. See the file
! 1269: COPYING for details.
! 1270:
! 1271: The primary ftp site for rsync is <ftp://rsync.samba.org/pub/rsync>
! 1272:
! 1273: A web site is available at <https://rsync.samba.org/>.
! 1274:
! 1275: We would be delighted to hear from you if you like this program.
! 1276:
! 1277: This program uses the zlib compression library written by Jean-loup Gailly and
! 1278: Mark Adler.
! 1279:
! 1280: # THANKS
! 1281:
! 1282: Thanks to Warren Stanley for his original idea and patch for the rsync daemon.
! 1283: Thanks to Karsten Thygesen for his many suggestions and documentation!
! 1284:
! 1285: # AUTHOR
! 1286:
! 1287: rsync was written by Andrew Tridgell and Paul Mackerras. Many people have
! 1288: later contributed to it.
! 1289:
! 1290: Mailing lists for support and development are available at
! 1291: <https://lists.samba.org/>.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rsyncd.conf.5.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync