@@ -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
139914170 . ` --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+
49584980Three basic behaviors are possible when rsync encounters a symbolic
49594981link in the source directory.
49604982
0 commit comments