X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/1874f7e2e176dc7a3c2f05687a28bcbfe5964b06..27999abab48979c7306a1c335f8e264c6c200457:/rsync.yo diff --git a/rsync.yo b/rsync.yo index aa9ccc8b..a98d1eab 100644 --- a/rsync.yo +++ b/rsync.yo @@ -21,7 +21,7 @@ rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] manpagedescription() -rsync is a program that behaves in much the same way that rcp does, +Rsync is a program that behaves in much the same way that rcp does, but has many more options and uses the rsync remote-update protocol to greatly speed up file transfers when the destination file is being updated. @@ -31,7 +31,7 @@ differences between two sets of files across the network connection, using an efficient checksum-search algorithm described in the technical report that accompanies this package. -It finds files that need to be transferred using a "quick check" algorithm +Rsync finds files that need to be transferred using a "quick check" algorithm that looks for files that have changed in size or in last-modified time (by default). Any changes in the other preserved attributes (as requested by options) are made on the destination file directly when the quick check @@ -219,6 +219,21 @@ environment variable RSYNC_PROXY to a hostname:port pair pointing to your web proxy. Note that your web proxy's configuration must support proxy connections to port 873. +You may also establish a daemon connection using a program as a proxy by +setting the environment variable RSYNC_CONNECT_PROG to the commands you +wish to run in place of making a direct socket connection. The string may +contain the escape "%H" to represent the hostname specified in the rsync +command (so use "%%" if you need a single "%" in your string). For +example: + +verb( export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873' + rsync -av targethost1::module/src/ /dest/ + rsync -av rsync:://targethost2/module/src/ /dest/ ) + +The command specifed above uses ssh to run nc (netcat) on a proxyhost, +which forwards all data to port 873 (the rsync daemon) on the targethost +(%H). + manpagesection(USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION) It is sometimes useful to use various features of an rsync daemon (such as @@ -318,6 +333,7 @@ to the detailed description below for a complete description. verb( -u, --update skip files that are newer on the receiver --inplace update destination files in-place --append append data onto shorter files + --append-verify --append w/old data in file cheksum -d, --dirs transfer directories without recursing -l, --links copy symlinks as symlinks -L, --copy-links transform symlink into referent file/dir @@ -330,14 +346,14 @@ to the detailed description below for a complete description. verb( -E, --executability preserve executability --chmod=CHMOD affect file and/or directory permissions -A, --acls preserve ACLs (implies -p) - -X, --xattrs preserve extended attrs (implies -p) + -X, --xattrs preserve extended attributes -o, --owner preserve owner (super-user only) -g, --group preserve group --devices preserve device files (super-user only) --specials preserve special files -D same as --devices --specials - -t, --times preserve times - -O, --omit-dir-times omit directories when preserving times + -t, --times preserve modification times + -O, --omit-dir-times omit directories from --times --super receiver attempts super-user activities --fake-super store/recover privileged attrs using xattrs -S, --sparse handle sparse files efficiently @@ -378,6 +394,7 @@ to the detailed description below for a complete description. verb( --link-dest=DIR hardlink to files in DIR when unchanged -z, --compress compress file data during the transfer --compress-level=NUM explicitly set compression level + --skip-compress=LIST skip compressing files with suffix in LIST -C, --cvs-exclude auto-ignore files in the same way CVS does -f, --filter=RULE add a file-filtering RULE -F same as --filter='dir-merge /.rsync-filter' @@ -388,6 +405,7 @@ to the detailed description below for a complete description. verb( --include-from=FILE read include patterns from FILE --files-from=FILE read list of source-file names from FILE -0, --from0 all *from/filter files are delimited by 0s + -s, --protect-args no space-splitting; wildcard chars only --address=ADDRESS bind address for outgoing socket to daemon --port=PORT specify double-colon alternate port number --sockopts=OPTIONS specify custom TCP options @@ -484,7 +502,7 @@ be updated. dit(bf(--size-only)) This modifies rsync's "quick check" algorithm for finding files that need to be transferred, changing it from the default of transferring files with either a changed size or a changed last-modified -time to just transferring files that have a changed size. This is useful +time to just looking for files that have changed in size. This is useful when starting to use rsync after using another mirroring system which may not preserve timestamps exactly. @@ -554,19 +572,21 @@ Beginning with rsync 3.0.0, the recursive algorithm used is now an incremental scan that uses much less memory than before and begins the transfer after the scanning of the first few directories have been completed. This incremental scan only affects our recursion algorithm, and -does not change a non-recursive transfer (e.g. when using a fully-specified -bf(--files-from) list). It is also only possible when both ends of the -transfer are at least version 3.0.0. +does not change a non-recursive transfer. It is also only possible when +both ends of the transfer are at least version 3.0.0. Some options require rsync to know the full file list, so these options disable the incremental recursion mode. These include: bf(--delete-before), -bf(--delete-after), bf(--prune-empty-dirs), bf(--delay-updates), and bf(--hard-links). +bf(--delete-after), bf(--prune-empty-dirs), and bf(--delay-updates). Because of this, the default delete mode when you specify bf(--delete) is now bf(--delete-during) when both ends of the connection are at least 3.0.0 (use bf(--del) or bf(--delete-during) to request this improved deletion mode explicitly). See also the bf(--delete-delay) option that is a better choice than using bf(--delete-after). +Incremental recursion can be disabled using the bf(--no-inc-recursive) +option or its shorter bf(--no-i-r) alias. + dit(bf(-R, --relative)) Use relative paths. This means that the full path names specified on the command line are sent to the server rather than just the last parts of the filenames. This is particularly useful when @@ -664,16 +684,15 @@ if no -bf(-backup-dir) was specified, otherwise it is an empty string. dit(bf(-u, --update)) This forces rsync to skip any files which exist on the destination and have a modified time that is newer than the source -file. (If an existing destination file has a modify time equal to the +file. (If an existing destination file has a modification time equal to the source file's, it will be updated if the sizes are different.) -In the current implementation of bf(--update), a difference of file format -between the sender and receiver is always -considered to be important enough for an update, no matter what date -is on the objects. In other words, if the source has a directory or a -symlink where the destination has a file, the transfer would occur -regardless of the timestamps. This might change in the future (feel -free to comment on this on the mailing list if you have an opinion). +Note that this does not affect the copying of symlinks or other special +files. Also, a difference of file format between the sender and receiver +is always considered to be important enough for an update, no matter what +date is on the objects. In other words, if the source has a directory +where the destination has a file, the transfer would occur regardless of +the timestamps. dit(bf(--inplace)) This causes rsync not to create a new copy of the file and then move it into place. Instead rsync will overwrite the existing @@ -701,13 +720,22 @@ receiving user. dit(bf(--append)) This causes rsync to update a file by appending data onto the end of the file, which presumes that the data that already exists on the receiving side is identical with the start of the file on the sending -side. If that is not true, the file will fail the checksum test, and the -resend will do a normal bf(--inplace) update to correct the mismatched data. -Only files on the receiving side that are shorter than the corresponding -file on the sending side (as well as new files) are sent. -Implies bf(--inplace), but does not conflict with bf(--sparse) (though the -bf(--sparse) option will be auto-disabled if a resend of the already-existing -data is required). +side. Any files that are the same size or shorter on the receiving size +are skipped. Files that do not yet exist on the receiving side are also +sent, since they are considered to have 0 length. Implies bf(--inplace), +but does not conflict with bf(--sparse) (since it is always extending a +file's length). + +dit(bf(--append-verify)) This works just like the bf(--append) option, but +the existing data on the receiving side is included in the full-file +checksum verification step, which will cause a file to be resent if the +final verification step fails (rsync uses a normal, non-appending +bf(--inplace) transfer for the resend). + +Note: prior to rsync 3.0.0, the bf(--append) option worked like +bf(--append-verify), so if you are interacting with an older rsync (or the +transfer is using a protocol prior to 30), specifying either append option +will initiate an bf(--append-verify) transfer. dit(bf(-d, --dirs)) Tell the sending side to include any directories that are encountered. Unlike bf(--recursive), a directory's contents are not copied @@ -775,6 +803,12 @@ as though they were separate files. Note that rsync can only detect hard links if both parts of the link are in the list of files being sent. +If incremental recursion is active (see bf(--recursive)), rsync may transfer +a missing hard-linked file before it finds that another link for the file +exists elsewhere in the hierarchy. This does not affect the accuracy of +the transfer, just its efficiency. One way to avoid this is to disable +incremental recursion using the bf(--no-inc-recursive) option. + dit(bf(-p, --perms)) This option causes the receiving rsync to set the destination permissions to be the same as the source permissions. (See also the bf(--chmod) option for a way to modify what rsync considers to @@ -848,8 +882,7 @@ works if the remote rsync also supports it. bf(--acls) implies bf(--perms). 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 supports this option also. This is -a non-standard option. +only if the remote machine's rsync also supports this 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 @@ -933,9 +966,8 @@ 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 or -directory, the files we create can always be accessed/changed by the -creating user). +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). 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 @@ -965,7 +997,7 @@ correctly and ends up corrupting the files. dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers, instead it will just report the actions it would have taken. -dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm +dit(bf(-W, --whole-file)) With this option the delta transfer algorithm is not used and the whole file is sent as-is instead. The transfer may be faster if this option is used when the bandwidth between the source and destination machines is higher than the bandwidth to disk (especially when the @@ -994,12 +1026,20 @@ dit(bf(--existing, --ignore-non-existing)) This tells rsync to skip creating files (including directories) that do not exist yet on the destination. If this option is combined with the bf(--ignore-existing) option, no files will be updated -(which can be useful if all you want to do is to delete extraneous files). +(which can be useful if all you want to do is delete extraneous files). dit(bf(--ignore-existing)) This tells rsync to skip updating files that already exist on the destination (this does em(not) ignore existing directories, or nothing would get done). See also bf(--existing). +This option can be useful for those doing backups using the bf(--link-dest) +option when they need to continue a backup run that got interrupted. Since +a bf(--link-dest) run is copied into a new directory hierarchy (when it is +used properly), using bf(--ignore existing) will ensure that the +already-handled files don't get tweaked (which avoids a change in +permissions on the hard-linked files). This does mean that this option +is only looking at the existing files in the destination hierarchy itself. + dit(bf(--remove-source-files)) This tells rsync to remove from the sending side the files (meaning non-directories) that are a part of the transfer and have been successfully duplicated on the receiving side. @@ -1092,13 +1132,15 @@ using bf(--delete-after), and it used to be non-functional unless the bf(--recursive) option was also enabled. dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM -files or directories. -Beginning with version 3.0.0, you may specify bf(--max-delete=0) to -be warned about any extraneous files in the destination, but be very -careful to never specify a 0 value to an older rsync client, or the -option will be silently ignored. (A 3.0.0 client will die with an -error if the remote rsync is not new enough to handle the situation.) -This is useful when mirroring very large trees to prevent disasters. +files or directories. If that limit is exceeded, a warning is output +and rsync exits with an error code of 25 (new for 3.0.0). + +Also new for version 3.0.0, you may specify bf(--max-delete=0) to be warned +about any extraneous files in the destination without removing any of them. +Older clients interpreted this as "unlimited", so if you don't know what +version the client is, you can use the less obvious bf(--max-delete=-1) as +a backward-compatible way to specify that no deletions be allowed (though +older versions didn't warn when the limit was exceeded). dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any file that is larger than the specified SIZE. The SIZE value can be @@ -1273,7 +1315,7 @@ quote(itemization( bf(--files-from), as does bf(--no-R) and all other options). )) -The file names that are read from the FILE are all relative to the +The filenames that are read from the FILE are all relative to the source dir -- any leading slashes are removed and no ".." references are allowed to go higher than the source dir. For example, take this command: @@ -1311,6 +1353,21 @@ merged files specified in a bf(--filter) rule. It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore file are split on whitespace). +If the bf(--iconv) and bf(--protect-args) options are specified and the +bf(--files-from) filenames are being sent from one host to another, the +filenames will be translated from the sending host's charset to the +receiving host's charset. + +dit(bf(-s, --protect-args)) This option sends all filenames and some options to +the remote rsync without allowing the remote shell to interpret them. This +means that spaces are not split in names, and any non-wildcard special +characters are not translated (such as ~, $, ;, &, etc.). Wildcards are +expanded on the remote host by rsync (instead of the shell doing it). + +If you use this option with bf(--iconv), the args will also be translated +from the local to the remote character set. The translation happens before +wild-cards are expanded. See also the bf(--files-from) option. + dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a scratch directory when creating temporary copies of the files transferred on the receiving side. The default behavior is to create each temporary @@ -1431,10 +1488,40 @@ be achieved by using a compressing remote shell or a compressing transport because it takes advantage of the implicit information in the matching data blocks that are not explicitly sent over the connection. +See the bf(--skip-compress) option for the default list of file suffixes +that will not be compressed. + dit(bf(--compress-level=NUM)) Explicitly set the compression level to use (see bf(--compress)) instead of letting it default. If NUM is non-zero, the bf(--compress) option is implied. +dit(bf(--skip-compress=LIST)) Override the list of file suffixes that will +not be compressed. The bf(LIST) should be one or more file suffixes +(without the dot) separated by slashes (/). + +You may specify an empty string to indicate that no file should be skipped. + +Simple character-class matching is supported: each must consist of a list +of letters inside the square brackets (e.g. no special classes, such as +"[:alpha:]", are supported). + +The characters asterisk (*) and question-mark (?) have no special meaning. + +Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules +matches 2 suffixes): + +verb( --skip-compress=gz/jpg/mp[34]/7z/bz2) + +The default list of suffixes that will not be compressed is this (several +of these are newly added for 3.0.0): + +verb( gz/zip/z/rpm/deb/iso/bz2/t[gb]z/7z/mp[34]/mov/avi/ogg/jpg/jpeg) + +This list will be replaced by your bf(--skip-compress) list in all but one +situation: a copy from a daemon rsync will add your skipped suffixes to +its list of non-compressing files (and its list may be configured to a +different default). + dit(bf(--numeric-ids)) With this option rsync will transfer numeric group and user IDs rather than using user and group names and mapping them at both ends. @@ -1530,9 +1617,9 @@ quote(itemization( by the file transfer. it() A bf(t) means the modification time is different and is being updated to the sender's value (requires bf(--times)). An alternate value of bf(T) - means that the time will be set to the transfer time, which happens - anytime a symlink is transferred, or when a file or device is transferred - without bf(--times). + means that the modification time will be set to the transfer time, which happens + anytime a symlink is transferred, or when a regular file or device is + transferred without bf(--times). it() A bf(p) means the permissions are different and are being updated to the sender's value (requires bf(--perms)). it() An bf(o) means the owner is different and is being updated to the @@ -1667,7 +1754,7 @@ after it has served its purpose. Note that if bf(--whole-file) is specified (or implied), any partial-dir file that is found for a file that is being updated will simply be removed (since -rsync is sending files without using the incremental rsync algorithm). +rsync is sending files without using the delta transfer algorithm). Rsync will create the em(DIR) if it is missing (just the last dir -- not the whole path). This makes it easy to use a relative path (such as @@ -1785,7 +1872,7 @@ sender's file, which is being reconstructed at a rate of 110.64 kilobytes per second, and the transfer will finish in 4 seconds if the current rate is maintained until the end. -These statistics can be misleading if the incremental transfer algorithm is +These statistics can be misleading if the delta transfer algorithm is in use. For example, if the sender's file consists of the basis file followed by additional data, the reported rate will probably drop dramatically when the receiver gets to the literal data, and the transfer @@ -1882,20 +1969,25 @@ Finally, you can specify a CONVERT_SPEC of "-" to turn off any conversion. The default setting of this option is site-specific, and can also be affected via the RSYNC_ICONV environment variable. +If you specify the bf(--protect-args) option (bf(-s)), rsync will translate +the filenames you specify on the command-line that are being sent to the +remote host. See also the bf(--files-from) option. + Note that rsync does not do any conversion of names in filter files -(including include/exclude files), in a files-from file, nor those -specified on the command line. It is up to you to ensure that you're -requesting the right names from a remote server, and you can specify -extra include/exclude rules if there are filename differences on the -two sides that need to be accounted for. (In the future there may be -a way to specify a UTF-8 filter rule that gets auto-converted to the -local side's character set.) +(including include/exclude files). It is up to you to ensure that you're +specifying matching rules that can match on both sides of the transfer. +For instance, you can specify extra include/exclude rules if there are +filename differences on the two sides that need to be accounted for. dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6 when creating sockets. This only affects sockets that rsync has direct control over, such as the outgoing socket when directly contacting an rsync daemon. See also these options in the bf(--daemon) mode section. +If rsync was complied without support for IPv6, the bf(--ipv6) option +will have no effect. The bf(--version) output will tell you if this +is the case. + dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer NUM. This 4 byte checksum seed is included in each block and file MD4 checksum calculation. By default the checksum seed is generated @@ -1978,6 +2070,10 @@ versions of Linux to work around an IPv6 bug in the kernel (if you see an "address already in use" error when nothing else is using the port, try specifying bf(--ipv6) or bf(--ipv4) when starting the daemon). +If rsync was complied without support for IPv6, the bf(--ipv6) option +will have no effect. The bf(--version) output will tell you if this +is the case. + dit(bf(-h, --help)) When specified after bf(--daemon), print a short help page describing the options available for starting an rsync daemon. enddit() @@ -2054,20 +2150,19 @@ itemization( particular spot in the hierarchy of files, otherwise it is matched against the end of the pathname. This is similar to a leading ^ in regular expressions. - Thus "/foo" would match a file named "foo" at either the "root of the + Thus "/foo" would match a name of "foo" at either the "root of the transfer" (for a global rule) or in the merge-file's directory (for a per-directory rule). - An unqualified "foo" would match any file or directory named "foo" - anywhere in the tree because the algorithm is applied recursively from - the + An unqualified "foo" would match a name of "foo" anywhere in the + tree because the algorithm is applied recursively from the top down; it behaves as if each path component gets a turn at being the - end of the file name. Even the unanchored "sub/foo" would match at + end of the filename. Even the unanchored "sub/foo" would match at any point in the hierarchy where a "foo" was found within a directory named "sub". See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify a pattern that matches at the root of the transfer. it() if the pattern ends with a / then it will only match a - directory, not a file, link, or device. + directory, not a regular file, symlink, or device. it() rsync chooses between doing a simple string match and wildcard matching by checking if the pattern contains one of these three wildcard characters: '*', '?', and '[' . @@ -2085,7 +2180,7 @@ itemization( can actually be any portion of a path from the starting directory on down.) it() a trailing "dir_name/***" will match both the directory (as if - "dir_name/" had been specified) and all the files in the directory + "dir_name/" had been specified) and everything in the directory (as if "dir_name/**" had been specified). This behavior was added in version 2.6.7. ) @@ -2128,7 +2223,7 @@ tt(- *)nl() Here are some examples of exclude/include matching: itemization( - it() "- *.o" would exclude all filenames matching *.o + it() "- *.o" would exclude all names matching *.o it() "- /foo" would exclude a file (or directory) named foo in the transfer-root directory it() "- foo/" would exclude any directory named foo @@ -2682,7 +2777,7 @@ values see also the comments on the bf(--delete) option -Please report bugs! See the website at +Please report bugs! See the web site at url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION)