@@ -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
139914050 . ` --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
143114370 . ` --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+
49584962Three basic behaviors are possible when rsync encounters a symbolic
49594963link in the source directory.
49604964
0 commit comments