Avoid directory permission issues with --fake-super.

[rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 9cc1a591558a47c59f13f3cfbc9d5870697ec6e0..a523f23b675e52f62e8e62fa3937dc7a6e4e271f 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -688,6 +688,12 @@ specify a backup suffix using the bf(--suffix) option
 (otherwise the files backed up in the specified directory
 will keep their original filenames).
 
+Note that if you specify a relative path, the backup directory will be
+relative to the destination directory, so you probably want to specify
+either an absolute path or a path that starts with "../".  If an rsync
+daemon is the receiver, the backup dir cannot go outside the module's path
+hierarchy, so take extra care not to delete it or copy into it.
+
 dit(bf(--suffix=SUFFIX)) This option allows you to override the default
 backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~
 if no -bf(-backup-dir) was specified, otherwise it is an empty string.
@@ -823,6 +829,17 @@ bf(--force) or bf(--delete) is in effect).
 See also bf(--keep-dirlinks) for an analogous option for the receiving
 side.
 
+bf(--copy-dirlinks) applies to all symlinks to directories in the source.  If
+you want to follow only a few specified symlinks, a trick you can use is to
+pass them as additional source args with a trailing slash, using bf(--relative)
+to make the paths match up right.  For example:
+
+quote(tt(rsync -r --relative src/./ src/./follow-me/ dest/))
+
+This works because rsync calls bf(lstat)(2) on the source arg as given, and the
+trailing slash makes bf(lstat)(2) follow the symlink, giving rise to a directory
+in the file-list which overrides the symlink found during the scan of "src/./".
+
 dit(bf(-K, --keep-dirlinks)) This option causes the receiving side to treat
 a symlink to a directory as though it were a real directory, but only if it
 matches a real directory from the sender.  Without this option, the
@@ -953,14 +970,18 @@ The source and destination systems must have compatible ACL entries for this
 option to work properly.  See the bf(--fake-super) option for a way to backup
 and restore ACLs that are not compatible.
 
-dit(bf(-X, --xattrs)) This option causes rsync to update the remote
-extended attributes to be the same as the local ones.
+dit(bf(-X, --xattrs)) This option causes rsync to update the destination
+extended attributes to be the same as the source ones.
 
 For systems that support extended-attribute namespaces, a copy being done by a
 super-user copies all namespaces except system.*.  A normal user only copies
 the user.* namespace.  To be able to backup and restore non-user namespaces as
 a normal user, see the bf(--fake-super) option.
 
+Note that this option does not copy rsyncs special xattr values (e.g. those
+used by bf(--fake-super)) unless you repeat the option (e.g. -XX).  This
+"copy all xattrs" mode cannot be used with bf(--fake-super).
+
 dit(bf(--chmod)) This option tells rsync to apply one or more
 comma-separated "chmod" strings to the permission of the files in the
 transfer.  The resulting value is treated as though it were the permissions
@@ -970,7 +991,10 @@ can seem to have no effect on existing files if bf(--perms) is not enabled.
 In addition to the normal parsing rules specified in the bf(chmod)(1)
 manpage, you can specify an item that should only apply to a directory by
 prefixing it with a 'D', or specify an item that should only apply to a
-file by prefixing it with a 'F'.  For example:
+file by prefixing it with a 'F'.  For example, the following will ensure
+that all directories get marked set-gid, that no files are other-writable,
+that both are user-writable and group-writable, and that both have
+consistent executability across all bits:
 
 quote(--chmod=Dg+s,ug+w,Fo-w,+X)