Skip to content

Commit 24c4b44

Browse files
committed
docs: clarify safe-links and path protection
1 parent d1a2844 commit 24c4b44

1 file changed

Lines changed: 48 additions & 26 deletions

File tree

‎rsync.1.md‎

Lines changed: 48 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -290,25 +290,37 @@ 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 --
293+
Two separate rules apply to symlinks:
294+
- Symlinks in the transfer are entries found under the source and described
295+
by the sender. [`--links`](#opt) (`-l`) recreates them, and [`--archive`](#opt)
296+
(`-a`) implies `--links`. [`--safe-links`](#opt) filters only these entries,
297+
dropping links whose targets escape the copied tree. `--archive` does not
298+
enable `--safe-links`; it must be requested separately.
299+
[`--munge-links`](#opt) stores every symlink in an unusable but recoverable
300+
form, while `--no-links` drops them entirely.
301+
- Symlinks in operator-supplied paths are components of the destination or
302+
another protected path named on the command line. This protection is
303+
independent of `--links`, `--safe-links` and `--archive`. By default rsync
304+
follows such a component only when it is owned by the running user or by
305+
root. [`--insecure-links`](#opt) restores the historical
306+
follow-any-symlink behaviour.
307+
308+
For example, `rsync -ax SRC HOST:DEST` recreates symlink entries found inside
309+
`SRC` without following their targets. This does not require `--insecure-links`
310+
and does not enable `--safe-links`. The operator-path check affects that command
311+
only if `DEST` contains a symlink owned by neither the receiving rsync user nor
312+
root. The `-x` option does not change either rule.
313+
The source argument itself selects the transfer root and is not subject to this
314+
ownership check.
315+
316+
Protected operator-supplied paths include the destination plus
301317
[`--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.
318+
[`--link-dest`](#opt)/[`--compare-dest`](#opt)/[`--copy-dest`](#opt) basis
319+
directories, [`--log-file`](#opt), [`--password-file`](#opt),
320+
[`--files-from`](#opt)/`--include-from`/`--exclude-from`, [`--filter`](#opt)
321+
merge files and [`--write-batch`](#opt)/[`--read-batch`](#opt). Never use
322+
`--insecure-links` when an unprivileged user can write a directory along one of
323+
those paths.
312324

313325
### Use strong checksums
314326

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

1395+
This option applies only to symlink entries received in the file list. It
1396+
does not control symlink components in the destination or other protected
1397+
operator-supplied paths; those are handled by the default ownership check
1398+
described under [`--insecure-links`](#opt).
1399+
13831400
Since this ignoring is happening on the receiving side, it will still be
13841401
effective even when the sending side has munged symlinks (when it is using
13851402
[`--munge-links`](#opt)). It also affects deletions, since the file being
@@ -1389,7 +1406,8 @@ sign) if you want the local shell to expand it.
13891406
This option has no effect unless it is combined with [`--links`](#opt) (or
13901407
an option that implies [`--links`](#opt) such as [`--archive`](#opt)),
13911408
because without [`--links`](#opt) there will not be any symlinks in the
1392-
transfer. Its effect is superseded by [`--copy-unsafe-links`](#opt).
1409+
transfer. [`--archive`](#opt) does not itself enable `--safe-links`. Its
1410+
effect is superseded by [`--copy-unsafe-links`](#opt).
13931411

13941412
Using this option in conjunction with [`--relative`](#opt) may give
13951413
unexpected results.
@@ -1398,20 +1416,21 @@ sign) if you want the local shell to expand it.
13981416

13991417
0. `--insecure-links`
14001418

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
1419+
By default rsync resolves protected operator-supplied paths with a defensive
1420+
directory-tree walk. It **follows a symlink component only when it is owned
1421+
by uid 0 or by the running user** and refuses one owned by any other
1422+
user. This stops an attacker who can write inside one of those directories
1423+
from planting a symlink that
14071424
redirects a privileged rsync to a target outside the intended tree, while
14081425
still honouring the operator's own symlinks.
14091426
The rule is the same for absolute and relative paths.
1410-
This applies to the destination directory and to the parameters to the
1427+
The protected paths are the destination directory and the parameters to the
14111428
following options: `--backup-dir`, `--temp-dir`/`-T`,
14121429
`--partial-dir`, `--link-dest`, `--compare-dest`, `--copy-dest`, `--log-file`,
14131430
`--password-file`, `--files-from`, `--include-from`, `--exclude-from`,
14141431
`--filter` merge files, `--write-batch` and `--read-batch`.
1432+
This check does not inspect or omit symlink entries in the transfer;
1433+
`--links` still recreates those entries without following their targets.
14151434

14161435
`--insecure-links` turns that defence off, restoring the historical behaviour
14171436
of following any symlink in those paths. Use it only when you fully trust
@@ -4955,6 +4974,9 @@ appropriate [`--read-batch`](#opt) command for the batched data.
49554974
49564975
## SYMBOLIC LINKS
49574976
4977+
This section describes symlink entries in the transfer. Symlink components in
4978+
operator-supplied paths are handled separately; see [`--insecure-links`](#opt).
4979+
49584980
Three basic behaviors are possible when rsync encounters a symbolic
49594981
link in the source directory.
49604982

0 commit comments

Comments
 (0)