X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/bbd6f4ba8e1a36de8a3cae4b013c99ffa77d9f8d..b35d0d8e9ae9c5407c9f781b545f8a66b9caa9d0:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 0bb19448..6282e635 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(29 May 2001)()() +manpage(rsync)(1)(25 Jan 2002)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -19,7 +19,7 @@ manpagedescription() 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 speedup file transfers when the destination file already +greatly speed up file transfers when the destination file already exists. The rsync remote-update protocol allows rsync to transfer just the @@ -81,7 +81,7 @@ Once installed you can use rsync to any machine that you can use rsh to. rsync uses rsh for its communications, unless both the source and destination are local. -You can also specify an alternative to rsh, by either using the -e +You can also specify an alternative to rsh, either by using the -e command line option, or by setting the RSYNC_RSH environment variable. One common substitute is to use ssh, which offers a high degree of @@ -139,10 +139,10 @@ It is also possible to use rsync without using rsh or ssh as the transport. In this case you will connect to a remote rsync server running on TCP port 873. -You may establish the connetcion via a web proxy by setting the +You may establish the connection via a web proxy by setting the environment variable RSYNC_PROXY to a hostname:port pair pointing to -your web proxy. Note that your web proxy must allow proxying to port -873, this must be configured in your proxy servers ruleset. +your web proxy. Note that your web proxy's configuration must allow +proxying to port 873. Using rsync in this way is the same as using it with rsh or ssh except that: @@ -226,8 +226,8 @@ verb( --backup-dir make backups into this directory --suffix=SUFFIX override backup suffix -u, --update update only (don't overwrite newer files) - -l, --links preserve soft links - -L, --copy-links treat soft links like regular files + -l, --links copy symlinks as symlinks + -L, --copy-links copy the referent of symlinks --copy-unsafe-links copy links outside the source tree --safe-links ignore links outside the destination tree -H, --hard-links preserve hard links @@ -239,12 +239,14 @@ verb( -S, --sparse handle sparse files efficiently -n, --dry-run show what would have been transferred -W, --whole-file copy whole files, no incremental checks + --no-whole-file turn off --whole-file -x, --one-file-system don't cross filesystem boundaries -B, --block-size=SIZE checksum blocking size (default 700) -e, --rsh=COMMAND specify rsh replacement --rsync-path=PATH specify path to rsync on the remote machine -C, --cvs-exclude auto ignore files in the same way CVS does --existing only update files that already exist + --ignore-existing ignore files that already exist on the receiving side --delete delete files that don't exist on the sending side --delete-excluded also delete excluded files on the receiving side --delete-after delete after transferring, not before @@ -272,13 +274,14 @@ verb( --config=FILE specify alternate rsyncd.conf file --port=PORT specify alternate rsyncd port number --blocking-io use blocking IO for the remote shell + --no-blocking-io turn off --blocking-io --stats give some file transfer stats --progress show progress during transfer --log-format=FORMAT log file transfers using specified format --password-file=FILE get password from FILE --bwlimit=KBPS limit I/O bandwidth, KBytes per second - -f, --read-batch=FILE read batch file - -F, --write-batch write batch file + --read-batch=PREFIX read batch fileset starting with PREFIX + --write-batch=PREFIX write batch fileset starting with PREFIX -h, --help show this help screen @@ -378,17 +381,16 @@ dit(bf(-u, --update)) This forces rsync to skip any files for which the destination file already exists and has a date later than the source file. -dit(bf(-l, --links)) This tells rsync to recreate symbolic links on the -remote system to be the same as the local system. Without this -option, all symbolic links are skipped. +dit(bf(-l, --links)) When symlinks are encountered, recreate the +symlink on the destination. -dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just -like ordinary files. +dit(bf(-L, --copy-links)) When symlinks are encountered, the file that +they point to is copied, rather than the symlink. -dit(bf(--copy-unsafe-links)) This tells rsync to treat symbolic links that -point outside the source tree like ordinary files. Absolute symlinks are -also treated like ordinary files, and so are any symlinks in the source -path itself when --relative is used. +dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of +symbolic links that point outside the source tree. Absolute symlinks +are also treated like ordinary files, and so are any symlinks in the +source path itself when --relative is used. dit(bf(--safe-links)) This tells rsync to ignore any symbolic links which point outside the destination tree. All absolute symlinks are @@ -411,19 +413,21 @@ target machines is higher than the bandwidth to disk (especially when the "disk" is actually a networked file system). This is the default when both the source and target are on the local machine. +dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the +default. + dit(bf(-p, --perms)) This option causes rsync to update the remote permissions to be the same as the local permissions. -dit(bf(-o, --owner)) This option causes rsync to update the remote owner -of the file to be the same as the local owner. This is only available -to the super-user. Note that if the source system is a daemon using chroot, -the --numeric-ids option is implied because the source system cannot get -access to the usernames. +dit(bf(-o, --owner)) This option causes rsync to set the owner of the +destination file to be the same as the source file. On most systems, +only the super-user can set file ownership. -dit(bf(-g, --group)) This option causes rsync to update the remote group -of the file to be the same as the local group. If the receving system is -not running as the super-user, only groups that the receiver is a member of -will be preserved (by group name, not group id number). +dit(bf(-g, --group)) This option causes rsync to set the group of the +destination file to be the same as the source file. If the receiving +program is not running as the super-user, only groups that the +receiver is a member of will be preserved (by group name, not group id +number). dit(bf(-D, --devices)) This option causes rsync to transfer character and block device information to the remote system to recreate these @@ -454,6 +458,10 @@ contents of only one filesystem. dit(bf(--existing)) This tells rsync not to create any new files - only update files that already exist on the destination. +dit(bf(--ignore-existing)) +This tells rsync not to update files that already exist on +the destination. + dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM files or directories. This is useful when mirroring very large trees to prevent disasters. @@ -487,12 +495,9 @@ dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files even when there are IO errors. dit(bf(--force)) This options tells rsync to delete directories even if -they are not empty. This applies to both the --delete option and to -cases where rsync tries to copy a normal file but the destination -contains a directory of the same name. - -Since this option was added, deletions were reordered to be done depth-first -so it is hardly ever needed anymore except in very obscure cases. +they are not empty when they are to be replaced by non-directories. This +is only relevant without --delete because deletions are now done depth-first. +Requires the --recursive option (which is implied by -a) to have any effect. dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in the rsync algorithm. See the technical report for details. @@ -551,8 +556,9 @@ quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state then files listed in a $HOME/.cvsignore are added to the list and any files listed in the CVSIGNORE environment variable (space delimited). -Finally in each directory any files listed in the .cvsignore file in -that directory are added to the list. +Finally, any file is ignored if it is in the same directory as a +.cvsignore file and matches one of the patterns listed therein. See +the bf(cvs(1)) manual for more information. dit(bf(--csum-length=LENGTH)) By default the primary checksum used in rsync is a very strong 16 byte MD4 checksum. In most cases you will @@ -609,21 +615,24 @@ what ownership to give files. The special uid 0 and the special group 0 are never mapped via user/group names even if the --numeric-ids option is not specified. -If the source system is a daemon using chroot, or if a user or group name -does not exist on the destination system, then the numeric id from the -source system is used instead. +If the source system is a daemon using chroot, or if a user or group +name does not exist on the destination system, then the numeric id +from the source system is used instead. dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO timeout in seconds. If no data is transferred for the specified time then rsync will exit. The default is 0, which means no timeout. -dit(bf(--daemon)) This tells rsync that it is to run as a rsync -daemon. If standard input is a socket then rsync will assume that it -is being run via inetd, otherwise it will detach from the current -terminal and become a background daemon. The daemon will read the -config file (/etc/rsyncd.conf) on each connect made by a client and -respond to requests accordingly. See the rsyncd.conf(5) man page for more -details. +dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The +daemon may be accessed using the bf(host::module) or +bf(rsync://host/module/) syntax. + +If standard input is a socket then rsync will assume that it is being +run via inetd, otherwise it will detach from the current terminal and +become a background daemon. The daemon will read the config file +(/etc/rsyncd.conf) on each connect made by a client and respond to +requests accordingly. See the rsyncd.conf(5) man page for more +details. dit(bf(--no-detach)) When running as a daemon, this option instructs rsync to not detach itself and become a background process. This @@ -653,6 +662,9 @@ the default "rsh", this defaults to blocking IO, otherwise it defaults to non-blocking IO. You may find the --blocking-io option is needed for some remote shells that can't handle non-blocking IO. Ssh prefers blocking IO. +dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the +default. + dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the rsync client logs to stdout on a per-file basis. The log format is specified using the same format conventions as the log format option in @@ -694,10 +706,13 @@ transfer was too fast, it will wait before sending the next data block. The result is an average transfer rate equalling the specified limit. A value of zero specifies no limit. -dit(bf(--read-batch)) Apply a previously generated change batch. +dit(bf(--write-batch=PREFIX)) Generate a set of files that can be +transferred as a batch update. Each filename in the set starts with +PREFIX. See the "BATCH MODE" section for details. -dit(bf(--write-batch)) Generate a set of files that can be transferred -as a batch update. +dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch, +using the fileset whose filenames start with PREFIX. See the "BATCH +MODE" section for details. enddit() @@ -706,7 +721,7 @@ manpagesection(EXCLUDE PATTERNS) The exclude and include patterns specified to rsync allow for flexible selection of which files to transfer and which files to skip. -rsync builds a ordered list of include/exclude options as specified on +rsync builds an ordered list of include/exclude options as specified on the command line. When a filename is encountered, rsync checks the name against each exclude/include pattern in turn. The first matching pattern is acted on. If it is an exclude pattern, then that file is @@ -759,7 +774,7 @@ itemize( part of an include option. The "- " part is discarded before matching. it() if the pattern is a single exclamation mark ! then the current - exclude list is reset, removing all previous exclude patterns. + include/exclude list is reset, removing all previously defined patterns. ) The +/- rules are most useful in exclude lists, allowing you to have a @@ -791,27 +806,110 @@ itemize( manpagesection(BATCH MODE) -The following call generates 4 files that encapsulate the information -for synchronizing the contents of bf(target_dir) with the updates found in -bf(src_dir) +bf(Note:) Batch mode should be considered experimental in this version +of rsync. The interface or behaviour may change before it stabilizes. + +Batch mode can be used to apply the same set of updates to many +identical systems. Suppose one has a tree which is replicated on a +number of hosts. Now suppose some changes have been made to this +source tree and those changes need to be propagated to the other +hosts. In order to do this using batch mode, rsync is run with the +write-batch option to apply the changes made to the source tree to one +of the destination trees. The write-batch option causes the rsync +client to store the information needed to repeat this operation against +other destination trees in a batch update fileset (see below). The +filename of each file in the fileset starts with a prefix specified by +the user as an argument to the write-batch option. This fileset is +then copied to each remote host, where rsync is run with the read-batch +option, again specifying the same prefix, and the destination tree. +Rsync updates the destination tree using the information stored in the +batch update fileset. + +The fileset consists of 4 files: -quote( -$ rsync -F [other rsync options here] \nl() - /somewhere/src_dir /somewhere/target_dir +itemize( +it() bf(.rsync_argvs) command-line arguments +it() bf(.rsync_flist) rsync internal file metadata +it() bf(.rsync_csums) rsync checksums +it() bf(.rsync_delta) data blocks for file update & change ) -The generated files are labeled with a common timestamp: +The .rsync_argvs file contains a command-line suitable for updating a +destination tree using that batch update fileset. It can be executed +using a Bourne(-like) shell, optionally passing in an alternate +destination tree pathname which is then used instead of the original +path. This is useful when the destination tree path differs from the +original destination tree path. -itemize( -it() bf(rsync_argvs.) command-line arguments -it() bf(rsync_flist.) rsync internal file metadata -it() bf(rsync_csums.) rsync checksums -it() bf(rsync_delta.) data blocks for file update & change +Generating the batch update fileset once saves having to perform the +file status, checksum and data block generation more than once when +updating multiple destination trees. Multicast transport protocols can +be used to transfer the batch update files in parallel to many hosts at +once, instead of sending the same data to every host individually. + +Example: + +verb( +$ rsync --write_batch=pfx -a /source/dir/ /adest/dir/ +$ rcp pfx.rsync_* remote: +$ rsh remote rsync --read_batch=pfx -a /bdest/dir/ +# or alternatively +$ rsh remote ./pfx.rsync_argvs /bdest/dir/ ) +In this example, rsync is used to update /adest/dir/ with /source/dir/ +and the information to repeat this operation is stored in the files +pfx.rsync_*. These files are then copied to the machine named "remote". +Rsync is then invoked on "remote" to update /bdest/dir/ the same way as +/adest/dir/. The last line shows the rsync_argvs file being used to +invoke rsync. + +Caveats: + +The read-batch option expects the destination tree it is meant to update +to be identical to the destination tree that was used to create the +batch update fileset. When a difference between the destination trees +is encountered the update will fail at that point, leaving the +destination tree in a partially updated state. In that case, rsync can +be used in its regular (non-batch) mode of operation to fix up the +destination tree. + +The rsync version used on all destinations should be identical to the +one used on the original destination. + +The -z/--compress option does not work in batch mode and yields a usage +error. A separate compression tool can be used instead to reduce the +size of the batch update files for transport to the destination. + +The -n/--dryrun option does not work in batch mode and yields a runtime +error. + See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical reports. +manpagesection(SYMBOLIC LINKS) + +Three basic behaviours are possible when rsync encounters a symbolic +link in the source directory. + +By default, symbolic links are not transferred at all. A message +"skipping non-regular" file is emitted for any symlinks that exist. + +If bf(--links) is specified, then symlinks are recreated with the same +target on the destination. Note that bf(--archive) implies +bf(--links). + +If bf(--copy-links) is specified, then symlinks are "collapsed" by +copying their referent, rather than the symlink. + +rsync also distinguishes "safe" and "unsafe" symbolic links. An +example where this might be used is a web site mirror that wishes +ensure the rsync module they copy does not include symbolic links to +bf(/etc/passwd) in the public section of the site. Using +bf(--copy-unsafe-links) will cause any links to be copied as the file +they point to on the destination. Using bf(--safe-links) will cause +unsafe links to be ommitted altogether. + manpagesection(DIAGNOSTICS) rsync occasionally produces error messages that may seem a little @@ -937,16 +1035,22 @@ Jean-loup Gailly and Mark Adler. manpagesection(THANKS) Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell -and David Bell for helpful suggestions and testing of rsync. I've -probably missed some people, my apologies if I have. +and David Bell for helpful suggestions, patches and testing of rsync. +I've probably missed some people, my apologies if I have. + +Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer. manpageauthor() -rsync was written by Andrew Tridgell and Paul Mackerras. They may be -contacted via email at tridge@samba.org and -Paul.Mackerras@cs.anu.edu.au +rsync was written by Andrew Tridgell and Paul +Mackerras. -rsync is now also maintained by Martin Pool +rsync is now maintained by Martin Pool . +Mailing lists for support and development are available at +url(http://lists.samba.org)(lists.samba.org) +If you suspect you have found a security vulnerability in rsync, +please send it directly to Martin Pool and Andrew Tridgell. For other +enquiries, please use the mailing list.