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