Skip to content

Commit 57fa107

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

1 file changed

Lines changed: 37 additions & 19 deletions

File tree

‎rsync.1.md‎

Lines changed: 37 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -290,25 +290,34 @@ 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 symlinks found inside `SRC` and
309+
does not enable `--safe-links`. The operator-path check affects that command if
310+
`DEST` contains a symlink owned by neither the receiving rsync user nor root.
311+
The `-x` option does not change either rule.
312+
313+
Protected operator-supplied paths include the destination plus
301314
[`--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.
315+
[`--link-dest`](#opt)/[`--compare-dest`](#opt)/[`--copy-dest`](#opt) basis
316+
directories, [`--log-file`](#opt), [`--password-file`](#opt),
317+
[`--files-from`](#opt)/`--include-from`/`--exclude-from`, [`--filter`](#opt)
318+
merge files and [`--write-batch`](#opt)/[`--read-batch`](#opt). Never use
319+
`--insecure-links` when an unprivileged user can write a directory along one of
320+
those paths.
312321

313322
### Use strong checksums
314323

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

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

13941409
Using this option in conjunction with [`--relative`](#opt) may give
13951410
unexpected results.
@@ -4955,6 +4970,9 @@ appropriate [`--read-batch`](#opt) command for the batched data.
49554970
49564971
## SYMBOLIC LINKS
49574972
4973+
This section describes symlink entries in the transfer. Symlink components in
4974+
operator-supplied paths are handled separately; see [`--insecure-links`](#opt).
4975+
49584976
Three basic behaviors are possible when rsync encounters a symbolic
49594977
link in the source directory.
49604978

0 commit comments

Comments
 (0)