RSYNCD.CONF(5) File Formats Manual RSYNCD.CONF(5)

rsyncd.conf — configuration format for the rsync daemon

When the rsync(1) --daemon mode starts up, it first reads its global configuration from a file located by default at /etc/rsyncd.conf, unless the --config option is specified to direct rsync(1) to look elsewhere. In this first pass of reading rsyncd.conf, only the leading global configuration is read. rsyncd.conf is read once again when a client connects to the daemon, this time loading module parameters specified later in the file.

rsyncd.conf files bare close resemblance to the commonly-found INI file format. Unless otherwise noted, leading whitespace on lines is not significant and will be ignored.

Comments are supported on their own lines, and begin with a ‘#’ character.

A line containing a declaration like “[module]” indicates that the following lines belong to the module named between the square brackets. Leading and trailing whitespace in the module name are stripped. Internal whitespace is collapsed down to or transformed into a single space character. Multiple sections for a module are merged together as one would expect.

Assignments are lines that look like “key = value”, where the key is everything before a ‘=’, and the value may contain spaces or ‘=’ characters unescaped. Quotation marks are used literally in the value configured, not interpreted in any special way. The value may span multiple lines by "escaping" the newline with a \ character at the end.

Value assignments that occur before any module section are global options, which may influence how the rsync(1) starts up or provide default values for module parameters described later. rsyncd.conf supports sections named “global”, which may also provide default values for module parameters.

The following keys may be assigned before any module sections, and will influence rsync(1) daemon startup:

“address”
Provides an address to bind the listening socket to, if not otherwise specified by the --address option to rsync(1). By default, rsync(1) will bind to any address on the system.
“motd file”
Names a file containing a MOTD that will be printed to clients as they connect to the rsync(1) daemon. This file will be read every time a client is connected, so a daemon restart is not required to update the MOTD.
“pid file”
Names a file to write the rsync(1) pid to. This file will be locked while the daemon is still running, preventing other daemons configured to use the same pid file from starting.
“port”
Provides a port to bind the listening socket to, if not otherwise specified by the --port option to rsync(1). By default, rsync(1) will bind to the “rsync” port as described in /etc/services, which is traditionally port 873.
“socket options”
Defines socket options to set on both the listening socket and accepted client sockets, unless overridden by the --sockopts option to rsync(1).

The following keys may be assigned within module sections declared in rsyncd.conf:

“auth users”
Names the users and/or groups authorized to authenticate and use the module, along with an optional policy option per entry. If a name entry begins with a “@”, then the entry describes a group and the username presented must be a member of the named group on the system. An optional policy option may be specified by appending a “:” followed by one of “deny”, “rw”, or “ro”. The latter two options will override the “read only” option described later, if specified. The first rule matched is used, so care must be taken to ensure that entries appear in the order of desired precedence.

When a username is presented, the “secrets file” is consulted for the secret to authenticate with.

“comment”
Comment to use when a module listing is requested.
“dont compress”
This option is accepted for compatibility with the reference rsync, but it has no effect in openrsync. Traditionally, the value of “dont compress” is a space delimited list of patterns describing filenames that should not be compressed.

In earlier versions of rsync, only zlib is supported for compression and per-file compression levels cannot be set. The first file matching a pattern in this list could inadvertently disable compression for the entire transfer rather than just the already-compressed files. This implementation chose to favor lower bandwidth over potentially wasted CPU cycles for the time being.

“exclude”, “exclude from”, “filter”, “include”, “include from”
These options correspond to the rsync command-line option equivalents. The “exclude”, “filter”, and “include” values are space-separated, and may contain a leading “- ” or “+ ” to specify the rule and, e.g., get rule ordering correct. These rules take precedence over any client-specified rules.
“gid”, “uid”
The group and user names or IDs to use for transfer processes. Once a client connected, privileges are dropped as soon as we possibly can before the transfer begins.
“hosts allow”, “hosts deny”
Specifies a list of host patterns that are either allowed or denied from using the module. Incoming connections must match at least one of the “hosts allow” patterns, if specified. Conversely, incoming connections must not match any “hosts deny” pattern, if specified. If both options are specified, then the “hosts allow” rule is processed first, followed by a potential rejection if the allowed host matches one of the “hosts deny” patterns.

The pattern may be:

  • A single IPv4 or IPv6 address
  • address/<mask> or address/<mask address> notation
  • Hostname with optional wildcards, which are processed with the internal pattern matching engine that functions much like fnmatch(3). Hostnames are matched against a reverse lookup of the client when it initially connects.
“ignore errors”
Functionally equivalent to the --ignore-errors option to rsync(1).
“ignore nonreadable”
Instructs rsync(1) to completely ignore files that it can't read from the module path. This may be useful for, e.g., a public archive that has mixed ownership.
“incoming chmod”, “outgoing chmod”
Functionally equivalent to splitting the --chmod option to rsync(1) into sender and receiver chmod options. Resulting incoming or outgoing files are given the requested mode.
“list”
Indicates if the module will be named when a listing is requested. This defaults to true, making all modules visible to any connected rsync client that requests a listing.
“lock file”
Names the path on the filesystem that rsync(1) will use for counting connections towards the
“log file”
Names a path on the filesystem to use instead of syslog for logging. If the value is not set, empty, or we fail to open the logfile, then rsync(1) will fallback to using syslog anyways.
“log format”
Functionally equivalent to the --out-format option to rsync(1). “max connections” limit. Segments of this file will be rangelocked with fcntl(2) F_SETLK as needed to determine if we have any connection slots left open to grant.
“max connections”
Limit number of connections to the module at any given time to the named number. This is enforced using a range lock on the “lock file”.
“max verbosity”
Specifies the max amount of verbosity that a client can request when it connects. Defaults to 1, to allow at most a single -v.
“munge symlinks”
Munges symlinks received or sent by the daemon as appropriate to render them safe to follow. If this option is enabled, then rsync(1) will prepend /rsyncd-munge/ to the target of any symlink received. For symlinks sent, it will strip the /rsyncd-munge/ prefix to restore the symlink's target.

If this option is disabled and “chroot” is also disabled, then symlinks may be irreversibly damaged to render them safe for the daemon. Notably, any path components that may cause rsync(1) to traverse outside of the module path will be stripped.

This option is enabled by default when “chroot” is disabled.

“numeric ids”
Nearly functionally equivalent to the --numeric-ids option to rsync(1). When operating in a chroot, “numeric ids” will be silently enabled on the daemon-side.
“path”
Names the path on the filesystem that rsync(1) will serve files for this module from.
“pre-xfer exec”, “post-xfer exec”
Commands to execute before and after the transfer. rsync(1) will not do any word-splitting of these options. The following environment variables will be available to the execution environment:
The name of the requested module.
The “path” for the requested module.
The client's network address.
The client's host name, as determined from a reverse DNS lookup.
The username the client has sent along for authentication purposes.
The PID of the process that will be handling or did handle the transfer.
Only available for “pre-xfer exec”, each of the arguments provided by the client are passed in via the environment. RSYNC_ARG0 will be set to “rsyncd” by convention. Options are terminated by a single “”., after which paths will be present. Paths will have the module/ part stripped.
Only available for “pre-xfer exec”, this essentially contains the entirety of the path portion of the arguments as they were sent by the client, with the module/ prefix left intact if provided.
Only available for “post-xfer exec”, the raw numeric exit status of the process that handled the transfer. This includes any flag bits set that may indicate, e.g., that the process was terminated by signal.
Only available for “post-xfer exec”, this is the exit status of the child if it did terminate normally. For abnormal termination, -1 will be passed as the exit status.
“read only”
Indicates whether the module is read only or not. This is only checked when a client attempts to send a file to the rsync(1) daemon. This is enabled by default.
“refuse options”
Options to refuse from the client, if provided. Refused options cause the rsync(1) daemon to abort the operation before any files are transferred. Options are provided as a space delimited list of patterns to refuse. These patterns, like those used in filter rules and the above “hosts allow” and “hosts deny”, are simple patterns that support globbing as in fnmatch(3). The pattern may match either the short option name or the long option name for a given option

Refusing the -a option will refuse all of the options that make up the -a option, unless the option is matched by wildcard. Refusing any component of -a will also refuse the -a option.

Refusing “delete” will also implicitly refuse --remove-source-files.

“secrets file”
Names the path on the filesystem that rsync(1) will use to authenticate users if “auth users” is set. The secrets file consists of “username:password” pairs, one per line, and supports comments on lines starting with “#”. The username specified in the secrets file may also start with a “@” to name a group.

Note that rsync(1) will ensure that the file is not other-readable, unless “strict modes” is disabled. Strict mode violations, along with syntax errors, will effectively disable a module that has set “auth users”.

“strict modes”
Instructs rsync(1) to enforce stricter modes on the secrets file. Namely, the secrets file must not be other-readable. This is enabled by default.
“syslog facility”
The syslog facility to use when rsync(1) writes to the syslog. Defaults to “daemon”.
“timeout”
Functionally equivalent to the --timeout option to rsync(1).
“transfer logging”
Enable FTP-style logging of the transactions that take place during this transfer. The relevant log lines honor the format specified by the “log format” option, which defaults to “%o %h [%a] %m (%u) %f %l” for “transfer logging” purposes.

This option is disabled by default.

“use chroot”
Boolean value describing whether rsync(1) should chroot(2) itself into the named “path”. By default, rsync(1) will attempt to chroot(2), but if it fails due to EPERM then it will proceed anyways. This fallback does not happen if “use chroot” is explicitly set to true in rsyncd.conf.
“write only”
Indicates whether the module is write only or not. This is only checked when a client attempts to send a file to the rsync(1) daemon. This is disabled by default.

“path” is the only required field for a module.

A basic configuration for the rsync(1) daemon to listen on *:9998 serving files out of /var/ftp/pub:

# These settings affect rsync(1) startup
port = 9998
motd file = /etc/rsync.motd

[ftp]
  # This is only used when the 'ftp' module is requested
  path = /var/ftp/pub

Listen on the usual port, serving files out of the same directory as above:

# This also affects all modules
use chroot = yes

# Alternative spelling of the above:
#[global]
#  use chroot = yes

[ftp]
  path = /var/ftp/pub

Syntax errors in rsyncd.conf that occur at or after the first module declaration will not be detected until a client has attempted to connect.

Module names are case sensitive when requested by the client, but are not case sensitive when specified in rsyncd.conf. The client may request a module by the casing used in the first appearance of the module, not by any casing used in subsequent sections describing the same module.

Line continuation escapes using \ at the end of a line are only recognized as continuations if they occur in the middle of a value assignment.

Leading whitespace in a value is insignificant as long as it occurs on the same line as the =. Whitespace on the next line, whether a significant character in the value was written on the previous line or not, is significant and will appear in the value.

rsyncd.conf supports sections named “global” to define global defaults for some values, but this name is somewhat misleading as they are not read in for rsync(1) daemon startup. As such, global options like “port” or “pid file” appearing in a “[global]” section will not affect the rsync(1) daemon startup.

February 21, 2025 Mac OS X 14