Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 70 additions & 66 deletions rsync.1.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,25 +290,25 @@ filenames and pass it to [`--files-from`](#opt).

### Symbolic links

A malicious sender can include symlinks that point outside the destination tree
(for example at `/etc/passwd`). Use [`--safe-links`](#opt) to ignore any symlink
that points outside the set of files
being transferred, or [`--munge-links`](#opt) to store every symlink in a
form that is unusable on disk but recoverable later; `--no-links` drops symlinks
entirely. See the [SYMBOLIC LINKS](#) section for how these interact.

Separately, the directory and file paths that *you* supply on the command line --
[`--backup-dir`](#opt), [`--temp-dir`](#opt), [`--partial-dir`](#opt), the
[`--link-dest`](#opt)/[`--compare-dest`](#opt)/[`--copy-dest`](#opt) basis directories,
[`--log-file`](#opt), [`--password-file`](#opt),
[`--files-from`](#opt)/`--include-from`/`--exclude-from`,
[`--filter`](#opt) merge files, [`--write-batch`](#opt)/[`--read-batch`](#opt),
and the destination itself -- are resolved so that a symlink component is followed
only when it is owned by you or by root; an attacker-planted symlink along one of
those paths is refused. [`--insecure-links`](#opt) turns that protection off
(restoring the historical follow-any-symlink behaviour); use it only when every
directory along those paths is trusted, never on a path an unprivileged user can
write.
[`--archive`](#opt) (`-a`) includes [`--links`](#opt) (`-l`), which copies
symlinks as symlinks rather than copying their targets. It does not imply
[`--safe-links`](#opt): links pointing outside the copied tree are preserved
unless that option is requested. [`--munge-links`](#opt) stores symlinks in an
unusable but recoverable form; `--no-links` drops them entirely.

For example, `rsync -ax SRC HOST:DEST` preserves the symlinks inside `SRC`
without `--insecure-links`. A symlink in the path leading to `DEST` is different:
rsync must follow it to reach the destination. By default it follows that link
only if it is owned by root or the user running the receiver. A symlink owned
by another user is refused. The explicit source argument selects the transfer
root and is not subject to this ownership check. The `-x` option does not change
these rules.

The same ownership check applies to auxiliary files and directories; see
[`--insecure-links`](#opt). That option disables the check and should only be
used when every directory along those paths is trusted. Root confinement is a
separate restriction described under [`--confine-root`](#opt) and in
[**rsyncd.conf**(5)](rsyncd.conf.5).

### Use strong checksums

Expand Down Expand Up @@ -1380,6 +1380,11 @@ sign) if you want the local shell to expand it.
which point outside the copied tree. All absolute symlinks are also
ignored.

This option applies only to symlink entries received in the file list. It
does not control symlink components in the destination or other protected
operator-supplied paths; those are handled by the default ownership check
described under [`--insecure-links`](#opt).

Since this ignoring is happening on the receiving side, it will still be
effective even when the sending side has munged symlinks (when it is using
[`--munge-links`](#opt)). It also affects deletions, since the file being
Expand All @@ -1389,7 +1394,8 @@ sign) if you want the local shell to expand it.
This option has no effect unless it is combined with [`--links`](#opt) (or
an option that implies [`--links`](#opt) such as [`--archive`](#opt)),
because without [`--links`](#opt) there will not be any symlinks in the
transfer. Its effect is superseded by [`--copy-unsafe-links`](#opt).
transfer. [`--archive`](#opt) does not itself enable `--safe-links`.
[`--copy-unsafe-links`](#opt) takes precedence over `--safe-links`.

Using this option in conjunction with [`--relative`](#opt) may give
unexpected results.
Expand All @@ -1398,59 +1404,54 @@ sign) if you want the local shell to expand it.

0. `--insecure-links`

By default rsync resolves the directory and file paths that the **operator**
supplies on the command line with a defensive directory-tree walk that
**follows a symlink component only when it is owned by uid 0 or by the
running user**, and
refuses one owned by any other user. This stops an attacker who can write
inside one of those directories from planting a symlink that
redirects a privileged rsync to a target outside the intended tree, while
still honouring the operator's own symlinks.
The rule is the same for absolute and relative paths.
This applies to the destination directory and to the parameters to the
following options: `--backup-dir`, `--temp-dir`/`-T`,
`--partial-dir`, `--link-dest`, `--compare-dest`, `--copy-dest`, `--log-file`,
`--password-file`, `--files-from`, `--include-from`, `--exclude-from`,
`--filter` merge files, `--write-batch` and `--read-batch`.

`--insecure-links` turns that defence off, restoring the historical behaviour
of following any symlink in those paths. Use it only when you fully trust
every directory along each operator-supplied path, as it re-exposes the
symlink-redirection attacks the walk prevents.
Allow rsync to follow symlinks owned by other users in the destination and
auxiliary paths. By default each symlink followed in these paths must be
owned by root or by the effective user running that rsync process. The rule
applies to absolute and relative paths.

The checked directories are the destination and those named by
`--backup-dir`, `--temp-dir` (`-T`), `--partial-dir`, `--link-dest`,
`--compare-dest` and `--copy-dest`.

The check also covers files named by `--log-file`, `--password-file`,
`--files-from`, `--include-from`, `--exclude-from`, `--write-batch`,
`--read-batch` and merge files read by `--filter`. Files supplied locally
before the transfer can live outside the transfer tree. A list or merge file
selected by a daemon client must stay inside the module. Paths selected from a
`--files-from` list and merge files read during the transfer can also be
confined by [`--confine-root`](#opt).

This option is not needed to preserve symlink entries with [`--links`](#opt)
or [`--archive`](#opt): those entries are recreated without following their
targets. Use `--insecure-links` only when every directory along the paths
rsync will follow is trusted.

The option is **local only**: it is not sent to the remote side of the
transfer. A remote-shell peer that needs the opt-out must set it there, e.g.
via [`--rsync-path`](#opt)), and a daemon never honours it -- a daemon that
receives `--insecure-links` from a client refuses the request. A daemon
administrator who wants the legacy behaviour for a single trusted module sets
"`insecure links = yes`" in that module's **rsyncd.conf**(5) section instead;
a client can never enable it.
transfer. A remote-shell peer that needs the opt-out must set it there using
[`--rsync-path`](#opt). A daemon refuses `--insecure-links` from a client.
Its administrator can enable `insecure links = yes` for a trusted module in
[**rsyncd.conf**(5)](rsyncd.conf.5); a client cannot enable it.

See the [SYMBOLIC LINKS](#) section for multi-option info.

0. `--confine-root=DIR`

In the default symlink mode this bounds where operator option paths and
paths selected from a [`--files-from`](#opt) list are allowed to resolve:
one that ends up outside DIR is refused, even if every symlink along it was
owned by a trusted user. Explicit source roots remain operator-selected
transfer roots.
The ownership walk asks who planted a link; this asks where the path came
out.

DIR must be absolute. Nothing is confined by default, and
`--confine-root=/` is a no-op.

It exists for a wrapper that serves a restricted directory over a remote
shell, `rrsync` being the one shipped here, which passes it automatically
whenever its restricted dir is not "`/`". Such a wrapper can vet the argv
it is handed, but filter rules travel over the protocol instead: a client
can name a merge file outside the restricted dir in a dir-merge rule and
have the server read it in as filter rules. On a pull that needs neither
`--delete` nor any verbosity, because an exclude-only merge (the "`-`"
modifier) makes every line a pattern, and the client reads the file's
contents off which of its own names went missing. Confining the open is
what closes that; a merge file inside DIR keeps working as before.
In the default symlink mode this bounds paths used for backups, partial files,
alternate-destination lookups, merge files read during the transfer and
entries selected from a [`--files-from`](#opt) list. Such a path is refused
if it resolves outside DIR, even when its symlinks are owned by root or the
running user. Explicit source arguments still select their own transfer roots.

Files opened locally before the transfer, such as log files, password files,
batch files and file lists, are checked for symlink ownership but may reside
outside DIR. A local `--files-from` list can therefore live outside DIR even
when the paths read from it are confined.

DIR must be absolute. `--confine-root=/` adds no restriction.

Restricted-shell wrappers such as `rrsync` use this option to constrain
paths received over the protocol. `rrsync` sets DIR to its restricted
directory unless that directory is `/`.

A daemon ignores this option -- its module directory is already the
boundary, and the option arrives in a client-supplied argv, so honouring it
Expand Down Expand Up @@ -4955,6 +4956,9 @@ appropriate [`--read-batch`](#opt) command for the batched data.

## SYMBOLIC LINKS

This section describes symlink entries in the transfer. Symlink components in
operator-supplied paths are handled separately; see [`--insecure-links`](#opt).

Three basic behaviors are possible when rsync encounters a symbolic
link in the source directory.

Expand Down
Loading