Allow --port to be used in client mode (as well as daemon mode).

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 1a70c62..6a0f6c1 100644 (file)
--- 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
      --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
  -P                          equivalent to --partial --progress
  -z, --compress              compress file data
  -C, --cvs-exclude           auto ignore files in the same way CVS does


@@ -387,6 +388,7 @@ Rsync can also be run as a daemon, in which case the following options are accep
 verb(
      --daemon                run as an rsync daemon
      --address=ADDRESS       bind to the specified address
 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
      --config=FILE           specify alternate rsyncd.conf file
      --no-detach             do not detach from the parent
      --port=PORT             specify alternate rsyncd port number


@@ -464,15 +466,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
 
 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
 
 
 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
 
 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
 
 dit(bf(--no-relative)) Turn off the --relative option.  This is only
 needed if you want to use --files-from without its implied --relative


@@ -507,11 +515,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.
 
 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
 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


@@ -533,9 +543,9 @@ 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
 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
 --link-dest (a future rsync version will hopefully update the protocol to

-remove these restrictions).
+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
 
 WARNING: The file's data will be in an inconsistent state during the
 transfer (and possibly afterward if the transfer gets interrupted), so you


@@ -807,31 +817,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.
 
 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/
 )
 
 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
 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


@@ -892,7 +921,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
 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
 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


@@ -903,7 +932,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
 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 a partial file was found to exist at the start of the transfer and the
 DIR was specified as a relative path).
 


@@ -947,7 +976,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.
 
 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)
 
 verb(
      1238099 100%  146.38kB/s    0:00:08  (5, 57.1% of 396)


@@ -1023,7 +1052,14 @@ 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
 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.
+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. 
 
 dit(bf(--config=FILE)) This specifies an alternate config file than
 the default.  This is only relevant when --daemon is specified. 


@@ -1041,7 +1077,8 @@ 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
 sshd.
 
 dit(bf(--port=PORT)) This specifies an alternate TCP port number to use

-rather than the default port 873.
+rather than the default port 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
 
 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