embedaddon/rsync/rsyncd.conf.5.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / rsyncd.conf.5.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Wed Mar 17 00:32:36 2021 UTC (3 years, 3 months ago) by misho
Branches: rsync, MAIN
CVS tags: v3_2_3, HEAD

rsync 3.2.3

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: rsyncd.conf -⁠ configuration file for rsync in daemon mode 31: <h1>SYNOPSIS</h1> 32: rsyncd.conf 33: <h1>DESCRIPTION</h1> 34: The rsyncd.conf file is the runtime configuration file for rsync when run as an 35: rsync daemon. 36: The rsyncd.conf file controls authentication, access, logging and available 37: modules. 38: <h1>FILE FORMAT</h1> 39: 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>. 42: The file is line-based -⁠-⁠ that is, each newline-terminated line represents 43: either a comment, a module name or a parameter. 44: 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. 49: Any line beginning 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.) 52: Any line ending in a <code>\</code> is "continued" on the next line in the customary UNIX 53: fashion. 54: 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. 57: <h1>LAUNCHING THE RSYNC DAEMON</h1> 58: The rsync daemon is launched by specifying the <code>--daemon</code> option to 59: rsync. 60: 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. 64: 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. 67: When run via inetd you should add a line like this to /etc/services: 68: <blockquote> 69: <pre><code>rsync 873/tcp 70: </code></pre> 71: </blockquote> 72: and a single line something like this to /etc/inetd.conf: 73: <blockquote> 74: <pre><code>rsync stream tcp nowait root /usr/bin/rsync rsyncd --daemon 75: </code></pre> 76: </blockquote> 77: 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. 80: Note that you should not 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. 82: <h1>GLOBAL PARAMETERS</h1> 83: 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). 87: 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. 90: 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 %%. 101: <dl> 102: 103: <dt><code>motd file</code></dt><dd> 104: 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. 108: </dd> 109: 110: <dt><code>pid file</code></dt><dd> 111: 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. 114: The filename can be overridden by the <code>--dparam=pidfile=FILE</code> command-line 115: option when starting the daemon. 116: </dd> 117: 118: <dt><code>port</code></dt><dd> 119: 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. 122: </dd> 123: 124: <dt><code>address</code></dt><dd> 125: 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. 128: </dd> 129: 130: <dt><code>socket options</code></dt><dd> 131: 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: setsockopt() 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. 137: </dd> 138: 139: <dt><code>listen backlog</code></dt><dd> 140: You can override the default backlog value when the daemon listens for 141: connections. It defaults to 5. 142: </dd> 143: 144: <dt><code>use slp</code></dt><dd> 145: You can enable Service Location Protocol support by enabling this global 146: parameter. The default is "false". 147: </dd> 148: 149: <dt><code>slp refresh</code></dt><dd> 150: 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. 157: </dd> 158: </dl> 159: <h1>MODULE PARAMETERS</h1> 160: 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). 168: 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. 170: <dl> 171: 172: <dt><code>comment</code></dt><dd> 173: 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. 176: </dd> 177: 178: <dt><code>path</code></dt><dd> 179: 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>. 182: 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: 186: <blockquote> 187: <pre><code>path = /home/%RSYNC_USER_NAME% 188: </code></pre> 189: </blockquote> 190: 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. 195: </dd> 196: 197: <dt><code>use chroot</code></dt><dd> 198: 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). 205: 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 "/". 216: 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). 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 <code>numeric ids = false</code> for rsync to do name 230: lookups. 231: 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. 236: </dd> 237: 238: <dt><code>daemon chroot</code></dt><dd> 239: 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. 247: </dd> 248: 249: <dt><code>proxy protocol</code></dt><dd> 250: 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. 253: 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. 258: CAUTION: 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. 265: 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. 268: </dd> 269: 270: <dt><code>name converter</code></dt><dd> 271: 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. 276: 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 or you can do 278: customized conversions. 279: 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. 283: 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. 286: </dd> 287: 288: <dt><code>numeric ids</code></dt><dd> 289: 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. 297: A chroot-enabled module should not have this parameter set to false unless 298: you're using a "name converter" program or 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. 301: </dd> 302: 303: <dt><code>munge symlinks</code></dt><dd> 304: 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. 310: 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). 315: 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. 322: 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. 330: 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. 336: </dd> 337: 338: <dt><code>charset</code></dt><dd> 339: 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". 347: 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. 350: </dd> 351: 352: <dt><code>max connections</code></dt><dd> 353: 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. 358: </dd> 359: 360: <dt><code>link by hash dir</code></dt><dd> 361: When the "link by hash dir" parameter is set to a non-empty string, 362: received files will be hard linked into DIR, a link farm arranged by 363: MD5 file hash. See the <code>--link-by-hash</code> option for a full explanation. 364: The DIR 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. 369: If this parameter is set, it will disable the <code>--link-by-hash</code> command-line 370: option for copies into the module. 371: </dd> 372: </dl> 373: The default is for this parameter to be unset. 374: <dl> 375: 376: <dt><code>log file</code></dt><dd> 377: 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 syslog() 380: doesn't work for chrooted programs. The file is opened before chroot() 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. 384: 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.) 387: 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. 392: </dd> 393: 394: <dt><code>syslog facility</code></dt><dd> 395: 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). 403: </dd> 404: 405: <dt><code>syslog tag</code></dt><dd> 406: 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). 410: For example, if you wanted each authenticated user's name to be included in 411: the syslog tag, you could do something like this: 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: 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. 423: 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. 430: </dd> 431: 432: <dt><code>lock file</code></dt><dd> 433: 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>. 437: </dd> 438: 439: <dt><code>checksum files</code></dt><dd> 440: 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. 445: 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. 451: </dd> 452: 453: <dt><code>read only</code></dt><dd> 454: 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. 458: Note that "auth users" can override this setting on a per-user basis. 459: </dd> 460: 461: <dt><code>write only</code></dt><dd> 462: 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. 467: Helpful hint: you probably want to specify "refuse options = delete" for a 468: write-only module. 469: </dd> 470: 471: <dt><code>open noatime</code></dt><dd> 472: 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. 479: When set to False, this parameters ensures that files on the server are not 480: opened with O_NOATIME. 481: When set to Unset (the default) the user controls the setting via 482: <code>--open-noatime</code>. 483: </dd> 484: 485: <dt><code>list</code></dt><dd> 486: 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. 494: </dd> 495: 496: <dt><code>uid</code></dt><dd> 497: 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. 503: 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: 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: 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). 524: 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. 529: </dd> 530: 531: <dt><code>daemon uid</code></dt><dd> 532: 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. 535: </dd> 536: 537: <dt><code>daemon gid</code></dt><dd> 538: 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. 541: </dd> 542: 543: <dt><code>fake super</code></dt><dd> 544: 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. 548: </dd> 549: 550: <dt><code>filter</code></dt><dd> 551: 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. 560: 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 must 564: exclude everything in the subtree; the easiest way to do this is with a 565: triple-star pattern like "<code>/secret/***</code>". 566: 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. 576: </dd> 577: 578: <dt><code>exclude</code></dt><dd> 579: 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. 584: </dd> 585: 586: <dt><code>include</code></dt><dd> 587: 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. 590: </dd> 591: 592: <dt><code>exclude from</code></dt><dd> 593: 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. 599: </dd> 600: 601: <dt><code>include from</code></dt><dd> 602: 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. 605: </dd> 606: 607: <dt><code>incoming chmod</code></dt><dd> 608: 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 chmod(1) 614: manpage for information on the format of this string. 615: </dd> 616: 617: <dt><code>outgoing chmod</code></dt><dd> 618: 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 chmod(1) manpage for information 625: on the format of this string. 626: </dd> 627: 628: <dt><code>auth users</code></dt><dd> 629: 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"). 640: 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. 645: 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. 649: 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: 652: <blockquote> 653: <pre><code>auth users = joe:deny @guest:deny admin:rw @rsync:ro susan joe sam 654: </code></pre> 655: </blockquote> 656: 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. 664: 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: 668: <blockquote> 669: <pre><code>auth users = , joe:deny, @Some Group:deny, admin:rw, @RO Group:ro 670: </code></pre> 671: </blockquote> 672: 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. 676: See also the section entitled "USING RSYNC-DAEMON FEATURES VIA A REMOTE 677: SHELL CONNECTION" in rsync(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. 680: </dd> 681: 682: <dt><code>secrets file</code></dt><dd> 683: 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. 692: 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. 696: 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. 700: 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. 704: </dd> 705: 706: <dt><code>strict modes</code></dt><dd> 707: 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. 713: </dd> 714: 715: <dt><code>hosts allow</code></dt><dd> 716: 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. 720: Each pattern can be in one of six forms: 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: Note IPv6 link-local addresses can have a scope in the address 744: specification: 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: 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. 757: The default is no "hosts allow" parameter, which means all hosts can 758: connect. 759: </dd> 760: 761: <dt><code>hosts deny</code></dt><dd> 762: 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. 766: The default is no "hosts deny" parameter, which means all hosts can 767: connect. 768: </dd> 769: 770: <dt><code>reverse lookup</code></dt><dd> 771: 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. 777: 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. 781: </dd> 782: 783: <dt><code>forward lookup</code></dt><dd> 784: 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. 788: </dd> 789: 790: <dt><code>ignore errors</code></dt><dd> 791: 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. 797: </dd> 798: 799: <dt><code>ignore nonreadable</code></dt><dd> 800: 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. 804: </dd> 805: 806: <dt><code>transfer logging</code></dt><dd> 807: 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. 811: If you want to customize the log lines, see the "log format" parameter. 812: </dd> 813: 814: <dt><code>log format</code></dt><dd> 815: 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>"). 826: 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.) 830: The single-character escapes that are understood are as follows: 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: 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. 863: 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. 866: </dd> 867: 868: <dt><code>timeout</code></dt><dd> 869: 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). 874: </dd> 875: 876: <dt><code>refuse options</code></dt><dd> 877: 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 "!". 882: When an option is refused, the daemon prints an error message and exits. 883: For example, this would refuse <code>--checksum</code> (<code>-c</code>) and all the various 884: delete options: 885: <blockquote> 886: <pre><code>refuse options = c delete 887: </code></pre> 888: </blockquote> 889: 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. 891: The use of a negated match allows you to fine-tune your refusals after a 892: wild-card, such as this: 893: <blockquote> 894: <pre><code>refuse options = delete-* !delete-during 895: </code></pre> 896: </blockquote> 897: 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: 901: <blockquote> 902: <pre><code>refuse options = * !a !v !compress* 903: </code></pre> 904: </blockquote> 905: 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: 910: <blockquote> 911: <pre><code>refuse options = * no-iconv !a !v 912: </code></pre> 913: </blockquote> 914: 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. 920: 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>.) 925: 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: 928: <blockquote> 929: <pre><code>refuse options = * !a !delete !delete-during 930: </code></pre> 931: </blockquote> 932: ... whereas this accepts any delete option except <code>--delete-after</code>: 933: <blockquote> 934: <pre><code>refuse options = * !a !delete* delete-after 935: </code></pre> 936: </blockquote> 937: 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. 941: 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. 943: 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. 947: Here are all the options that are not matched by wild-cards: 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: 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. 974: 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. 980: See the <code>--skip-compress</code> parameter in the rsync(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. 984: </dd> 985: 986: <dt><code>early exec</code>, <code>pre-xfer exec</code>, <code>post-xfer exec</code></dt><dd> 987: 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: not 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. 997: 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. 1004: 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 not 1006: be run, however, if the <code>early exec</code> command fails. 1007: The following environment variables will be set, though some are specific 1008: to the pre-xfer or the post-xfer environment: 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: waitpid().</li> 1032: </ul> 1033: 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. 1036: 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: system() call's default shell), and use RSYNC_NO_XFER_EXEC to disable 1039: both options completely. 1040: </dd> 1041: </dl> 1042: <h1>CONFIG DIRECTIVES</h1> 1043: 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. 1047: 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. 1051: 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. 1055: 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: 1060: <blockquote> 1061: <pre><code>&include /path/rsyncd.d 1062: </code></pre> 1063: </blockquote> 1064: would be the same as this set of directives: 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: except that it adjusts as files are added and removed from the directory. 1072: 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. 1075: 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. 1079: For example, this is a useful /etc/rsyncd.conf file: 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: 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). 1092: <h1>AUTHENTICATION STRENGTH</h1> 1093: 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.) 1098: 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. 1101: You can also make use of SSL/TLS encryption if you put rsync behind an 1102: SSL proxy. 1103: <h1>SSL/TLS Daemon Setup</h1> 1104: 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. 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: An example haproxy setup is as follows: 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: An example nginx proxy setup is as follows: 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: A simple rsyncd.conf file that allow anonymous rsync to a ftp area at 1147: <code>/home/ftp</code> would be: 1148: <blockquote> 1149: <pre><code>[ftp] 1150: path = /home/ftp 1151: comment = ftp export area 1152: </code></pre> 1153: </blockquote> 1154: A more sophisticated example would be: 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: The /etc/rsyncd.secrets file would look something like this: 1188: <blockquote> 1189: <pre><code>tridge:mypass 1190: susan:herpass 1191: </code></pre> 1192: </blockquote> 1193: <h1>FILES</h1> 1194: /etc/rsyncd.conf or rsyncd.conf 1195: <h1>SEE ALSO</h1> 1196: rsync(1), rsync-ssl(1) 1197: <h1>BUGS</h1> 1198: Please report bugs! The rsync bug tracking system is online at 1199: <a href="https://rsync.samba.org/">https://rsync.samba.org/</a>. 1200: <h1>VERSION</h1> 1201: This man page is current for version 3.2.3 of rsync. 1202: <h1>CREDITS</h1> 1203: rsync is distributed under the GNU General Public License. See the file 1204: COPYING for details. 1205: The primary ftp site for rsync is <a href="ftp://rsync.samba.org/pub/rsync">ftp://rsync.samba.org/pub/rsync</a> 1206: A web site is available at <a href="https://rsync.samba.org/">https://rsync.samba.org/</a>. 1207: We would be delighted to hear from you if you like this program. 1208: This program uses the zlib compression library written by Jean-loup Gailly and 1209: Mark Adler. 1210: <h1>THANKS</h1> 1211: 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! 1213: <h1>AUTHOR</h1> 1214: rsync was written by Andrew Tridgell and Paul Mackerras. Many people have 1215: later contributed to it. 1216: Mailing lists for support and development are available at 1217: <a href="https://lists.samba.org/">https://lists.samba.org/</a>. 1218: <div style="float: right">06 Aug 2020</div> 1219: </body></html>