@@ -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+
49584976Three basic behaviors are possible when rsync encounters a symbolic
49594977link in the source directory.
49604978
0 commit comments