mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Sep 2004)()()
+manpage(rsync)(1)(1 Jun 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
-rsync [OPTION]... [USER@]HOST:SRC DEST
+rsync [OPTION]... [USER@]HOST:SRC [DEST]
rsync [OPTION]... SRC [SRC]... DEST
it() can use any transparent remote shell, including ssh or rsh
it() does not require root privileges
it() pipelining of file transfers to minimize latency costs
- it() support for anonymous or authenticated rsync servers (ideal for
+ it() support for anonymous or authenticated rsync daemons (ideal for
mirroring)
)
manpagesection(GENERAL)
-There are eight different ways of using rsync. They are:
-
-itemize(
- it() for copying local files. This is invoked when neither
- source nor destination path contains a : separator
- it() for copying from the local machine to a remote machine using
- a remote shell program as the transport (such as ssh or
- rsh). This is invoked when the destination path contains a
- single : separator.
- it() for copying from a remote machine to the local machine
- using a remote shell program. This is invoked when the source
- contains a : separator.
- it() for copying from a remote rsync server to the local
- machine. This is invoked when the source path contains a ::
- separator or an rsync:// URL.
- it() for copying from the local machine to a remote rsync
- server. This is invoked when the destination path contains a ::
- separator or an rsync:// URL.
- it() for copying from a remote machine using a remote shell
- program as the transport, using rsync server on the remote
- machine. This is invoked when the source path contains a ::
- separator and the bf(--rsh=COMMAND) (aka "bf(-e COMMAND)") option is
- also provided.
- it() for copying from the local machine to a remote machine
- 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
- bf(--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
- local destination.
-)
-
-Note that in all cases (other than listing) at least one of the source
-and destination paths must be local.
+Rsync copies files either to or from a remote host, or locally on the
+current host (it does not support copying files between two remote hosts).
+
+There are two different ways for rsync to contact a remote system: using a
+remote-shell program as the transport (such as ssh or rsh) or contacting an
+rsync daemon directly via TCP. The remote-shell transport is used whenever
+the source or destination path contains a single colon (:) separator after
+a host specification. Contacting an rsync daemon directly happens when the
+source or destination path contains a double colon (::) separator after a
+host specification, OR when an rsync:// URL is specified.
+
+As a special case, if a remote source is specified without a destination,
+the remote files are listed in an output format similar to "ls -l".
+
+As expected, if neither the source or destination path specify a remote
+host, the copy occurs locally (see also the bf(--list-only) option).
+
+Finally, it is possible to use a remote-shell transport to contact a remote
+host and then to spawn a single-use rsync daemon. This allows the use of
+some of the daemon features (such as named modules) without having to run a
+daemon as a service. To achieve this, invoke rsync with an explicit
+bf(--rsh=COMMAND) (aka "bf(-e COMMAND)") option combined with either the
+source or destination path specified as an rsync daemon (i.e. either a ::
+separator or an rsync:// URL). In this case, rsync contacts the remote
+host specified using the specified remote shell, and then starts a
+single-use rsync daemon to deal with that copy request. See the section
+"CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM" below.
manpagesection(SETUP)
tt(rsync -av /src/foo/ /dest/foo)nl()
)
+Note also that host and module references don't require a trailing slash to
+copy the contents of the default directory. For example, both of these
+copy the remote directory's contents into "/dest":
+
+quote(
+tt(rsync -av host: /dest)nl()
+tt(rsync -av host::module /dest)nl()
+)
+
You can also use rsync in local-only mode, where both the source and
destination don't have a ':' in the name. In this case it behaves like
an improved copy command.
This latter example assumes that your shell passes through unmatched
wildcards. If it complains about "no match", put the name in quotes.
-manpagesection(CONNECTING TO AN RSYNC SERVER)
+manpagesection(CONNECTING TO AN RSYNC DAEMON)
It is also possible to use rsync without a remote shell as the
-transport. In this case you will connect to a remote rsync server
+transport. In this case you will connect to a remote rsync daemon
running on TCP port 873.
You may establish the connection via a web proxy by setting the
that:
itemize(
- it() you use a double colon :: instead of a single colon to
- separate the hostname from the path or an rsync:// URL.
- it() the remote server may print a message of the day when you
+ it() you either use a double colon :: instead of a single colon to
+ separate the hostname from the path, or you use an rsync:// URL.
+ it() the remote daemon may print a message of the day when you
connect.
- it() if you specify no path name on the remote server then the
- list of accessible paths on the server will be shown.
+ it() if you specify no path name on the remote daemon then the
+ list of accessible paths on the daemon will be shown.
it() if you specify no local destination then a listing of the
- specified files on the remote server is provided.
+ specified files on the remote daemon is provided.
)
-Some paths on the remote server may require authentication. If so then
+Some paths on the remote daemon may require authentication. If so then
you will receive a password prompt when you connect. You can avoid the
password prompt by setting the environment variable RSYNC_PASSWORD to
the password you want to use or using the bf(--password-file) option. This
WARNING: On some systems environment variables are visible to all
users. On those systems using bf(--password-file) is recommended.
-manpagesection(CONNECTING TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+manpagesection(CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM)
It is sometimes useful to be able to set up file transfers using rsync
-server capabilities on the remote machine, while still using ssh or
+daemon capabilities on the remote machine, while still using ssh or
rsh for transport. This is especially useful when you want to connect
to a remote machine via ssh (for encryption or to get through a
-firewall), but you still want to have access to the rsync server
-features (see RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM,
+firewall), but you still want to have access to the rsync daemon
+features (see RUNNING AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM,
below).
From the user's perspective, using rsync in this way is the same as
-using it to connect to an rsync server, except that you must
+using it to connect to an rsync daemon, except that you must
explicitly set the remote shell program on the command line with
bf(--rsh=COMMAND). (Setting RSYNC_RSH in the environment will not turn on
this functionality.)
In order to distinguish between the remote-shell user and the rsync
-server user, you can use '-l user' on your remote-shell command:
+daemon user, you can use '-l user' on your remote-shell command:
verb( rsync -av --rsh="ssh -l ssh-user" \
rsync-user@host::module[/path] local-path)
The "ssh-user" will be used at the ssh level; the "rsync-user" will be
used to check against the rsyncd.conf on the remote host.
-manpagesection(RUNNING AN RSYNC SERVER)
+manpagesection(RUNNING AN RSYNC DAEMON)
-An rsync server is configured using a configuration file. Please see the
+An rsync daemon 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
is rsyncd.conf in the current directory on the remote computer
(typically $HOME).
-manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+manpagesection(RUNNING AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM)
See the rsyncd.conf(5) man page for full information on the rsync
-server configuration file.
+daemon configuration file.
Several configuration options will not be available unless the remote
user is root (e.g. chroot, setuid/setgid, etc.). There is no need to
-configure inetd or the services map to include the rsync server port
-if you run an rsync server only via a remote shell program.
+configure inetd or the services map to include the rsync daemon port
+if you run an rsync daemon only via a remote shell program.
-To run an rsync server out of a single-use ssh key, see this section
+To run an rsync daemon out of a single-use ssh key, see this section
in the rsyncd.conf(5) man page.
manpagesection(EXAMPLES)
to the detailed description below for a complete description. verb(
-v, --verbose increase verbosity
-q, --quiet suppress non-error messages
- -c, --checksum always checksum
-c, --checksum skip based on checksum, not mod-time & size
-a, --archive archive mode; same as -rlptgoD (no -H)
-r, --recursive recurse into directories
-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
- --rsync-path=PATH specify path to rsync on the remote machine
+ --rsync-path=PROGRAM specify the rsync to run on remote machine
--existing only update files that already exist
--ignore-existing ignore files that already exist on receiver
+ --remove-sent-files sent files/symlinks are removed from sender
--del an alias for --delete-during
--delete delete files that don't exist on sender
--delete-before receiver deletes before transfer (default)
--include=PATTERN don't exclude files matching PATTERN
--include-from=FILE read include patterns from FILE
--files-from=FILE read list of source-file names from FILE
- -0, --from0 all *from file lists are delimited by nulls
- --version print version number
+ -0, --from0 all *from/filter files are delimited by 0s
+ --address=ADDRESS bind address for outgoing socket to daemon
--port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
--no-blocking-io turn off blocking I/O when it is default
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
- --log-format=FORMAT log file-transfers using specified format
+ --log-format=FORMAT output filenames using the specified format
--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
--write-batch=FILE write a batched update to FILE
+ --only-write-batch=FILE like --write-batch but w/o updating dest
--read-batch=FILE read a batched update from FILE
+ --protocol=NUM force an older protocol version to be used
--checksum-seed=NUM set block/file checksum seed (advanced)
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
+ --version print version number
-h, --help show this help screen)
Rsync can also be run as a daemon, in which case the following options are
information at the end. More than two bf(-v) flags should only be used if
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
+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
+output (on the client) increases to mention all items that are changed in
+any way. See the bf(--log-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
from the remote server. This flag is useful when invoking rsync from
dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
way of saying you want recursion and want to preserve almost
everything. The only exception to this is if bf(--files-from) was
-specified, in which case bf(-d) is implied instead of bf(-r).
+specified, in which case bf(-r) is not implied.
Note that bf(-a) bf(does not preserve hardlinks), because
finding multiply-linked files is expensive. You must separately
renamed as each file is transferred or deleted. You can control where the
backup file goes and what (if any) suffix gets appended using the
bf(--backup-dir) and bf(--suffix) options.
+Note that if you don't specify bf(--backup-dir), the bf(--omit-dir-times)
+option will be enabled.
dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
tells rsync to store all backups in the specified directory. This is
specify a backup suffix using the bf(--suffix) option
(otherwise the files backed up in the specified directory
will keep their original filenames).
-If DIR is a relative path, it is relative to the destination directory
-(which changes in a recursive transfer).
dit(bf(--suffix=SUFFIX)) This option allows you to override the default
backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~
The option implies bf(--partial) (since an interrupted transfer does not delete
the file), but conflicts with bf(--partial-dir) and bf(--delay-updates).
-Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest),
-bf(--copy-dest), and bf(--link-dest).
+Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest)
+and bf(--link-dest).
WARNING: The file's data will be in an inconsistent state during the
transfer (and possibly afterward if the transfer gets interrupted), so you
dit(bf(-p, --perms)) This option causes rsync to set the destination
permissions to be the same as the source permissions.
-Without this option, each new file gets its permissions set based on the
-source file's permissions and the umask at the receiving end, while all
-other files (including updated files) retain their existing permissions
+Without this option, all existing files (including updated files) retain
+their existing permissions, while each new file gets its permissions set
+based on the source file's permissions, but masked by the receiving end's
+umask setting
(which is the same behavior as other file-copy utilities, such as cp).
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
it is preserving modification times (see bf(--times)). If NFS is sharing
the directories on the receiving side, it is a good idea to use bf(-O).
+This option is inferred if you use bf(--backup) without bf(--backup-dir).
dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
instead it will just report the actions it would have taken.
This tells rsync not to update files that already exist on
the destination.
+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
+updated on the receiving side. Directories and devices are not removed,
+nor are files/symlinks whose attributes are merely changed.
+
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
Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect.
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.
+files or directories (NUM must be non-zero).
+This is useful when mirroring very large trees to prevent disasters.
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
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(COMMAND) will be used to run an rsync server on the
+remote shell em(COMMAND) will be used to run an rsync daemon 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
-TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM" above.
+running rsync daemon on the remote host. See the section "CONNECTING
+TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM" above.
Command-line arguments are permitted in COMMAND provided that COMMAND is
presented to rsync as a single argument. For example:
See also the bf(--blocking-io) option which is affected by this option.
-dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
-rsync on the remote machine. Useful when it's not in your path. Note
-that this is the full path to the binary, not just the directory that
-the binary is in.
+dit(bf(--rsync-path=PROGRAM)) Use this to specify what program is to be run
+on the remote machine to start-up rsync. Often used when rsync is not in
+the default remote-shell's path (e.g. --rsync-path=/usr/local/bin/rsync).
+Note that PROGRAM is run with the help of a shell, so it can be any
+program, script, or command sequence you'd care to run, so long as it does
+not corrupt the standard-in & standard-out that rsync is using to
+communicate.
+
+One tricky example is to set a different default directory on the remote
+machine for use with the bf(--relative) option. For instance:
+
+quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/))
dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
broad range of files that you often don't want to transfer between
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,
-regardless of where the -C was placed on the command-line. This makes them
+regardless of where the bf(-C) was placed on the command-line. This makes them
a lower priority than any rules you specified explicitly. If you want to
control where these CVS excludes get inserted into your filter rules, you
should omit the bf(-C) as a command-line option and use a combination of
quote(tt( rsync -a --files-from=/tmp/foo /usr remote:/backup))
If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
-directory will be created as /backup/bin on the remote host (but the
-contents of the /usr/bin dir would not be sent unless you specified bf(-r)
-or the names were explicitly listed in /tmp/foo). Also keep in mind
+directory will be created as /backup/bin on the remote host. If it
+contains "bin/" (note the trailing slash), the immediate contents of
+the directory would also be sent (without needing to be explicitly
+mentioned in the file -- this began in version 2.6.4). In both cases,
+if the bf(-r) option was enabled, that dir's entire hierarchy would
+also be transferred (keep in mind that bf(-r) needs to be specified
+explicitly with bf(--files-from), since it is not implied by bf(-a)).
+Also note
that the effect of the (enabled by default) bf(--relative) option is to
duplicate only the path info that is read from the file -- it does not
force the duplication of the source-spec path (/usr in this case).
This would copy all the files specified in the /path/file-list file that
was located on the remote "src" host.
-dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
+dit(bf(-0, --from0)) This tells rsync that the rules/filenames it reads from a
file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any
merged files specified in a bf(--filter) rule.
have changed from an earlier backup.
Beginning in version 2.6.4, multiple bf(--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.
+provided, which will cause rsync to search the list in the order specified
+for an exact match.
+If a match is found that differs only in attributes, a local copy is made
+and the attributes updated.
+If a match is 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 bf(--copy-dest) and bf(--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.
+directory using a local 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.
+
+Multiple bf(--copy-dest) directories may be provided, which will cause
+rsync to search the list in the order specified for an unchanged file.
+If a match is 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 bf(--compare-dest) and bf(--link-dest).
quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
-Beginning with version 2.6.4, if more than one bf(--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.
+Beginning in version 2.6.4, multiple bf(--link-dest) directories may be
+provided, which will cause rsync to search the list in the order specified
+for an exact match.
+If a match is found that differs only in attributes, a local copy is made
+and the attributes updated.
+If a match is 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 bf(--compare-dest) and bf(--copy-dest).
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(--address)) By default rsync will bind to the wildcard address when
+connecting to an rsync daemon. The bf(--address) option allows you to
+specify a specific IP address (or hostname) to bind to. See also this
+option in the bf(--daemon) mode section.
+
dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
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
dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the
default.
-dit(bf(-i, --itemize-changes)) Outputs a change-summary for each updated
-item. The format is as follows:
+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').
-quote(tt( *XcstpogDL ITEM_NAME))
+The "%i" escape has a cryptic output that is 9 letters long. The general
+format is like the string bf(UXcstpoga)), where bf(U) is replaced by the
+kind of update being done, bf(X) is replaced by the file-type, and the
+other letters represent attributes that may be output if they are being
+modified.
-The bf(*) will be present if this is a file that is being transferred,
-otherwise it will be replaced with a space. The bf(X) will be replaced by
-one of the following: an "f" for a file, a "d" for a dir, an "L" for a
-symlink, or a "D" for a device. The rest of the letters in the string
-above are the actual letters that will be output if the associated
-attribute for the item is being updated; if not the letter will be replaced
-by either a "-" if no change is occurring, or a "+" if this is a new item.
-The meanings of the attribute letters are as follows:
+The update types that replace the bf(U) are as follows:
+
+quote(itemize(
+ it() A bf(<) means that a file is being transferred to the remote host
+ (sent).
+ it() A bf(>) means that a file is being transferred to the local host
+ (received).
+ it() A bf(c) means that a local change/creation is occurring for the item
+ (such as the creation of a directory or the changing of a symlink, etc.).
+ it() A bf(h) means that the item is a hard-link to another item (requires
+ bf(--hard-links)).
+ it() A bf(.) means that the item is not being updated (though it might
+ have attributes that are being modified).
+))
+
+The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a
+directory, an bf(L) for a symlink, and a bf(D) for a device.
+
+The other letters in the string above are the actual letters that
+will be output if the associated attribute for the item is being updated or
+a "." for no change. Three exceptions to this are: (1) a newly created
+item replaces each letter with a "+", (2) an identical item replaces the
+dots with spaces, and (3) an unknown attribute replaces each letter with
+a "?" (this can happen when talking to an older rsync).
+
+The attribute that is associated with each letter is as follows:
quote(itemize(
it() A bf(c) means the checksum of the file is different and will be
- updated by the file transfer (requries bf(--checksum)).
+ updated by the file transfer (requires bf(--checksum)).
it() A bf(s) means the size of the file is different and will be updated
by the file transfer.
- it() A bf(t) means the modified time is being updated to the server's
- value (requires --times, but transferred files without --times will be
- marked with a bf(T) because the time is updated to the transfer time).
- it() A bf(p) means the permissions are being updated (requires
- bf(--perms)).
- it() An bf(o) means the owner is being updated (requires bf(--owner) and
- root privileges).
- it() A bf(g) means the group is being updated (requires bf(--group)).
- it() A bf(D) means the device is being updated (requires bf(--devices)
- and root privileges).
- it() An bf(L) means the symlink value is being updated (requires
- --links).
+ it() A bf(t) means the modification time is different and is being updated
+ to the sender's value (requires bf(--times)). An alternate value of bf(T)
+ means that the time will be set to the transfer time, which happens
+ anytime a symlink is transferred, or when a file or device is transferred
+ without bf(--times).
+ it() A bf(p) means the permissions are different and are being updated to
+ the sender's value (requires bf(--perms)).
+ it() An bf(o) means the owner is different and is being updated to the
+ sender's value (requires bf(--owner) and root privileges).
+ it() A bf(g) means the group is different and is being updated to the
+ sender's value (requires bf(--group) and the authority to set the group).
+ it() The bf(a) is reserved for a future enhanced version that supports
+ extended file attributes, such as ACLs.
))
+One other output is possible: when deleting files, the "%i" will output
+the string "*deleting" for each item that is being removed (assuming that
+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 logs to stdout on a per-file basis. The log format is
-specified using the same format conventions as the log format option in
-rsyncd.conf.
+rsync client outputs to the user on a per-file 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.)
+
+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 itemized-changes escape (%i) is included in
+the string, in which case 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(--itemized-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 bv(--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
+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).
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
specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when
bf(--delay-updates) was specified (see below).
-For the purposes of the server-config's "refuse options" setting,
+For the purposes of the daemon-config's "refuse options" setting,
bf(--partial-dir) does em(not) imply bf(--partial). This is so that a
refusal of the bf(--partial) option can be used to disallow the overwriting
of destination files with a partial transfer, while still allowing the
each file's destination directory, but you can override this by specifying
the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect
on this value, nor is bf(--partial-dir) considered to be implied for the
-purposes of the server-config's "refuse options" setting.)
+purposes of the daemon-config's "refuse options" setting.)
Conflicts with bf(--inplace).
This option uses more memory on the receiving side (one bit per file
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
-is only useful when accessing an rsync server using the built in
+in a file for accessing a remote rsync daemon. Note that this option
+is only useful when accessing an rsync daemon using the built in
transport, not when using a remote shell as the transport. The file
must not be world readable. It should contain just the password as a
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 you don't usually need to use it explicitly. However, it can
-come in handy for a power user that wants to avoid the "bf(-r --exclude='/*/*')"
+come in handy for a user that wants to avoid the "bf(-r --exclude='/*/*')"
options that rsync might use as a compatibility kluge when generating a
-non-recursive listing.
+non-recursive listing, or to list the files that are involved in a local
+copy (since the destination path is not optional for a local copy, you
+must specify this option explicitly and still include a destination).
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(--write-batch=FILE)) Record a file that can later be applied to
another identical destination with bf(--read-batch). See the "BATCH MODE"
-section for details.
+section for details, and also the bf(--only-write-batch) option.
+
+dit(bf(--only-write-batch=FILE)) Works like bf(--write-batch), except that
+no updates are made on the destination system when creating the batch.
+This lets you transport the changes to the destination system via some
+other means and then apply the changes via bf(--read-batch).
+
+Note that you can feel free to write the batch directly to some portable
+media: if this media fills to capacity before the end of the transfer, you
+can just apply that partial transfer to the destination and repeat the
+whole process to get the rest of the changes (as long as you don't mind a
+partially updated destination system while the multi-update cycle is
+happening).
+
+Also note that you only save bandwidth when pushing changes to a remote
+system because this allows the batched data to be diverted from the sender
+into the batch file without having to flow over the wire to the receiver
+(when pulling, the sender is remote, and thus can't write the batch).
dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
file previously generated by bf(--write-batch).
If em(FILE) is "-" the batch data will be read from standard input.
See the "BATCH MODE" section for details.
+dit(bf(--protocol=NUM)) Force an older protocol version to be used. This
+is useful for creating a batch file that is compatible with an older
+version of rsync. For instance, if rsync 2.6.4 is being used with the
+bf(--write-batch) option, but rsync 2.6.3 is what will be used to run the
+bf(--read-batch) option, you should use "--protocol=28" when creating the
+batch file to force the older protocol version to be used in the batch
+file (assuming you can't upgrade the rsync on the reading system).
+
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
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.
+daemon you start running may be accessed using an rsync client 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
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 bf(--daemon) option or when connecting to a
-rsync server. The bf(--address) option allows you to specify a specific IP
-address (or hostname) to bind to. This makes virtual hosting possible
-in conjunction with the bf(--config) option. See also the "address" global
-option in the rsyncd.conf manpage.
+dit(bf(--address)) By default rsync will bind to the wildcard address when
+run as a daemon with the bf(--daemon) option. The bf(--address) option
+allows you to specify a specific IP address (or hostname) to bind to. This
+makes virtual hosting possible in conjunction with the bf(--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.
default to having that modifier set. For instance, "merge,-/ .excl" would
treat the contents of .excl as absolute-path excludes,
while "dir-merge,s .filt" and ":sC" would each make all their
- per-directory rules apply only on the server side.
+ per-directory rules apply only on the sending side.
)
The following modifiers are accepted after a "+" or "-":
being transferred. The default is for a rule to affect both sides
unless bf(--delete-excluded) was specified, in which case default rules
become sender-side only. See also the hide (H) and show (S) rules,
- which are an alternate way to specify server-side includes/excludes.
+ which are an alternate way to specify sending-side includes/excludes.
it() An bf(r) is used to indicate that the rule applies to the receiving
side. When a rule affects the receiving side, it prevents files from
being deleted. See the bf(s) modifier for more info. See also the
The read-batch option expects the destination tree that it is updating
to be identical to the destination tree that was used to create the
batch update fileset. When a difference between the destination trees
-is encountered the update might be discarded with no error (if the file
+is encountered the update might be discarded with a warning (if the file
appears to be up-to-date already) or the file-update may be attempted
and then, if the file fails to verify, the update discarded with an
error. This means that it should be safe to re-run a read-batch operation
The rsync version used on all destinations must be at least as new as the
one used to generate the batch file. Rsync will die with an error if the
protocol version in the batch file is too new for the batch-reading rsync
-to handle.
-
-The bf(--dry-run) (bf(-n)) option does not work in batch mode and yields a runtime
-error.
+to handle. See also the bf(--protocol) option for a way to have the
+creating rsync generate a batch file that an older rsync can understand.
+(Note that batch files changed format in version 2.6.3, so mixing versions
+older than that with newer versions will not work.)
When reading a batch file, rsync will force the value of certain options
to match the data in the batch file if you didn't set them to the same
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 omitted altogether.
+unsafe links to be omitted altogether. (Note that you must specify
+bf(--links) for bf(--safe-links) to have any effect.)
Symbolic links are considered unsafe if they are absolute symlinks
(start with bf(/)), empty, or if they contain enough bf("..")
components to ascend from the directory being copied.
+Here's a summary of how the symlink options are interpreted. The list is
+in order of precedence, so if your combination of options isn't mentioned,
+use the first line that is a complete subset of your options:
+
+dit(bf(--copy-links)) Turn all symlinks into normal files (leaving no
+symlinks for any other options to affect).
+
+dit(bf(--links --copy-unsafe-links)) Turn all unsafe symlinks into files
+and duplicate all safe symlinks.
+
+dit(bf(--copy-unsafe-links)) Turn all unsafe symlinks into files, noisily
+skip all safe symlinks.
+
+dit(bf(--links --safe-links)) Duplicate safe symlinks and skip unsafe
+ones.
+
+dit(bf(--links)) Duplicate all symlinks.
+
manpagediagnostics()
rsync occasionally produces error messages that may seem a little
them; or an option was specified that is supported by the client and
not by the server.
dit(bf(5)) Error starting client-server protocol
+dit(bf(6)) Daemon unable to append to log-file
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(22)) Error allocating core memory buffers
dit(bf(23)) Partial transfer due to error
dit(bf(24)) Partial transfer due to vanished source files
+dit(bf(25)) The --max-delete limit stopped deletions
dit(bf(30)) Timeout in data send/receive
enddit()
daemon without user intervention. Note that this does not supply a
password to a shell transport such as ssh.
dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
-are used to determine the default username sent to an rsync server.
+are used to determine the default username sent to an rsync daemon.
If neither is set, the username defaults to "nobody".
dit(bf(HOME)) The HOME environment variable is used to find the user's
default .cvsignore file.
Please report bugs! See the website at
url(http://rsync.samba.org/)(http://rsync.samba.org/)
+manpagesection(VERSION)
+
+This man page is current for version 2.6.5 of rsync.
+
manpagesection(CREDITS)
rsync is distributed under the GNU public license. See the file
git.samba.org / rsync.git / blobdiff