X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/b4d1e854ef72a2ff56e97be9aabc3e9880f3c0d7..4ce838e1f107239f1b18f3f8cd7c7fbab65e0bd5:/rsync.yo diff --git a/rsync.yo b/rsync.yo index bd5c1019..589545ac 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(12 Aug 2004)()() +manpage(rsync)(1)(30 Sep 2004)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -345,6 +345,7 @@ verb( --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 + --max-size=SIZE don't transfer any file larger than SIZE --partial keep partially transferred files --partial-dir=DIR put a partially transferred file into DIR --force force deletion of dirs even if not empty @@ -355,7 +356,8 @@ verb( --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 + --copy-dest=DIR ... and include copies of unchanged files + --link-dest=DIR hardlink to files in DIR when unchanged -P equivalent to --partial --progress -z, --compress compress file data -C, --cvs-exclude auto ignore files in the same way CVS does @@ -366,11 +368,7 @@ verb( --files-from=FILE read FILE for list of source-file names -0 --from0 all file lists are delimited by nulls --version print version number - --daemon run as an rsync daemon - --no-detach do not detach from the parent - --address=ADDRESS bind to the specified address - --config=FILE specify alternate rsyncd.conf file - --port=PORT specify alternate rsyncd port number + --port=PORT specify double-colon alternate port number --blocking-io use blocking I/O for the remote shell --no-blocking-io turn off --blocking-io --stats give some file transfer stats @@ -384,8 +382,20 @@ verb( -4 --ipv4 prefer IPv4 -6 --ipv6 prefer IPv6 -h, --help show this help screen +) +Rsync can also be run as a daemon, in which case the following options are accepted: +verb( + --daemon run as an rsync daemon + --address=ADDRESS bind to the specified address + --bwlimit=KBPS limit I/O bandwidth, KBytes per second + --config=FILE specify alternate rsyncd.conf file + --no-detach do not detach from the parent + --port=PORT listen on alternate port number + -4 --ipv4 prefer IPv4 + -6 --ipv6 prefer IPv6 + -h, --help show this help screen ) manpageoptions() @@ -398,9 +408,9 @@ can be used instead. startdit() dit(bf(-h, --help)) Print a short help page describing the options -available in rsync +available in rsync. -dit(bf(--version)) print the rsync version number and exit +dit(bf(--version)) print the rsync version number and exit. dit(bf(-v, --verbose)) This option increases the amount of information you are given during the transfer. By default, rsync works silently. A @@ -457,15 +467,21 @@ just the last parts of the filenames. This is particularly useful when you want to send several different directories at the same time. For example, if you used the command -verb(rsync foo/bar/foo.c remote:/tmp/) +verb(rsync /foo/bar/foo.c remote:/tmp/) then this would create a file called foo.c in /tmp/ on the remote machine. If instead you used -verb(rsync -R foo/bar/foo.c remote:/tmp/) +verb(rsync -R /foo/bar/foo.c remote:/tmp/) then a file called /tmp/foo/bar/foo.c would be created on the remote -machine -- the full path name is preserved. +machine -- the full path name is preserved. To limit the amount of +path information that is sent, do something like this: + +verb(cd /foo +rsync -R bar/foo.c remote:/tmp/) + +That would create /tmp/bar/foo.c on the remote machine. dit(bf(--no-relative)) Turn off the --relative option. This is only needed if you want to use --files-from without its implied --relative @@ -500,11 +516,13 @@ dit(bf(--suffix=SUFFIX)) This option allows you to override the default backup suffix used with the --backup (-b) option. The default suffix is a ~ if no --backup-dir was specified, otherwise it is an empty string. -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(-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 +source file's, it will be updated if the sizes are different.) -In the currently implementation, a difference of file format is always +In the current implementation of --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 @@ -518,10 +536,17 @@ from the sender. 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 file, meaning that the rsync algorithm can't extract the full amount of -network reduction it might otherwise. +network reduction it might otherwise (since it does not yet try to sort +data matches -- a future version may improve this). + +This option is useful for transfer of large files with block-based changes +or appended data, and also on systems that are disk bound, not network +bound. -This option is useful for transfer of large files with block-based change -or appended data, and also on systems that are disk bound not network bound. +The option implies --partial (since an interrupted transfer does not delete +the file), but conflicts with --partial-dir, --compare-dest, --copy-dest, and +--link-dest (a future rsync version will hopefully update the protocol to +remove some of these restrictions). WARNING: The file's data will be in an inconsistent state during the transfer (and possibly afterward if the transfer gets interrupted), so you @@ -628,17 +653,27 @@ 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. -dit(bf(--delete)) This tells rsync to delete any files on the receiving -side that aren't on the sending side. Files that are excluded from -transfer are excluded from being deleted unless you use --delete-excluded. +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 +suffixed with a letter to indicate a size multiplier (K, M, or G) and +may be a fractional value (e.g. "--max-size=1.5m"). + +dit(bf(--delete)) This tells rsync to delete extraneous files from the +receiving side (ones that aren't on the sending side), but only for the +directories that are being synchronized. You must have asked rsync to +send the whole directory (e.g. "dir" or "dir/") without using a wildcard +for the directory's contents (e.g. "dir/*") since the wildcard is expanded +by the shell and rsync thus gets a request to transfer those files, not +the files' parent directory. Files that are excluded from transfer are +excluded from being deleted unless you use --delete-excluded. This option has no effect if directory recursion is not selected. 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 +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 I/O 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 @@ -654,6 +689,10 @@ 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. +One reason to use --delete-after is to avoid a delay before the start of +the transfer (while the receiving side is scanned for deletions) as this +delay might cause the transfer to timeout. + dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files even when there are I/O errors. @@ -788,31 +827,50 @@ scratch directory when creating temporary copies of the files transferred on the receiving side. The default behavior is to create the temporary files in the receiving directory. -dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on -the destination machine as an additional directory to compare destination -files against when doing transfers if the files are missing in the -destination directory. This is useful for doing transfers to a new -destination while leaving existing files intact, and then doing a -flash-cutover when all files have been successfully transferred (for -example by moving directories around and removing the old directory, -although this skips files that haven't changed; see also --link-dest). -This option increases the usefulness of --partial because partially -transferred files will remain in the new temporary destination until they -have a chance to be completed. If DIR is a relative path, it is relative -to the destination directory. - -dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but -also will create hard links from em(DIR) to the destination directory for -unchanged files. Files with changed ownership or permissions will not be -linked. +dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on +the destination machine as an additional hierarchy to compare destination +files against doing transfers (if the files are missing in the destination +directory). If a file is found in em(DIR) that is identical to the +sender's file, the file will NOT be transferred to the destination +directory. This is useful for creating a sparse backup of just files that +have changed from an earlier backup. + +Beginning in version 2.6.4, multiple --compare-dest directories may be +provided and rsync will search the list in the order specified until it +finds an existing file. That first discovery is used as the basis file, +and also determines if the transfer needs to happen. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also --copy-dest and --link-dest. + +dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but +rsync will also copy unchanged files found in em(DIR) to the destination +directory (using the data in the em(DIR) for an efficient copy). This is +useful for doing transfers to a new destination while leaving existing +files intact, and then doing a flash-cutover when all files have been +successfully transferred. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also --compare-dest and --link-dest. + +dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but +unchanged files are hard linked from em(DIR) to the destination directory. +The files must be identical in all preserved attributes (e.g. permissions, +possibly ownership) in order for the files to be linked together. An example: verb( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/ ) -Like bf(--compare-dest) if DIR is a relative path, it is relative to the -destination directory. +Beginning with version 2.6.4, if more than one --link-dest option is +specified, rsync will try to find an exact match to link with (searching +the list in the order specified), and if not found, a basis file from one +of the em(DIR)s will be selected to try to speed up the transfer. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also --compare-dest and --copy-dest. + Note that rsync versions prior to 2.6.1 had a bug that could prevent --link-dest from working properly for a non-root user when -o was specified (or implied by -a). If the receiving rsync is not new enough, you can work @@ -848,40 +906,11 @@ 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. -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 -(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 -option is required when running as a service on Cygwin, and may also -be useful when rsync is supervised by a program such as -bf(daemontools) or AIX's bf(System Resource Controller). -bf(--no-detach) is also recommended when rsync is run under a -debugger. This option has no effect if rsync is run from inetd or -sshd. - -dit(bf(--address)) By default rsync will bind to the wildcard address -when run as a daemon with the --daemon option or when connecting to a -rsync server. The --address option allows you to specify a specific IP -address (or hostname) to bind to. This makes virtual hosting possible -in conjunction with the --config option. - -dit(bf(--config=FILE)) This specifies an alternate config file than -the default. This is only relevant when --daemon is specified. -The default is /etc/rsyncd.conf unless the daemon is running over -a remote shell program and the remote user is not root; in that case -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. +rather than the default of 873. This is only needed if you are using the +double-colon (::) syntax to connect with an rsync daemon (since the URL +syntax has a way to specify the port as a part of the URL). See also this +option in the --daemon mode section. 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, @@ -908,7 +937,7 @@ it is more desirable to keep partially transferred files. Using the make a subsequent transfer of the rest of the file much faster. dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to -put a partially transferred file into DIR instead of writing out the +put a partially transferred file into em(DIR) instead of writing out the file to the destination dir. Rsync will also use a file found in this dir as data to speed up the transfer (i.e. when you redo the send after rsync creates a partial file) and delete such a file after it has served @@ -919,15 +948,20 @@ rsync is sending files without using the incremental rsync algorithm). Rsync will create the dir if it is missing (just the last dir -- not the whole path). This makes it easy to use a relative path (such as "--partial-dir=.rsync-partial") to have rsync create the partial-directory -in the destination file's directory (rsync will also try to remove the DIR +in the destination file's directory (rsync will also try to remove the em(DIR) if a partial file was found to exist at the start of the transfer and the DIR was specified as a relative path). -If you are deleting files on the destination and your partial-dir is -inside the destination hierarchy, make sure you specify an exclude to -prevent the partial file from being deleted (it could get deleted at the -end of the transfer when using --delete-after, or at the beginning of the -transfer when using --delete). E.g. "--exclude=.rsync-partial/". +If the partial-dir value is not an absolute path, rsync will also add an +--exclude of this value at the end of all your existing excludes. This +will prevent partial-dir files from being transferred and also prevent the +untimely deletion of partial-dir items on the receiving side. An example: +the above --partial-dir option would add an "--exclude=.rsync-partial/" +rule at the end of any other include/exclude rules. Note that if you are +supplying your own include/exclude rules, you may need to manually insert a +rule for this directory exclusion somewhere higher up in the list so that +it has a high enough priority to be effective (e.g., if your rules specify +a trailing --exclude=* rule, the auto-added rule will be ineffective). IMPORTANT: the --partial-dir should not be writable by other users or it is a security risk. E.g. AVOID "/tmp". @@ -958,7 +992,7 @@ 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: +After a file is complete, the data looks like this: verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396) @@ -970,9 +1004,9 @@ 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. +dit(bf(-P)) The -P option is equivalent to --partial --progress. Its +purpose is to make it much easier to specify these two options for a long +transfer that may be interrupted. dit(bf(--password-file)) This option allows you to provide a password in a file for accessing a remote rsync server. Note that this option @@ -1001,11 +1035,7 @@ See the "BATCH MODE" section for details. 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, or the incoming sockets that an rsync daemon uses to -listen for connections. One of these options may be required in older -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 --ipv6 or --ipv4 when starting the daemon). +rsync daemon. See also these options in the --daemon mode section. 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 @@ -1019,6 +1049,65 @@ for checksum seed. enddit() +The options allowed when starting an rsync daemon are as follows: + +startdit() + +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 +(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(--address)) By default rsync will bind to the wildcard address +when run as a daemon with the --daemon option or when connecting to a +rsync server. The --address option allows you to specify a specific IP +address (or hostname) to bind to. This makes virtual hosting possible +in conjunction with the --config option. See also the "address" global +option in the rsyncd.conf manpage. + +dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum +transfer rate in kilobytes per second for the data the daemon sends. +The client can still specify a smaller --bwlimit value, but their +requested value will be rounded down if they try to exceed it. See the +client version of this option (above) for some extra details. + +dit(bf(--config=FILE)) This specifies an alternate config file than +the default. This is only relevant when --daemon is specified. +The default is /etc/rsyncd.conf unless the daemon is running over +a remote shell program and the remote user is not root; in that case +the default is rsyncd.conf in the current directory (typically $HOME). + +dit(bf(--no-detach)) When running as a daemon, this option instructs +rsync to not detach itself and become a background process. This +option is required when running as a service on Cygwin, and may also +be useful when rsync is supervised by a program such as +bf(daemontools) or AIX's bf(System Resource Controller). +bf(--no-detach) is also recommended when rsync is run under a +debugger. This option has no effect if rsync is run from inetd or +sshd. + +dit(bf(--port=PORT)) This specifies an alternate TCP port number for the +daemon to listen on rather than the default of 873. See also the "port" +global option in the rsyncd.conf manpage. + +dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6 +when creating the incoming sockets that the rsync daemon will use to +listen for connections. One of these options may be required in older +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 --ipv6 or --ipv4 when starting the daemon). + +dit(bf(-h, --help)) When specified after --daemon, print a short help +page describing the options available for starting an rsync daemon. + +enddit() + manpagesection(EXCLUDE PATTERNS) The exclude and include patterns specified to rsync allow for flexible