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