mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(6 Nov 2006)()()
+manpage(rsync)(1)(4 Oct 2007)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
manpagesection(ADVANCED USAGE)
-The syntax for requesting multiple files from a remote host involves using
-quoted spaces in the SRC. Some examples:
+The syntax for requesting multiple files from a remote host is done by
+specifying additional remote-host args in the same style as the first,
+or with the hostname omitted. For instance, all these work:
-quote(tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
+quote(tt(rsync -av host:file1 :file2 host:file{3,4} /dest/)nl()
+tt(rsync -av host::modname/file{1,2} host::modname/file3 /dest/)nl()
+tt(rsync -av host::modname/file1 ::modname/file{3,4}))
-This would copy file1 and file2 into /dest from an rsync daemon. Each
-additional arg must include the same "modname/" prefix as the first one,
-and must be preceded by a single space. All other spaces are assumed
-to be a part of the filenames.
+Older versions of rsync required using quoted spaces in the SRC, like these
+examples:
-quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest))
+quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest)nl()
+tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
-This would copy file1 and file2 into /dest using a remote shell. This
-word-splitting is done by the remote shell, so if it doesn't work it means
-that the remote shell isn't configured to split its args based on
-whitespace (a very rare setting, but not unknown). If you need to transfer
-a filename that contains whitespace, you'll need to either escape the
-whitespace in a way that the remote shell will understand, or use wildcards
-in place of the spaces. Two examples of this are:
+This word-splitting still works (by default) in the latest rsync, but is
+not as easy to use as the first method.
-quote(
-tt(rsync -av host:'file\ name\ with\ spaces' /dest)nl()
-tt(rsync -av host:file?name?with?spaces /dest)nl()
-)
+If you need to transfer a filename that contains whitespace, you can either
+specify the bf(--protect-args) (bf(-s)) option, or you'll need to escape
+the whitespace in a way that the remote shell will understand. For
+instance:
-This latter example assumes that your shell passes through unmatched
-wildcards. If it complains about "no match", put the name in quotes.
+quote(tt(rsync -av host:'file\ name\ with\ spaces' /dest))
manpagesection(CONNECTING TO AN RSYNC DAEMON)
If bf(--perms) is enabled, this option is ignored.
dit(bf(-A, --acls)) This option causes rsync to update the destination
-ACLs to be the same as the source ACLs. This nonstandard option only
-works if the remote rsync also supports it. bf(--acls) implies bf(--perms).
+ACLs to be the same as the source ACLs.
+The option also implies bf(--perms).
+
+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. This will work
-only if the remote machine's rsync also supports this option.
+extended attributes to be the same as the local 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.
dit(bf(--chmod)) This option tells rsync to apply one or more
comma-separated "chmod" strings to the permission of the files in the
destination file to be the same as the source file, but only if the
receiving rsync is being run as the super-user (see also the bf(--super)
and bf(--fake-super) options).
-Without this option, the owner is set to the invoking user on the
-receiving side.
+Without this option, the owner of new and/or transferred files are set to
+the invoking user on the receiving side.
The preservation of ownership will associate matching names by default, but
may fall back to using the ID number in some circumstances (see also the
super-user can use bf(--no-super).
dit(bf(--fake-super)) When this option is enabled, rsync simulates
-super-user activities by saving/restoring the privileged attributes via a
-special extended attribute that is attached to each file (as needed). This
+super-user activities by saving/restoring the privileged attributes via
+special extended attributes that are attached to each file (as needed). This
includes the file's owner and group (if it is not the default), the file's
device info (device & special files are created as empty text files), and
any permission bits that we won't allow to be set on the real file (e.g.
the real file gets u-s,g-s,o-t for safety) or that would limit the owner's
access (since the real super-user can always access/change a file, the
files we create can always be accessed/changed by the creating user).
+This option also handles ACLs (if bf(--acls) was specified) and non-user
+extended attributes (if bf(--xattrs) was specified).
+
+This is a good way to backup data withou using a super-user, and to store
+ACLs from incompatible systems.
The bf(--fake-super) option only affects the side where the option is used.
To affect the remote side of a remote-shell connection, specify an rsync
Since there is only one "side" in a local copy, this option affects both
the sending and recieving of files. You'll need to specify a copy using
-"localhost" if you need to avoid this. Note, however, that it is always
-safe to copy from some non-fake-super files into some fake-super files
-using a local bf(--fake-super) command because the non-fake source files
-will just have their normal attributes.
+"localhost" if you need to avoid this, possibly using the "lsh" shell
+script (from the support directory) as a substitute for an actual remote
+shell (see bf(--rsh)).
This option is overridden by both bf(--super) and bf(--no-super).
manpagesection(VERSION)
-This man page is current for version 2.6.9 of rsync.
+This man page is current for version 3.0.0pre1 of rsync.
manpagesection(INTERNAL OPTIONS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff