mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(19 Feb 2006)()()
+manpage(rsync)(1)(22 Apr 2006)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
daemon already running (or it needs to have configured something like inetd
to spawn an rsync daemon for incoming connections on a particular port).
For full information on how to start a daemon that will handling incoming
-socket connections, see the rsyncd.conf(5) man page -- that is the config
+socket connections, see the bf(rsyncd.conf)(5) man page -- that is the config
file for the daemon, and it contains the full details for how to run the
daemon (including stand-alone and inetd configurations).
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
--rsync-path=PROGRAM specify the rsync to run on remote machine
- --existing ignore non-existing files on receiving side
- --ignore-existing ignore files that already exist on receiver
- --remove-sent-files sent files/symlinks are removed from sender
+ --existing skip creating new files on receiver
+ --ignore-existing skip updating files that exist on receiver
+ --remove-sent-files sender removes successfully sent files
--del an alias for --delete-during
- --delete delete files that don't exist on sender
+ --delete delete extraneous files from dest dirs
--delete-before receiver deletes before transfer (default)
--delete-during receiver deletes during xfer, not before
--delete-after receiver deletes after transfer, not before
- --delete-excluded also delete excluded files on receiver
+ --delete-excluded also delete excluded files from dest dirs
--ignore-errors delete even if there are I/O errors
--force force deletion of dirs even if not empty
--max-delete=NUM don't delete more than NUM files
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
- --log-format=FORMAT output filenames using the specified format
+ --out-format=FORMAT output updates using the specified FORMAT
+ --log-file=FILE log what we're doing to the specified FILE
+ --log-file-format=FMT log updates using the specified FMT
--password-file=FILE read password from FILE
--list-only list the files instead of copying them
--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
+ --log-file=FILE override the "log file" setting
+ --log-file-format=FMT override the "log format" setting
--sockopts=OPTIONS specify custom TCP options
-v, --verbose increase verbosity
-4, --ipv4 prefer IPv4
you are debugging rsync.
Note that the names of the transferred files that are output are done using
-a default bf(--log-format) of "%n%L", which tells you just the name of the
+a default bf(--out-format) of "%n%L", which tells you just the name of the
file and, if the item is a link, where it points. At the single bf(-v)
level of verbosity, this does not mention when a file gets its attributes
changed. If you ask for an itemized list of changed attributes (either
-bf(--itemize-changes) or adding "%i" to the bf(--log-format) setting), the
+bf(--itemize-changes) or adding "%i" to the bf(--out-format) setting), the
output (on the client) increases to mention all items that are changed in
-any way. See the bf(--log-format) option for more details.
+any way. See the bf(--out-format) option for more details.
dit(bf(-q, --quiet)) This option decreases the amount of information you
are given during the transfer, notably suppressing information messages
"path/foo/file", which might fail if the duplicated symlink did not point
to a directory on the receiving side. Another way to avoid this sending of
a symlink as an implied directory is to use bf(--copy-unsafe-links), or
-bf(--copy-dirlinks) (which will also affect symlinks to directories in the
-rest of the transfer).
+bf(--copy-dirlinks) (both of which also affect symlinks in the rest of the
+transfer -- see their descriptions for full details).
dit(bf(-b, --backup)) With this option, preexisting destination files are
renamed as each file is transferred or deleted. You can control where the
permission value can be applied to the files in the transfer.
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
-destination file to be the same as the source file. By default, the
-preservation is done by name, but may fall back to using the ID number
-in some circumstances (see the bf(--numeric-ids) option for a full
-discussion).
-This option has no effect if the receiving rsync is not run as the
-super-user and bf(--super) is not specified.
+destination file to be the same as the source file, but only if the
+receiving rsync is being run as the super-user (see also the bf(--super)
+option to force rsync to attempt super-user activities).
+Without this option, the owner is set to the invoking user on the
+receiving side.
+
+The preservation of ownership will associate matching names by default, but
+may fall back to using the ID number in some circumstances (see also the
+bf(--numeric-ids) option for a full discussion).
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 (or with the bf(--no-super)
-option), only groups that the
-receiver is a member of will be preserved. By default, the preservation
-is done by name, but may fall back to using the ID number in some
-circumstances. See the bf(--numeric-ids) option for a full discussion.
+program is not running as the super-user (or if bf(--no-super) was
+specified), only groups that the invoking user on the receiving side
+is a member of will be preserved.
+Without this option, the group is set to the default group of the invoking
+user on the receiving side.
+
+The preservation of group information will associate matching names by
+default, but may fall back to using the ID number in some circumstances
+(see also the bf(--numeric-ids) option for a full discussion).
dit(bf(--devices)) This option causes rsync to transfer character and
block device files to the remote system to recreate these devices.
by this option.
dit(bf(--existing, --ignore-non-existing)) This tells rsync to skip
-updating files that do not exist yet on the destination. If this option is
+creating files (including directories) that do not exist
+yet on the destination. If this option is
combined with the bf(--ignore-existing) option, no files will be updated
-(which can be useful if all you want to do is to delete missing files).
+(which can be useful if all you want to do is to delete extraneous files).
dit(bf(--ignore-existing)) This tells rsync to skip updating files that
-already exist on the destination. See also bf(--ignore-non-existing).
+already exist on the destination (this does em(not) ignore existing
+directores, or nothing would get done). See also bf(--existing).
dit(bf(--remove-sent-files)) This tells rsync to remove from the sending
side the files and/or symlinks that are newly created or whose content is
Finally, any file is ignored if it is in the same directory as a
.cvsignore file and matches one of the patterns listed therein. Unlike
rsync's filter/exclude files, these patterns are split on whitespace.
-See the bf(cvs(1)) manual for more information.
+See the bf(cvs)(1) manual for more information.
If you're combining bf(-C) with your own bf(--filter) rules, you should
note that these CVS excludes are appended at the end of your own rules,
dit(bf(--sockopts)) This option can provide endless fun for people
who like to tune their systems to the utmost degree. You can set all
sorts of socket options which may make transfers faster (or
-slower!). Read the man page for the setsockopt() system call for
+slower!). Read the man page for the code(setsockopt()) system call for
details on some of the options you may be able to set. By default no
special socket options are set. This only affects direct socket
connections to a remote rsync daemon. This option also exists in the
dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
changes that are being made to each file, including attribute changes.
-This is exactly the same as specifying bf(--log-format='%i %n%L').
+This is exactly the same as specifying bf(--out-format='%i %n%L').
If you repeat the option, unchanged files will also be output, but only
if the receiving rsync is at least version 2.6.7 (you can use bf(-vv)
with older versions of rsync, but that also turns on the output of other
you are talking to a recent enough rsync that it logs deletions instead of
outputting them as a verbose message).
-dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
-rsync client outputs to the user on a per-file basis. The format is a text
+dit(bf(--out-format=FORMAT)) This allows you to specify exactly what the
+rsync client outputs to the user on a per-update basis. The format is a text
string containing embedded single-character escape sequences prefixed with
a percent (%) character. For a list of the possible escape characters, see
-the "log format" setting in the rsyncd.conf manpage. (Note that this
-option does not affect what a daemon logs to its logfile.)
+the "log format" setting in the rsyncd.conf manpage.
Specifying this option will mention each file, dir, etc. that gets updated
in a significant way (a transferred file, a recreated symlink/device, or a
-touched directory) unless the itemize-changes escape (%i) is included in
-the string, in which case the logging of names increases to mention any
+touched directory). In addition, if the itemize-changes escape (%i) is
+included in the string, the logging of names increases to mention any
item that is changed in any way (as long as the receiving side is at least
2.6.4). See the bf(--itemize-changes) option for a description of the
output of "%i".
The bf(--verbose) option implies a format of "%n%L", but you can use
-bf(--log-format) without bf(--verbose) if you like, or you can override
+bf(--out-format) without bf(--verbose) if you like, or you can override
the format of its per-file output using this option.
-Rsync will output the log-format string prior to a file's transfer unless
+Rsync will output the out-format string prior to a file's transfer unless
one of the transfer-statistic escapes is requested, in which case the
logging is done at the end of the file's transfer. When this late logging
is in effect and bf(--progress) is also specified, rsync will also output
the name of the file being transferred prior to its progress information
-(followed, of course, by the log-format output).
+(followed, of course, by the out-format output).
+
+dit(bf(--log-file=FILE)) This option causes rsync to log what it is doing
+to a file. This is similar to the logging that a daemon does, but can be
+requested for the client side and/or the server side of a non-daemon
+transfer. If specified as a client option, transfer logging will be
+enabled with a default format of "%i %n%L". See the bf(--log-file-format)
+option if you wish to override this.
+
+Here's a example command that requests the remote side to log what is
+happening:
+
+verb( rsync -av --rsync-path="rsync --log-file=/tmp/rlog" src/ dest/)
+
+This is very useful if you need to debug why a connection is closing
+unexpectedly.
+
+dit(bf(--log-file-format=FORMAT)) This allows you to specify exactly what
+per-update logging is put into the file specified by the bf(--log-file) option
+(which must also be specified for this option to have any effect). If you
+specify an empty string, updated files will not be mentioned in the log file.
+For a list of the possible escape characters, see the "log format" setting
+in the rsyncd.conf manpage.
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
on the file transfer, allowing you to tell how effective the rsync
algorithm is for your data.
-The current statistics are as follows: itemize(
+The current statistics are as follows: quote(itemize(
it() bf(Number of files) is the count of all "files" (in the generic
sense), which includes directories, symlinks, etc.
it() bf(Number of files transferred) is the count of normal files that
rsync received by the client side from the server side. "Non-message"
bytes means that we don't count the bytes for a verbose message that the
server sent to us, which makes the stats more consistent.
-)
+))
dit(bf(-8, --8-bit-output)) This tells rsync to leave all high-bit characters
unescaped in the output instead of trying to test them to see if they're
single line.
dit(bf(--list-only)) This option will cause the source files to be listed
-instead of transferred. This option is inferred if there is no destination
-specified, so its main uses are: (1) to turn a copy command that includes a
+instead of transferred. This option is inferred if there is a single source
+arg and no destination specified, so its main uses are: (1) to turn a copy
+command that includes a
destination arg into a file-listing command, (2) to be able to specify more
than one local source arg (note: be sure to include the destination), or
(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that
rsync usually uses as a compatibility kluge when generating a non-recursive
-listing.
+listing. Caution: keep in mind that a source arg with a wild-card is expanded
+by the shell into multiple args, so it is never safe to try to list such an arg
+without using this option. For example:
+
+verb( rsync -av --list-only foo* dest/)
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second. This option is most effective when
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
MD4 checksum calculation. By default the checksum seed is generated
-by the server and defaults to the current time(). This option
+by the server and defaults to the current code(time()). This option
is used to set a specific checksum seed, which is useful for
applications that want repeatable block and file checksums, or
in the case where the user wants a more random checksum seed.
-Note that setting NUM to 0 causes rsync to use the default of time()
+Note that setting NUM to 0 causes rsync to use the default of code(time())
for checksum seed.
enddit()
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
+requests accordingly. See the bf(rsyncd.conf)(5) man page for more
details.
dit(bf(--address)) By default rsync will bind to the wildcard address when
daemon to listen on rather than the default of 873. See also the "port"
global option in the rsyncd.conf manpage.
+dit(bf(--log-file=FILE)) This option tells the rsync daemon to use the
+given log-file name instead of using the "log file" setting in the config
+file.
+
+dit(bf(--log-file-format=FORMAT)) This option tells the rsync daemon to use the
+given FORMAT string instead of using the "log format" setting in the config
+file. It also enables "transfer logging" unless the string is empty, in which
+case transfer logging is turned off.
+
dit(bf(--sockopts)) This overrides the bf(socket options) setting in the
rsyncd.conf file and has the same syntax.
of the transfer.
it() if the pattern ends with a / then it will only match a
directory, not a file, link, or device.
-
it() rsync chooses between doing a simple string match and wildcard
matching by checking if the pattern contains one of these three wildcard
characters: '*', '?', and '[' .
option is used. This file's name is created by appending
".sh" to the batch filename. The .sh file contains
a command-line suitable for updating a destination tree using that
-batch file. It can be executed using a Bourne(-like) shell, optionally
+batch file. It can be executed using a Bourne (or 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.
dit(bf(13)) Errors with program diagnostics
dit(bf(14)) Error in IPC code
dit(bf(20)) Received SIGUSR1 or SIGINT
-dit(bf(21)) Some error returned by waitpid()
+dit(bf(21)) Some error returned by code(waitpid())
dit(bf(22)) Error allocating core memory buffers
dit(bf(23)) Partial transfer due to error
dit(bf(24)) Partial transfer due to vanished source files
manpageseealso()
-rsyncd.conf(5)
+bf(rsyncd.conf)(5)
manpagebugs()
manpagesection(VERSION)
-This man page is current for version 2.6.7pre2 of rsync.
+This man page is current for version 2.6.8 of rsync.
manpagesection(CREDITS)