Skip to content

Commit 9d10a1e

Browse files
authored
docs: clarify safe-links and path protection (#1156)
1 parent c8c93e1 commit 9d10a1e

1 file changed

Lines changed: 70 additions & 66 deletions

File tree

‎rsync.1.md‎

Lines changed: 70 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -290,25 +290,25 @@ filenames and pass it to [`--files-from`](#opt).
290290

291291
### Symbolic links
292292

293-
A malicious sender can include symlinks that point outside the destination tree
294-
(for example at `/etc/passwd`). Use [`--safe-links`](#opt) to ignore any symlink
295-
that points outside the set of files
296-
being transferred, or [`--munge-links`](#opt) to store every symlink in a
297-
form that is unusable on disk but recoverable later; `--no-links` drops symlinks
298-
entirely. See the [SYMBOLIC LINKS](#) section for how these interact.
299-
300-
Separately, the directory and file paths that *you* supply on the command line --
301-
[`--backup-dir`](#opt), [`--temp-dir`](#opt), [`--partial-dir`](#opt), the
302-
[`--link-dest`](#opt)/[`--compare-dest`](#opt)/[`--copy-dest`](#opt) basis directories,
303-
[`--log-file`](#opt), [`--password-file`](#opt),
304-
[`--files-from`](#opt)/`--include-from`/`--exclude-from`,
305-
[`--filter`](#opt) merge files, [`--write-batch`](#opt)/[`--read-batch`](#opt),
306-
and the destination itself -- are resolved so that a symlink component is followed
307-
only when it is owned by you or by root; an attacker-planted symlink along one of
308-
those paths is refused. [`--insecure-links`](#opt) turns that protection off
309-
(restoring the historical follow-any-symlink behaviour); use it only when every
310-
directory along those paths is trusted, never on a path an unprivileged user can
311-
write.
293+
[`--archive`](#opt) (`-a`) includes [`--links`](#opt) (`-l`), which copies
294+
symlinks as symlinks rather than copying their targets. It does not imply
295+
[`--safe-links`](#opt): links pointing outside the copied tree are preserved
296+
unless that option is requested. [`--munge-links`](#opt) stores symlinks in an
297+
unusable but recoverable form; `--no-links` drops them entirely.
298+
299+
For example, `rsync -ax SRC HOST:DEST` preserves the symlinks inside `SRC`
300+
without `--insecure-links`. A symlink in the path leading to `DEST` is different:
301+
rsync must follow it to reach the destination. By default it follows that link
302+
only if it is owned by root or the user running the receiver. A symlink owned
303+
by another user is refused. The explicit source argument selects the transfer
304+
root and is not subject to this ownership check. The `-x` option does not change
305+
these rules.
306+
307+
The same ownership check applies to auxiliary files and directories; see
308+
[`--insecure-links`](#opt). That option disables the check and should only be
309+
used when every directory along those paths is trusted. Root confinement is a
310+
separate restriction described under [`--confine-root`](#opt) and in
311+
[**rsyncd.conf**(5)](rsyncd.conf.5).
312312

313313
### Use strong checksums
314314

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

1383+
This option applies only to symlink entries received in the file list. It
1384+
does not control symlink components in the destination or other protected
1385+
operator-supplied paths; those are handled by the default ownership check
1386+
described under [`--insecure-links`](#opt).
1387+
13831388
Since this ignoring is happening on the receiving side, it will still be
13841389
effective even when the sending side has munged symlinks (when it is using
13851390
[`--munge-links`](#opt)). It also affects deletions, since the file being
@@ -1389,7 +1394,8 @@ sign) if you want the local shell to expand it.
13891394
This option has no effect unless it is combined with [`--links`](#opt) (or
13901395
an option that implies [`--links`](#opt) such as [`--archive`](#opt)),
13911396
because without [`--links`](#opt) there will not be any symlinks in the
1392-
transfer. Its effect is superseded by [`--copy-unsafe-links`](#opt).
1397+
transfer. [`--archive`](#opt) does not itself enable `--safe-links`.
1398+
[`--copy-unsafe-links`](#opt) takes precedence over `--safe-links`.
13931399

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

13991405
0. `--insecure-links`
14001406

1401-
By default rsync resolves the directory and file paths that the **operator**
1402-
supplies on the command line with a defensive directory-tree walk that
1403-
**follows a symlink component only when it is owned by uid 0 or by the
1404-
running user**, and
1405-
refuses one owned by any other user. This stops an attacker who can write
1406-
inside one of those directories from planting a symlink that
1407-
redirects a privileged rsync to a target outside the intended tree, while
1408-
still honouring the operator's own symlinks.
1409-
The rule is the same for absolute and relative paths.
1410-
This applies to the destination directory and to the parameters to the
1411-
following options: `--backup-dir`, `--temp-dir`/`-T`,
1412-
`--partial-dir`, `--link-dest`, `--compare-dest`, `--copy-dest`, `--log-file`,
1413-
`--password-file`, `--files-from`, `--include-from`, `--exclude-from`,
1414-
`--filter` merge files, `--write-batch` and `--read-batch`.
1415-
1416-
`--insecure-links` turns that defence off, restoring the historical behaviour
1417-
of following any symlink in those paths. Use it only when you fully trust
1418-
every directory along each operator-supplied path, as it re-exposes the
1419-
symlink-redirection attacks the walk prevents.
1407+
Allow rsync to follow symlinks owned by other users in the destination and
1408+
auxiliary paths. By default each symlink followed in these paths must be
1409+
owned by root or by the effective user running that rsync process. The rule
1410+
applies to absolute and relative paths.
1411+
1412+
The checked directories are the destination and those named by
1413+
`--backup-dir`, `--temp-dir` (`-T`), `--partial-dir`, `--link-dest`,
1414+
`--compare-dest` and `--copy-dest`.
1415+
1416+
The check also covers files named by `--log-file`, `--password-file`,
1417+
`--files-from`, `--include-from`, `--exclude-from`, `--write-batch`,
1418+
`--read-batch` and merge files read by `--filter`. Files supplied locally
1419+
before the transfer can live outside the transfer tree. A list or merge file
1420+
selected by a daemon client must stay inside the module. Paths selected from a
1421+
`--files-from` list and merge files read during the transfer can also be
1422+
confined by [`--confine-root`](#opt).
1423+
1424+
This option is not needed to preserve symlink entries with [`--links`](#opt)
1425+
or [`--archive`](#opt): those entries are recreated without following their
1426+
targets. Use `--insecure-links` only when every directory along the paths
1427+
rsync will follow is trusted.
14201428

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

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

14311437
0. `--confine-root=DIR`
14321438

1433-
In the default symlink mode this bounds where operator option paths and
1434-
paths selected from a [`--files-from`](#opt) list are allowed to resolve:
1435-
one that ends up outside DIR is refused, even if every symlink along it was
1436-
owned by a trusted user. Explicit source roots remain operator-selected
1437-
transfer roots.
1438-
The ownership walk asks who planted a link; this asks where the path came
1439-
out.
1440-
1441-
DIR must be absolute. Nothing is confined by default, and
1442-
`--confine-root=/` is a no-op.
1443-
1444-
It exists for a wrapper that serves a restricted directory over a remote
1445-
shell, `rrsync` being the one shipped here, which passes it automatically
1446-
whenever its restricted dir is not "`/`". Such a wrapper can vet the argv
1447-
it is handed, but filter rules travel over the protocol instead: a client
1448-
can name a merge file outside the restricted dir in a dir-merge rule and
1449-
have the server read it in as filter rules. On a pull that needs neither
1450-
`--delete` nor any verbosity, because an exclude-only merge (the "`-`"
1451-
modifier) makes every line a pattern, and the client reads the file's
1452-
contents off which of its own names went missing. Confining the open is
1453-
what closes that; a merge file inside DIR keeps working as before.
1439+
In the default symlink mode this bounds paths used for backups, partial files,
1440+
alternate-destination lookups, merge files read during the transfer and
1441+
entries selected from a [`--files-from`](#opt) list. Such a path is refused
1442+
if it resolves outside DIR, even when its symlinks are owned by root or the
1443+
running user. Explicit source arguments still select their own transfer roots.
1444+
1445+
Files opened locally before the transfer, such as log files, password files,
1446+
batch files and file lists, are checked for symlink ownership but may reside
1447+
outside DIR. A local `--files-from` list can therefore live outside DIR even
1448+
when the paths read from it are confined.
1449+
1450+
DIR must be absolute. `--confine-root=/` adds no restriction.
1451+
1452+
Restricted-shell wrappers such as `rrsync` use this option to constrain
1453+
paths received over the protocol. `rrsync` sets DIR to its restricted
1454+
directory unless that directory is `/`.
14541455

14551456
A daemon ignores this option -- its module directory is already the
14561457
boundary, and the option arrives in a client-supplied argv, so honouring it
@@ -4955,6 +4956,9 @@ appropriate [`--read-batch`](#opt) command for the batched data.
49554956
49564957
## SYMBOLIC LINKS
49574958
4959+
This section describes symlink entries in the transfer. Symlink components in
4960+
operator-supplied paths are handled separately; see [`--insecure-links`](#opt).
4961+
49584962
Three basic behaviors are possible when rsync encounters a symbolic
49594963
link in the source directory.
49604964

0 commit comments

Comments
 (0)