X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/915dd20705ee32bd0c2a90e6f8e85e8c6a9c0ddf..db2b5cb75f4ce436232f5e4821c8d1e3c175de34:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 5cf489ef..96829ee5 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(26 Jan 2003)()() +manpage(rsync)(1)(1 Jan 2004)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -77,7 +77,7 @@ itemize( using a remote shell program as the transport, using rsync server on the remote machine. This is invoked when the destination path contains a :: separator and the - --rsh=COMMMAND option is also provided. + --rsh=COMMAND option is also provided. it() for listing files on a remote machine. This is done the same way as rsync transfers except that you leave off the @@ -111,7 +111,7 @@ manpagesection(USAGE) You use rsync in the same way you use rcp. You must specify a source and a destination, one of which may be remote. -Perhaps the best way to explain the syntax is some examples: +Perhaps the best way to explain the syntax is with some examples: quote(rsync *.c foo:src/) @@ -126,7 +126,7 @@ quote(rsync -avz foo:src/bar /data/tmp) This would recursively transfer all files from the directory src/bar on the machine foo into the /data/tmp/bar directory on the local machine. The files are transferred in "archive" mode, which ensures that symbolic -links, devices, attributes, permissions, ownerships etc are preserved +links, devices, attributes, permissions, ownerships, etc. are preserved in the transfer. Additionally, compression will be used to reduce the size of data portions of the transfer. @@ -162,8 +162,8 @@ running on TCP port 873. 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's configuration must allow -proxying to port 873. +your web proxy. Note that your web proxy's configuration must support +proxy connections to port 873. Using rsync in this way is the same as using it with a remote shell except that: @@ -217,7 +217,7 @@ used to check against the rsyncd.conf on the remote host. manpagesection(RUNNING AN RSYNC SERVER) -An rsync server is configured using a config file. Please see the +An rsync server is configured using a configuration file. Please see the rsyncd.conf(5) man page for more information. By default the configuration file is called /etc/rsyncd.conf, unless rsync is running over a remote shell program and is not running as root; in that case, the default name @@ -311,16 +311,16 @@ verb( --ignore-existing ignore files that already exist on receiver --delete delete files that don't exist on sender --delete-excluded also delete excluded files on receiver - --delete-after delete after transferring, not before - --ignore-errors delete even if there are IO errors + --delete-after receiver deletes after transfer, not before + --ignore-errors delete even if there are I/O errors --max-delete=NUM don't delete more than NUM files --partial keep partially transferred files --force force deletion of dirs even if not empty --numeric-ids don't map uid/gid values by user/group name - --timeout=TIME set IO timeout in seconds + --timeout=TIME set I/O timeout in seconds -I, --ignore-times turn off mod time & file size quick check --size-only ignore mod time for quick check (use size) - --modify-window=NUM use if mod times have reduced accuracy + --modify-window=NUM compare mod times with reduced accuracy -T --temp-dir=DIR create temporary files in directory DIR --compare-dest=DIR also compare received files relative to DIR --link-dest=DIR create hardlinks to DIR for unchanged files @@ -339,7 +339,7 @@ verb( --address=ADDRESS bind to the specified address --config=FILE specify alternate rsyncd.conf file --port=PORT specify alternate rsyncd port number - --blocking-io use blocking IO for the remote shell + --blocking-io use blocking I/O for the remote shell --no-blocking-io turn off --blocking-io --stats give some file transfer stats --progress show progress during transfer @@ -496,7 +496,7 @@ dit(bf(-W, --whole-file)) With this option the incremental rsync 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 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 +"disk" is actually a networked filesystem). 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 @@ -512,15 +512,20 @@ other files (including updated files) retain their existing permissions 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. Note that if the remote system -is a daemon using chroot, the --numeric-ids option is implied because the -remote system cannot get access to the usernames from /etc/passwd. +only the super-user can set file ownership. The preservation is done +primarily by name, but falls back to using the ID number if the ID has +no name on the sending side or has no match on the receiving side. +See also the --numeric-ids option and the "use chroot" setting in the +rsyncd.conf manpage. 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). +receiver is a member of will be preserved. The preservation is done +primarily by name, but falls back to using the ID number if the ID has +no name on the sending side or has no match on the receiving side. +See also the --numeric-ids option and the "use chroot" setting in the +rsyncd.conf manpage. dit(bf(-D, --devices)) This option causes rsync to transfer character and block device information to the remote system to recreate these @@ -569,7 +574,7 @@ This option can be dangerous if used incorrectly! It is a very good idea to run first using the dry run option (-n) to see what files would be deleted to make sure important files aren't listed. -If the sending side detects any IO errors then the deletion of any +If the sending side detects any I/O errors then the deletion of any files at the destination will be automatically disabled. This is to prevent temporary filesystem failures (such as NFS errors) on the sending side causing a massive deletion of files on the @@ -580,13 +585,13 @@ receiving side that are not on the sending side, this tells rsync to also delete any files on the receiving side that are excluded (see --exclude). Implies --delete. -dit(bf(--delete-after)) By default rsync does file deletions before -transferring files to try to ensure that there is sufficient space on -the receiving filesystem. If you want to delete after transferring -then use the --delete-after switch. Implies --delete. +dit(bf(--delete-after)) By default rsync does file deletions on the +receiving side before transferring files to try to ensure that there is +sufficient space on the receiving filesystem. If you want to delete +after transferring, use the --delete-after switch. Implies --delete. dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files -even when there are IO errors. +even when there are I/O errors. dit(bf(--force)) This options tells rsync to delete directories even if they are not empty when they are to be replaced by non-directories. This @@ -602,7 +607,7 @@ remote copies of rsync. Typically, rsync is configured to use ssh by default, but you may prefer to use rsh on a local network. If this option is used with bf([user@]host::module/path), then the -remote shell em(COMMMAND) will be used to run an rsync server on the +remote shell em(COMMAND) will be used to run an rsync server on the remote host, and all data will be transmitted through that remote shell connection, rather than through a direct socket connection to a running rsync server on the remote host. See the section "CONNECTING @@ -748,19 +753,20 @@ compressing transport, as it takes advantage of the implicit information sent for matching data blocks. 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 +and user IDs rather than using user and group names and mapping them at both ends. -By default rsync will use the user name and group name to determine +By default rsync will use the username and groupname to determine 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 a user or group has no name on the source system or it has no match +on the destination system, then the numeric ID +from the source system is used instead. See also the comments on the +"use chroot" setting in the rsyncd.conf manpage. -dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO +dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O timeout in seconds. If no data is transferred for the specified time then rsync will exit. The default is 0, which means no timeout. @@ -799,11 +805,11 @@ the default is rsyncd.conf in the current directory (typically $HOME). dit(bf(--port=PORT)) This specifies an alternate TCP port number to use rather than the default port 873. -dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching +dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching a remote shell transport. If the remote shell is either rsh or remsh, rsync defaults to using -blocking IO, otherwise it defaults to using non-blocking IO. (Note that -ssh prefers non-blocking IO.) +blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that +ssh prefers non-blocking I/O.) dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the default. @@ -828,6 +834,29 @@ showing the progress of the transfer. This gives a bored user something to watch. Implies --verbose without incrementing verbosity. +When the file is transferring, the data looks like this: + +verb( + 782448 63% 110.64kB/s 0:00:04 +) + +This tells you the current file size, the percentage of the transfer that +is complete, the current calculated file-completion rate (including both +data over the wire and data being matched locally), and the estimated time +remaining in this transfer. + +After the a file is complete, it the data looks like this: + +verb( + 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396) +) + +This tells you the final file size, that it's 100% complete, the final +transfer rate for the file, the amount of elapsed time it took to transfer +the file, and the addition of a total-transfer summary in parentheses. +These additional numbers tell you how many files have been updated, and +what percent of the total number of files has been scanned. + dit(bf(-P)) The -P option is equivalent to --partial --progress. I found myself typing that combination quite often so I created an option to make it easier. @@ -844,7 +873,7 @@ transfer rate in kilobytes per second. This option is most effective when using rsync with large files (several megabytes and up). Due to the nature of rsync transfers, blocks of data are sent, then if rsync determines the 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 +result is an average transfer rate equaling the specified limit. A value of zero specifies no limit. dit(bf(--write-batch=PREFIX)) Generate a set of files that can be @@ -1062,7 +1091,7 @@ 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. +unsafe links to be omitted altogether. Symbolic links are considered unsafe if they are absolute symlinks (start with bf(/)), empty, or if they contain enough bf("..") @@ -1104,11 +1133,11 @@ dit(bf(2)) Protocol incompatibility dit(bf(3)) Errors selecting input/output files, dirs dit(bf(4)) Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that cannot support -them; or an option was speciifed that is supported by the client and +them; or an option was specifed that is supported by the client and not by the server. dit(bf(5)) Error starting client-server protocol -dit(bf(10)) Error in socket IO -dit(bf(11)) Error in file IO +dit(bf(10)) Error in socket I/O +dit(bf(11)) Error in file I/O dit(bf(12)) Error in rsync protocol data stream dit(bf(13)) Errors with program diagnostics dit(bf(14)) Error in IPC code @@ -1163,11 +1192,11 @@ manpagebugs() times are transferred as unix time_t values -When transferring to FAT filesystmes rsync may resync +When transferring to FAT filesystems rsync may resync unmodified files. See the comments on the --modify-window option. -file permissions, devices etc are transferred as native numerical +file permissions, devices, etc. are transferred as native numerical values see also the comments on the --delete option