X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/3610c4583a6b187fa6fc98ad0025340c6f840d53..22f5bd5e35a0b148a8f9b0c0bb9d18827e6996b7:/rsync.yo diff --git a/rsync.yo b/rsync.yo index fb48e2e0..a8a5d480 100644 --- a/rsync.yo +++ b/rsync.yo @@ -356,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 @@ -367,11 +368,6 @@ 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 --blocking-io use blocking I/O for the remote shell --no-blocking-io turn off --blocking-io --stats give some file transfer stats @@ -385,8 +381,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 specify alternate rsyncd port number + -4 --ipv4 prefer IPv4 + -6 --ipv6 prefer IPv6 + -h, --help show this help screen ) manpageoptions() @@ -399,9 +407,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 @@ -527,7 +535,7 @@ 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, and +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 these restrictions). @@ -801,31 +809,38 @@ 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 +dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(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. +destination directory. Files that are identical to one of the specified +directories are not transferred. This is useful for creating a sparse +backup into a new hierarchy. 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 ownership and permissions--if those items +are being preserved--in order for the files to be linked together. If +em(DIR) is a relative path, it is relative to the destination directory. 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. +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. 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 @@ -861,41 +876,6 @@ 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. - 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 @@ -921,7 +901,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 @@ -932,7 +912,7 @@ 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). @@ -1019,11 +999,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 @@ -1037,6 +1013,63 @@ 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. + +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 to use +rather than the default port 873. + +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