- Avoid a hang when an overabundance of messages clogs up all the I/O buffers.
- - Fixed a mismatch in the RSYNC_PID values when running both a `pre-xfer exec`
- and a `post-xfer exec`.
+ - Fixed a mismatch in the RSYNC_PID values put into the environment of
+ `pre-xfer exec` and a `post-xfer exec`.
- Fixed a crash in the `--iconv` code.
- Made -V the short option for --version.
- Forward -4 & -6 options to the ssh command, making them easier to type than
- "--rsh='ssh -4'" (or -6).
+ `--rsh='ssh -4'` (or -6).
### PACKAGING RELATED:
- Add installed man page: /usr/man/man1/rsync-ssl.1
- - Some "readme" files have changed names to be .md files, such as: README.md,
+ - Some readme files have changed names to be .md files, such as: README.md,
INSTALL.md, NEWS.md, & OLDNEWS.md.
- The rsync-ssl script wants to run either openssl or stunnel4, so consider
that hasn't really been created.
- Fixed a problem with `--compress` (`-z`) where the receiving side could
- return the error `inflate (token) returned `-5``.
+ return the error "inflate (token) returned -5".
- Fixed a bug where `--delete-during` could delete in a directory before it
noticed that the sending side sent an I/O error for that directory (both
- An absolute-path filter rule (i.e. with a '/' modifier) no longer loses its
modifier when sending the filter rules to the remote rsync.
- - Improved the `--delete does not work without -r or -d` message.
+ - Improved the "--delete does not work without -r or -d" message.
- Improved rsync's handling of `--timeout` to avoid a weird timeout case where
the sender could timeout even though it has recently written data to the
either turn off `-d` (`--no-d`), or specify `-r --exclude='/*/*'` manually.
- In `--dry-run` mode, the last line of the verbose summary text is output
- with a `(DRY RUN)` suffix to help remind you that no updates were made.
+ with a "(DRY RUN)" suffix to help remind you that no updates were made.
Similarly, `--only-write-batch` outputs `(BATCH ONLY)`.
- A writable rsync daemon with `use chroot` disabled now defaults to a
- Using `--only-write-batch` to a daemon receiver now works properly (older
versions would update some files while writing the batch).
- - Avoid outputting a `file has vanished` message when the file is a broken
+ - Avoid outputting a "file has vanished" message when the file is a broken
symlink and `--copy-unsafe-links` or `--copy-dirlinks` is used (the code
already handled this for `--copy-links`).
- Added the `--skip-compress=LIST` option to override the default list of file
suffixes that will not be compressed when using `--compress` (`-z`).
- - The daemon's default for `dont compress` was extended to include: `*.7z
- *.mp[34] *.mov *.avi *.ogg *.jpg *.jpeg` The name-matching routine was also
+ - The daemon's default for `dont compress` was extended to include: `*.7z`
+ `*.mp[34]` `*.mov` `*.avi` `*.ogg` `*.jpg` `*.jpeg` and the name-matching routine was also
optimized to run more quickly.
- The `--max-delete` option now outputs a warning if it skipped any file
- Removed the unused function `write_int_named()`, the unused variable
`io_read_phase`, and the rarely used variable `io_write_phase`. This also
- elides the confusing `phase "unknown"` part of one error message.
+ elides the confusing 'phase "unknown"' part of one error message.
- Removed two unused configure checks and two related (also unused)
compatibility functions.
int64` in rsync.h.
- Fixed problem on systems such as Sunos4 that do not support realloc on a
- NULL pointer; error was `out of memory in "flist_expand"`.
+ NULL pointer; error was 'out of memory in "flist_expand"'.
- Fix for rsync server processes hanging around after the client unexpectedly
disconnects. (Colin Walters) (Debian bug #128632)
- `--statistics` now shows memory heap usage on platforms that support
mallinfo().
- - `The Ted T'so school of program optimization`: make progress visible and
+ - "The Ted T'so school of program optimization": make progress visible and
people will think it's faster. (With `--progress`, rsync will show you how
many files it has seen as it builds the `file_list`, giving some indication
that it has not hung.)
to this latter rule).
As a special case, if a single source arg is specified without a destination,
-the files are listed in an output format similar to "ls -l".
+the files are listed in an output format similar to "`ls -l`".
As expected, if neither the source or destination path specify a remote host,
the copy occurs locally (see also the `--list-only` option).
-Rsync refers to the local side as the "client" and the remote side as the
-"server". Don't confuse "server" with an rsync daemon -- a daemon is always a
-server, but a server can be either a daemon or a remote-shell spawned process.
+Rsync refers to the local side as the client and the remote side as the server.
+Don't confuse server with an rsync daemon. A daemon is always a server, but a
+server can be either a daemon or a remote-shell spawned process.
# SETUP
This would recursively transfer all files from the directory src/bar on the
machine foo into the /data/tmp/bar directory on the local machine. The files
-are transferred in "archive" mode, which ensures that symbolic links, devices,
+are transferred in archive mode, which ensures that symbolic links, devices,
attributes, permissions, ownerships, etc. are preserved in the transfer.
Additionally, compression will be used to reduce the size of data portions of
the transfer.
0. `--help`, `-h` `(*)`
Print a short help page describing the options available in rsync and exit.
- For backward-compatibility with older versions of rsync, the help will also
- be output if you use the `-h` option without any other args.
+ (*) The `-h` short option will only invoke `--help` when used without other
+ options since it normally means `--human-readable`.
0. `--version`, `-V`
and `--debug` have a way to ask for help that tells you exactly what flags
are set for each increase in verbosity.
- However, do keep in mind that a daemon's "max verbosity" setting will limit
+ However, do keep in mind that a daemon's "`max verbosity`" setting will limit
how high of a level the various individual flags can be set on the daemon
side. For instance, if the max is 2, then any info and/or debug flag that
is set to a higher value than what would be set by `-vv` will be downgraded
This option was added to 3.1.0, so an older rsync on the server side might
reject your attempts at fine-grained control (if one or more flags needed
to be send to the server and the server was too old to understand them).
- See also the "max verbosity" caveat above when dealing with a daemon.
+ See also the "`max verbosity`" caveat above when dealing with a daemon.
0. `--debug=FLAGS`
local transfer, the client side is the sender.)
This option has no affect on a daemon, since the daemon configures whether
- it wants munged symlinks via its "munge symlinks" parameter. See also the
+ it wants munged symlinks via its "`munge symlinks`" parameter. See also the
"munge-symlinks" perl script in the support directory of the source code.
0. `--copy-dirlinks`, `-k`
This option is overridden by both `--super` and `--no-super`.
- See also the "fake super" setting in the daemon's rsyncd.conf file.
+ See also the "`fake super`" setting in the daemon's rsyncd.conf file.
0. `--sparse`, `-S`
If a user or group has no name on the source system or it has no match on
the destination system, then the numeric ID from the source system is used
- instead. See also the comments on the "use chroot" setting in the
+ instead. See also the comments on the "`use chroot`" setting in the
rsyncd.conf manpage for information on how the chroot setting affects
rsync's ability to look up the names of the users and groups and what you
can do about it.
will occur. If GROUP is empty, the trailing colon may be omitted, but if
USER is empty, a leading colon must be supplied.
- If you specify "--chown=foo:bar, this is exactly the same as specifying
+ If you specify "`--chown=foo:bar`", this is exactly the same as specifying
"`--usermap=*:foo --groupmap=*:bar`", only easier.
0. `--timeout=TIMEOUT`
character. A default format of "%n%L" is assumed if either `--info=name`
or `-v` is specified (this tells you just the name of the file and, if the
item is a link, where it points). For a full list of the possible escape
- characters, see the "log format" setting in the rsyncd.conf manpage.
+ characters, see the "`log format`" setting in the rsyncd.conf manpage.
Specifying the `--out-format` option implies the `--info=name` option,
which will mention each file, dir, etc. that gets updated in a significant
file specified by the `--log-file` option (which must also be specified for
this option to have any effect). If you specify an empty string, updated
files will not be mentioned in the log file. For a list of the possible
- escape characters, see the "log format" setting in the rsyncd.conf manpage.
+ escape characters, see the "`log format`" setting in the rsyncd.conf manpage.
The default FORMAT used if `--log-file` is specified and this option is not
is '%i %n%L'.
tabs) are always escaped, regardless of this option's setting.
The escape idiom that started in 2.6.7 is to output a literal backslash
- (\\) and a hash (#), followed by exactly 3 octal digits. For example, a
- newline would output as "\\#012". A literal backslash that is in a
+ (`\`) and a hash (`#`), followed by exactly 3 octal digits. For example, a
+ newline would output as "`\\#012`". A literal backslash that is in a
filename is not escaped unless it is followed by a hash and 3 digits (0-9).
0. `--human-readable`, `-h`
rule may be ineffective at the end of your other rules, or (2) you may wish
to override rsync's exclude choice. For instance, if you want to make
rsync clean-up any left-over partial-dirs that may be lying around, you
- should specify `--delete-after` and add a "risk" filter rule, e.g. `-f 'R
- .rsync-partial/'`. (Avoid using `--delete-before` or `--delete-during`
- unless you don't need rsync to use any of the left-over partial-dir data
- during the current run.)
+ should specify `--delete-after` and add a "risk" filter rule, e.g.
+ `-f 'R .rsync-partial/'`. (Avoid using `--delete-before` or
+ `--delete-during` unless you don't need rsync to use any of the left-over
+ partial-dir data during the current run.)
IMPORTANT: the `--partial-dir` should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
tmp). This requires both ends of the transfer to be at least version
3.2.0.
- For the purposes of the daemon-config's "refuse options" setting,
+ For the purposes of the daemon-config's "`refuse options`" setting,
`--partial-dir` does _not_ imply `--partial`. This is so that a refusal of
the `--partial` option can be used to disallow the overwriting of
destination files with a partial transfer, while still allowing the safer
Rsync writes data over the socket in blocks, and this option both limits
the size of the blocks that rsync writes, and tries to keep the average
- transfer rate at the requested limit. Some "burstiness" may be seen where
+ transfer rate at the requested limit. Some burstiness may be seen where
rsync writes out a block of data and then sleeps to bring the average rate
into compliance.
These options also exist in the `--daemon` mode section.
If rsync was complied without support for IPv6, the `--ipv6` option will
- have no effect. The `rsync -V` output will contain "no IPv6" if is the
+ have no effect. The `rsync -V` output will contain "`no IPv6`" if is the
case.
See also these options in the `--daemon` mode section.
0. `--log-file=FILE`
This option tells the rsync daemon to use the given log-file name instead
- of using the "log file" setting in the config file.
+ of using the "`log file`" setting in the config file.
0. `--log-file-format=FORMAT`
This option tells the rsync daemon to use the given FORMAT string instead
- of using the "log format" setting in the config file. It also enables
- "transfer logging" unless the string is empty, in which case transfer
+ of using the "`log format`" setting in the config file. It also enables
+ "`transfer logging`" unless the string is empty, in which case transfer
logging is turned off.
0. `--sockopts`
This option increases the amount of information the daemon logs during its
startup phase. After the client connects, the daemon's verbosity level
- will be controlled by the options that the client used and the "max
- verbosity" setting in the module's config section.
+ will be controlled by the options that the client used and the
+ "`max verbosity`" setting in the module's config section.
0. `--ipv4`, `-4` or `--ipv6`, `-6`
These options also exist in the regular rsync options section.
If rsync was complied without support for IPv6, the `--ipv6` option will
- have no effect. The `rsync -V` output will contain "no IPv6" if is the
+ have no effect. The `rsync -V` output will contain "`no IPv6`" if is the
case.
0. `--help`, `-h`
When rules are being read from a file, empty lines are ignored, as are comment
lines that start with a "#".
-Note that the `--include`/`--exclude` command-line options do not allow the
+[comment]: # (Remember that markdown strips spaces from start/end of ` ... ` sequences!)
+[comment]: # (Thus, the `x ` sequences below use a literal non-breakable space!)
+
+Note that the `--include` & `--exclude` command-line options do not allow the
full range of rule parsing as described above -- they only allow the
-specification of include/exclude patterns plus a "!" token to clear the list
-(and the normal comment parsing when rules are read from a file). If a pattern
-does not begin with "- " (dash, space) or "+ " (plus, space), then the rule
-will be interpreted as if "+ " (for an include option) or "- " (for an exclude
-option) were prefixed to the string. A `--filter` option, on the other hand,
-must always contain either a short or long rule name at the start of the rule.
+specification of include / exclude patterns plus a "`!`" token to clear the
+list (and the normal comment parsing when rules are read from a file). If a
+pattern does not begin with "`- `" (dash, space) or "`+ `" (plus, space), then
+the rule will be interpreted as if "`+ `" (for an include option) or "`- `"
+(for an exclude option) were prefixed to the string. A `--filter` option, on
+the other hand, must always contain either a short or long rule name at the
+start of the rule.
Note also that the `--filter`, `--include`, and `--exclude` options take one
rule/pattern each. To add multiple ones, you can repeat the options on the
command-line, use the merge-file syntax of the `--filter` option, or the
-`--include-from`/`--exclude-from` options.
+`--include-from` / `--exclude-from` options.
# INCLUDE/EXCLUDE PATTERN RULES
- if the pattern starts with a / then it is anchored to a particular spot in
the hierarchy of files, otherwise it is matched against the end of the
pathname. This is similar to a leading ^ in regular expressions. Thus
- "/foo" would match a name of "foo" at either the "root of the transfer" (for
+ `/foo` would match a name of "foo" at either the "root of the transfer" (for
a global rule) or in the merge-file's directory (for a per-directory rule).
- An unqualified "foo" would match a name of "foo" anywhere in the tree because
+ An unqualified `foo` would match a name of "foo" anywhere in the tree because
the algorithm is applied recursively from the top down; it behaves as if each
path component gets a turn at being the end of the filename. Even the
unanchored "sub/foo" would match at any point in the hierarchy where a "foo"
The file consists of modules and parameters. A module begins with the name of
the module in square brackets and continues until the next module begins.
-Modules contain parameters of the form "name = value".
+Modules contain parameters of the form `name = value`.
The file is line-based -- that is, each newline-terminated line represents
either a comment, a module name or a parameter.
This parameter tells rsync to modify all symlinks in the same way as the
(non-daemon-affecting) `--munge-links` command-line option (using a method
described below). This should help protect your files from user trickery
- when your daemon module is writable. The default is disabled when "use
- chroot" is on with an inside-chroot path of "/", OR if "daemon chroot" is
- on, otherwise it is enabled.
+ when your daemon module is writable. The default is disabled when
+ "use chroot" is on with an inside-chroot path of "/", OR if "daemon chroot"
+ is on, otherwise it is enabled.
If you disable this parameter on a daemon that is not read-only, there are
tricks that a user can play with uploaded symlinks to access
and `--debug` logging. If the max value is 2, then no info and/or debug
value that is higher than what would be set by `-vv` will be honored by the
daemon in its logging. To see how high of a verbosity level you need to
- accept for a particular info/debug level, refer to "rsync --info=help" and
- "rsync --debug=help". For instance, it takes max-verbosity 4 to be able to
+ accept for a particular info/debug level, refer to `rsync --info=help` and
+ `rsync --debug=help`. For instance, it takes max-verbosity 4 to be able to
output debug TIME2 and FLIST3.
0. `lock file`
0. `read only`
This parameter determines whether clients will be able to upload files or
- not. If "read only" is true then any attempted uploads will fail. If "read
- only" is false then uploads will be possible if file permissions on the
- daemon side allow them. The default is for all modules to be read only.
+ not. If "read only" is true then any attempted uploads will fail. If
+ "read only" is false then uploads will be possible if file permissions on
+ the daemon side allow them. The default is for all modules to be read only.
- Note that "auth users" can override this setting on a
- per-user basis.
+ Note that "auth users" can override this setting on a per-user basis.
0. `write only`
The "filter" parameter takes a space-separated list of daemon filter rules,
though it is smart enough to know not to split a token at an internal space
- in a rule (e.g. "- /foo - /bar" is parsed as two rules). You may specify
+ in a rule (e.g. "`- /foo - /bar`" is parsed as two rules). You may specify
one or more merge-file rules using the normal syntax. Only one "filter"
parameter can apply to a given module in the config file, so put all the
rules you want in a single parameter. Note that per-directory merge-file
0. `exclude`
This parameter takes a space-separated list of daemon exclude patterns. As
- with the client `--exclude` option, patterns can be qualified with "- " or
- "+ " to explicitly indicate exclude/include. Only one "exclude" parameter
+ with the client `--exclude` option, patterns can be qualified with "`- `" or
+ "`+ `" to explicitly indicate exclude/include. Only one "exclude" parameter
can apply to a given module. See the "filter" parameter for a description
of how excluded files affect the daemon.
authentication. If "auth users" is set then the client will be challenged
to supply a username and password to connect to the module. A challenge
response authentication protocol is used for this exchange. The plain text
- usernames and passwords are stored in the file specified by the "secrets
- file" parameter. The default is for all users to be able to connect without
- a password (this is called "anonymous rsync").
+ usernames and passwords are stored in the file specified by the
+ "secrets file" parameter. The default is for all users to be able to
+ connect without a password (this is called "anonymous rsync").
In addition to username matching, you can specify groupname matching via a
'@' prefix. When using groupname matching, the authenticating username
If both parameters are specified then the "hosts allow" parameter is
checked first and a match results in the client being able to connect. The
"hosts deny" parameter is then checked and a match means that the host is
- rejected. If the host does not match either the "hosts allow" or the "hosts
- deny" patterns then it is allowed to connect.
+ rejected. If the host does not match either the "hosts allow" or the
+ "hosts deny" patterns then it is allowed to connect.
The default is no "hosts allow" parameter, which means all hosts can
connect.
0. `reverse lookup`
Controls whether the daemon performs a reverse lookup on the client's IP
- address to determine its hostname, which is used for "hosts allow"/"hosts
- deny" checks and the "%h" log escape. This is enabled by default, but you
- may wish to disable it to save time if you know the lookup will not return
- a useful result, in which case the daemon will use the name "UNDETERMINED"
- instead.
+ address to determine its hostname, which is used for "hosts allow" &
+ "hosts deny" checks and the "%h" log escape. This is enabled by default,
+ but you may wish to disable it to save time if you know the lookup will not
+ return a useful result, in which case the daemon will use the name
+ "UNDETERMINED" instead.
If this parameter is enabled globally (even by default), rsync performs the
lookup as soon as a client connects, so disabling it for a module will not
transfers when transfer logging is enabled. The format is a text string
containing embedded single-character escape sequences prefixed with a
percent (%) character. An optional numeric field width may also be
- specified between the percent and the escape letter (e.g. "`%-50n %8l
- %07p`"). In addition, one or more apostrophes may be specified prior to a
- numerical escape to indicate that the numerical value should be made more
- human-readable. The 3 supported levels are the same as for the
+ specified between the percent and the escape letter (e.g.
+ "`%-50n %8l %07p`"). In addition, one or more apostrophes may be specified
+ prior to a numerical escape to indicate that the numerical value should be
+ made more human-readable. The 3 supported levels are the same as for the
`--human-readable` command-line option, though the default is for
human-readability to be off. Each added apostrophe increases the level
(e.g. "`%''l %'b %f`").
- The default log format is "%o %h [%a] %m (%u) %f %l", and a "%t [%p] " is
- always prefixed when using the "log file" parameter. (A perl script that
- will summarize this default log format is included in the rsync source code
- distribution in the "support" subdirectory: rsyncstats.)
+ The default log format is "`%o %h [%a] %m (%u) %f %l`", and a "`%t [%p] `"
+ is always prefixed when using the "log file" parameter. (A perl script
+ that will summarize this default log format is included in the rsync source
+ code distribution in the "support" subdirectory: rsyncstats.)
The single-character escapes that are understood are as follows:
- %h the remote host name (only available for a daemon)
- %i an itemized list of what is being updated
- %l the length of the file in bytes
- - %L the string " -> SYMLINK", " => HARDLINK", or "" (where `SYMLINK` or
- `HARDLINK` is a filename)
+ - %L the string "` -> SYMLINK`", "` => HARDLINK`", or "" (where `SYMLINK`
+ or `HARDLINK` is a filename)
- %m the module name
- %M the last-modified time of the file
- %n the filename (short form; trailing "/" on dir)
> refuse options = * no-iconv !a !v
- As an additional aid (beginning in 3.2.0), refusing (or "!refusing") the
+ As an additional aid (beginning in 3.2.0), refusing (or "`!refusing`") the
"a" or "archive" option also affects all the options that the `--archive`
option implies (`-rdlptgoD`), but only if the option is matched explicitly
(not using a wildcard). If you want to do something tricky, you can use
"`!compress*`" so that you also accept the `--compress-level` option.
Note that the "write-devices" option is refused by default, but can be
- explicitly accepted with "!write-devices". The options "log-file" and
+ explicitly accepted with "`!write-devices`". The options "log-file" and
"log-file-format" are forcibly refused and cannot be accepted.
Here are all the options that are not matched by wild-cards:
- `--server`: Required for rsync to even work.
- - `-e`: Required to convey compatibility flags to the server.
+ - `--rsh`, `-e`: Required to convey compatibility flags to the server.
- `--log-format`: This is required to convey things like
`--itemize-changes` to a remote receiver. Is an older name for
`--out-format` that is still passed to the server for improved backward
compatibility and should not be confused with `--log-file-format`.
- `--sender`: Use "write only" parameter instead of refusing this.
- - `-n, --dry-run`: Who would want to disable this?
- - `-s, --protect-args`: This actually makes transfers safer.
- - `-0, --from0`: Make it easier to accept/refuse `--files-from` without
+ - `--dry-run`, `-n`: Who would want to disable this?
+ - `--protect-args`, `-n`: This actually makes transfers safer.
+ - `--from0`, `-0`: Make it easier to accept/refuse `--files-from` without
affecting this modifier.
- `--iconv`: This is auto-disabled based on "charset" parameter.
- `--no-iconv`: Most transfers use this option.
compression occurs for those files. Other algorithms have the level
minimized to reduces the CPU usage as much as possible.
- See the `--skip-compress` parameter in the `rsync`(1) manpage for the list
- of file suffixes that are not compressed by default. Specifying a value
- for the "dont compress" parameter changes the default when the daemon is
- the sender.
+ See the `--skip-compress` parameter in the **rsync**(1) manpage for the
+ list of file suffixes that are not compressed by default. Specifying a
+ value for the "dont compress" parameter changes the default when the daemon
+ is the sender.
0. `early exec`, `pre-xfer exec`, `post-xfer exec`
git.samba.org / rsync.git / commitdiff