--backup-dir make backups into this directory
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
-u, --update update only (don't overwrite newer files)
- --inplace update the destination files inplace
- -K, --keep-dirlinks treat symlinked dir on receiver as dir
+ --inplace update the destination files in-place
+ -d, --dirs transfer directories without recursing
-l, --links copy symlinks as symlinks
-L, --copy-links copy the referent of all symlinks
--copy-unsafe-links copy the referent of "unsafe" symlinks
--safe-links ignore "unsafe" symlinks
-H, --hard-links preserve hard links
+ -K, --keep-dirlinks treat symlinked dir on receiver as dir
-p, --perms preserve permissions
-o, --owner preserve owner (root only)
-g, --group preserve group
-D, --devices preserve devices (root only)
-t, --times preserve times
+ -O, --omit-dir-times omit directories when preserving times
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy whole files, no incremental checks
--rsync-path=PATH specify path to rsync on the remote machine
--existing only update files that already exist
--ignore-existing ignore files that already exist on receiver
+ --del an alias for --delete-during
--delete delete files that don't exist on sender
- --delete-excluded also delete excluded files on receiver
+ --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
--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
+ --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
+ --delay-updates update transferred files into place at end
--numeric-ids don't map uid/gid values by user/group name
--timeout=TIME set I/O timeout in seconds
-I, --ignore-times turn off mod time & file size quick check
--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
+ -f, --filter=RULE add a file-filtering RULE
+ -F same as --filter=': /.rsync-filter'
+ repeated: --filter='- .rsync-filter'
--exclude=PATTERN exclude files matching PATTERN
--exclude-from=FILE exclude patterns listed in FILE
--include=PATTERN don't exclude files matching PATTERN
--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
--progress show progress during transfer
--log-format=FORMAT log file transfers using specified format
--password-file=FILE get 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 batch to FILE
--read-batch=FILE read a batch from FILE
-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()
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
specify bf(-H).
dit(bf(-r, --recursive)) This tells rsync to copy directories
-recursively. If you don't specify this then rsync won't copy
-directories at all.
+recursively. See also --dirs (-d).
dit(bf(-R, --relative)) Use relative paths. This means that the full path
names specified on the command line are sent to the server rather than
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
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
regardless of the timestamps. This might change in the future (feel
free to comment on this on the mailing list if you have an opinion).
-dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
-pointing to a directory, it will be treated as matching a directory
-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 (since it does not yet try to sort
-data matches -- a future version may improve this).
+file, meaning that the rsync algorithm can't accomplish the full amount of
+network reduction it might be able to otherwise (since it does not yet try
+to sort data matches). One exception to this is if you combine the option
+with --backup, since rsync is smart enough to use the backup file as the
+basis file for the transfer.
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.
The option implies --partial (since an interrupted transfer does not delete
-the file), but conflicts with --partial-dir, --compare-dest, and
---link-dest (a future rsync version will hopefully update the protocol to
-remove these restrictions).
+the file), but conflicts with --partial-dir and --delay-updates.
+Prior to rsync 2.6.4 --inplace was also incompatible with --compare-dest,
+--copy-dest, and --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
should not use this option to update files that are in use. Also note that
-rsync will be unable to update a file inplace that is not writable by the
+rsync will be unable to update a file in-place that is not writable by the
receiving user.
+dit(bf(-d, --dirs)) Tell the sending side to include any directories that
+are encountered. Unlike --recursive, a directory's contents are not copied
+unless the directory was specified on the command-line as either "." or a
+name with a trailing slash (e.g. "foo/"). Without this option or the
+--recursive option, rsync will skip all directories it encounters (and
+output a message to that effect for each one).
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
This option can be quite slow, so only use it if you need it.
+dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
+pointing to a directory, it will be treated as matching a directory
+from the sender.
+
dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
is not used and the whole file is sent as-is instead. The transfer may be
faster if this option is used when the bandwidth between the source and
updated (though the rsync algorithm will make the update fairly efficient
if the files haven't actually changed, you're much better off using -t).
+dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
+it is preserving modification times (see --times). If NFS is sharing
+the directories on the receiving side, it is a good idea to use -O.
+
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.
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").
-This option has no effect if directory recursion is not selected.
+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 individual 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 unless directory recursion is enabled.
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
destination. You can override this with the --ignore-errors option.
+The --delete option may be combined with one of the --delete-WHEN options
+without conflict, as well as --delete-excluded. However, if none of the
+--delete-WHEN options are specified, rsync will currently choose the
+--delete-before algorithm. A future version may change this to choose the
+--delete-during algorithm. See also --delete-after.
+
+dit(bf(--delete-before)) Request that the file-deletions on the receiving
+side be done before the transfer starts. This is the default if --delete
+or --delete-excluded is specified without one of the --delete-WHEN options.
+See --delete (which is implied) for more details on file-deletion.
+
+Deleting before the transfer is helpful if the filesystem is tight for space
+and removing extraneous files would help to make the transfer possible.
+However, it does introduce a delay before the start of the transfer,
+and this delay might cause the transfer to timeout (if --timeout was
+specified).
+
+dit(bf(--delete-during, --del)) Request that the file-deletions on the
+receiving side be done incrementally as the transfer happens. This is
+a faster method than chosing the before- or after-transfer algorithm,
+but it is only supported beginning with rsync version 2.6.4.
+See --delete (which is implied) for more details on file-deletion.
+
+dit(bf(--delete-after)) Request that the file-deletions on the receiving
+side be done after the transfer has completed. This is useful if you
+are sending new per-directory merge files as a part of the transfer and
+you want their exclusions to take effect for the delete phase of the
+current transfer.
+See --delete (which is implied) for more details on file-deletion.
+
dit(bf(--delete-excluded)) In addition to deleting the files on the
receiving side that are not on the sending side, this tells rsync to also
delete any files on the receiving side that are excluded (see --exclude).
-Implies --delete.
-
-dit(bf(--delete-after)) By default rsync does file deletions on the
-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.
+See --delete (which is implied) for more details on file-deletion.
dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
even when there are I/O errors.
.cvsignore file and matches one of the patterns listed therein.
See the bf(cvs(1)) manual for more information.
-dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
-certain files from the list of files to be transferred. This is most
-useful in combination with a recursive transfer.
+dit(bf(-f, --filter=RULE)) This option allows you to add rules to selectively
+exclude certain files from the list of files to be transferred. This is
+most useful in combination with a recursive transfer.
-You may use as many --exclude options on the command line as you like
+You may use as many --filter options on the command line as you like
to build up the list of files to exclude.
-See the EXCLUDE PATTERNS section for detailed information on this option.
+See the FILTER RULES section for detailed information on this option.
+
+dit(bf(-F)) The -F option is a shorthand for adding two --filter rules to
+your command. The first time it is used is a shorthand for this rule:
+
+verb(
+ --filter=': /.rsync-filter'
+)
+
+This tells rsync to look for per-directory .rsync-filter files that have
+been sprinkled through the hierarchy and use their rules to filter the
+files in the transfer. If -F is repeated, it is a shorthand for this
+rule:
+
+verb(
+ --filter='- .rsync-filter'
+)
+
+This filters out the .rsync-filter files themselves from the transfer.
+
+See the FILTER RULES section for detailed information on how these options
+work.
+
+dit(bf(--exclude=PATTERN)) This option is a simplified form of the
+--filter option that defaults to an exclude rule and does not allow
+the full rule-parsing syntax of normal filter rules.
+
+See the FILTER RULES section for detailed information on this option.
dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
option, but instead it adds all exclude patterns listed in the file
';' or '#' are ignored.
If em(FILE) is bf(-) the list will be read from standard input.
-dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
-specified pattern of filenames. This is useful as it allows you to
-build up quite complex exclude/include rules.
+dit(bf(--include=PATTERN)) This option is a simplified form of the
+--filter option that defaults to an include rule and does not allow
+the full rule-parsing syntax of normal filter rules.
-See the EXCLUDE PATTERNS section for detailed information on this option.
+See the FILTER RULES section for detailed information on this option.
dit(bf(--include-from=FILE)) This specifies a list of include patterns
from a file.
dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
-This affects --exclude-from, --include-from, and --files-from.
+This affects --exclude-from, --include-from, --files-from, and any
+merged files specified in a --filter rule.
It does not affect --cvs-exclude (since all names read from a .cvsignore
file are split on whitespace).
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
-around this bug by avoiding the -o option.
+(or implied by -a). You can work-around this bug by avoiding the -o option
+when sending to an old rsync.
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
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,
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
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).
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 at the end of any other filter rules. Note that if you are
+supplying your own filter 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).
You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
variable. Setting this in the environment does not force --partial to be
-enabled, but rather it effects where partial files go when --partial (or
--P) is used. For instance, instead of specifying --partial-dir=.rsync-tmp
+enabled, but rather it effects where partial files go when --partial is
+specified. For instance, instead of using --partial-dir=.rsync-tmp
along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
environment and then just use the -P option to turn on the use of the
-.rsync-tmp dir for partial transfers. The only time the --partial option
-does not look for this environment value is when --inplace was also
-specified (since --inplace conflicts with --partial-dir).
+.rsync-tmp dir for partial transfers. The only time that the --partial
+option does not look for this environment value is (1) when --inplace was
+specified (since --inplace conflicts with --partial-dir), or (2) when
+--delay-updates was specified (see below).
+
+dit(bf(--delay-updates)) This option puts the temporary file from each
+updated file into the file's partial-dir (see above) until the end of the
+transfer, at which time all the files are renamed into place in rapid
+succession. This attempts to make the updating of the files a little more
+atomic. If you don't specify the --partial-dir option, this option will
+cause it to default to ".~tmp~" (RSYNC_PARTIAL_DIR is not consulted for
+this value). Conflicts with --inplace.
+
+This option uses more memory on the receiving side (one bit per file
+transferred) and also requires enough free disk space on the receiving
+side to hold an additional copy of all the updated files. Note also that
+you should not use an absolute path to --partial-dir unless there is no
+chance of any of the files in the transfer having the same name (since all
+the updated files will be put into a single directory if the path is
+absolute).
+
+See also the "atomic-rsync" perl script in the "support" subdir for an
+update algorithm that is even more atomic (it uses --link-dest and a
+parallel hierarchy of files).
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
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)
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 "-r --exclude="/*/*"
+options that rsync might use as a compatibility kluge when generating a
+non-recursive listing.
+
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second. This option is most effective when
using rsync with large files (several megabytes and up). Due to the nature
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
enddit()
-manpagesection(EXCLUDE PATTERNS)
+The options allowed when starting an rsync daemon are as follows:
-The exclude and include patterns specified to rsync allow for flexible
-selection of which files to transfer and which files to skip.
+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.
-Rsync builds an ordered list of include/exclude options as specified on
-the command line. Rsync checks each file and directory
-name against each exclude/include pattern in turn. The first matching
-pattern is acted on. If it is an exclude pattern, then that file is
-skipped. If it is an include pattern then that filename is not
-skipped. If no matching include/exclude pattern is found then the
+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(FILTER RULES)
+
+The filter rules allow for flexible selection of which files to transfer
+(include) and which files to skip (exclude). The rules either directly
+specify include/exclude patterns or they specify a way to acquire more
+include/exclude patterns (e.g. to read them from a file).
+
+As the list of files/directories to transfer is built, rsync checks each
+name to be transferred against the list of include/exclude patterns in
+turn, and the first matching pattern is acted on: if it is an exclude
+pattern, then that file is skipped; if it is an include pattern then that
+filename is not skipped; if no matching pattern is found, then the
filename is not skipped.
-The filenames matched against the exclude/include patterns are relative
-to the "root of the transfer". If you think of the transfer as a
-subtree of names that are being sent from sender to receiver, the root
-is where the tree starts to be duplicated in the destination directory.
-This root governs where patterns that start with a / match (see below).
+Rsync builds an ordered list of filter rules as specified on the
+command-line. Filter rules have the following syntax:
+
+itemize(
+ it() x RULE
+ it() xMODIFIERS RULE
+ it() !
+)
+
+The 'x' is a single-letter that specifies the kind of rule to create. It
+can have trailing modifiers, and is separated from the RULE by one of the
+following characters: a single space, an equal-sign (=), or an underscore
+(_). Here are the available rule prefixes:
+
+verb(
+ - specifies an exclude pattern.
+ + specifies an include pattern.
+ . specifies a merge-file to read for more rules.
+ : specifies a per-directory merge-file.
+ ! clears the current include/exclude list
+)
+
+Note that the --include/--exclude command-line options do not allow the
+full range of rule parsing as described above -- they only allow the
+specification of include/exclude patterns and the "!" token (not to
+mention the comment lines when reading rules from a file). If a pattern
+does not begin with "- " (dash, space) or "+ " (plus, space), then the
+rule will be interpreted as if "+ " (for an include option) or "- " (for
+an exclude option) were prefixed to the string. A --filter option, on
+the other hand, must always contain one of the prefixes above.
+
+Note also that the --filter, --include, and --exclude options take one
+rule/pattern each. To add multiple ones, you can repeat the options on
+the command-line, use the merge-file syntax of the --filter option, or
+the --include-from/--exclude-from options.
+
+When rules are being read from a file, empty lines are ignored, as are
+comment lines that start with a "#".
+
+manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
+
+You can include and exclude files by specifing patterns using the "+" and
+"-" filter rules (as introduced in the FILTER RULES section above). These
+rules specify a pattern that is matched against the names of the files
+that are going to be transferred. These patterns can take several forms:
+
+itemize(
+
+ it() if the pattern starts with a / then it is anchored to a
+ particular spot in the hierarchy of files, otherwise it is matched
+ against the end of the pathname. This is similar to a leading ^ in
+ regular expressions.
+ Thus "/foo" would match a file called "foo" at either the "root of the
+ transfer" (for a global rule) or in the merge-file's directory (for a
+ per-directory rule).
+ An unqualified "foo" would match any file or directory named "foo"
+ anywhere in the tree because the algorithm is applied recursively from
+ the
+ top down; it behaves as if each path component gets a turn at being the
+ end of the file name. Even the unanchored "sub/foo" would match at
+ any point in the hierarchy where a "foo" was found within a directory
+ named "sub". See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for
+ a full discussion of how to specify a pattern that matches at the root
+ of the transfer.
+
+ it() if the pattern ends with a / then it will only match a
+ directory, not a file, link, or device.
+
+ it() if the pattern contains a wildcard character from the set
+ *?[ then expression matching is applied using the shell filename
+ matching rules. Otherwise a simple string match is used.
+
+ it() the double asterisk pattern "**" will match slashes while a
+ single asterisk pattern "*" will stop at slashes.
+
+ it() if the pattern contains a / (not counting a trailing /) or a "**"
+ then it is matched against the full pathname, including any leading
+ directories. If the pattern doesn't contain a / or a "**", then it is
+ matched only against the final component of the filename.
+ (Remember that the algorithm is applied recursively so "full filename"
+ can actually be any portion of a path fomr the starting directory on
+ down.)
+
+)
+
+Note that, when using the --recursive (-r) option (which is implied by
+-a), every subcomponent of every path is visited from the top down, so
+include/exclude patterns get applied recursively to each subcomponent's
+full name (e.g. to include "/foo/bar/baz" the subcomponents "/foo" and
+"/foo/bar" must not be excluded).
+The exclude patterns actually short-circuit the directory traversal stage
+when rsync finds the files to send. If a pattern excludes a particular
+parent directory, it can render a deeper include pattern ineffectual
+because rsync did not descend through that excluded section of the
+hierarchy. This is particularly important when using a trailing '*' rule.
+For instance, this won't work:
+
+verb(
+ + /some/path/this-file-will-not-be-found
+ + /file-is-included
+ - *
+)
+
+This fails because the parent directory "some" is excluded by the '*'
+rule, so rsync never visits any of the files in the "some" or "some/path"
+directories. One solution is to ask for all directories in the hierarchy
+to be included by using a single rule: "+_*/" (put it somewhere before the
+"-_*" rule). Another solution is to add specific include rules for all
+the parent dirs that need to be visited. For instance, this set of rules
+works fine:
+
+verb(
+ + /some/
+ + /some/path/
+ + /some/path/this-file-is-found
+ + /file-also-included
+ - *
+)
+
+Here are some examples of exclude/include matching:
+
+itemize(
+ it() "- *.o" would exclude all filenames matching *.o
+ it() "- /foo" would exclude a file called foo in the transfer-root directory
+ it() "- foo/" would exclude any directory called foo
+ it() "- /foo/*/bar" would exclude any file called bar two
+ levels below a directory called foo in the transfer-root directory
+ it() "- /foo/**/bar" would exclude any file called bar two
+ or more levels below a directory called foo in the transfer-root directory
+ it() The combination of "+ */", "+ *.c", and "- *" would include all
+ directories and C source files but nothing else.
+ it() The combination of "+ foo/", "+ foo/bar.c", and "- *" would include
+ only the foo directory and foo/bar.c (the foo directory must be
+ explicitly included or it would be excluded by the "*")
+)
+
+manpagesection(MERGE-FILE FILTER RULES)
+
+You can merge whole files into your filter rules by specifying either a
+"." or a ":" filter rule (as introduced in the FILTER RULES section
+above).
+
+There are two kinds of merged files -- single-instance ('.') and
+per-directory (':'). A single-instance merge file is read one time, and
+its rules are incorporated into the filter list in the place of the "."
+rule. For per-directory merge files, rsync will scan every directory that
+it traverses for the named file, merging its contents when the file exists
+into the current list of inherited rules. These per-directory rule files
+must be created on the sending side because it is the sending side that is
+being scanned for the available files to transfer. These rule files may
+also need to be transferred to the receiving side if you want them to
+affect what files don't get deleted (see PER-DIRECTORY RULES AND DELETE
+below).
+
+Some examples:
+
+verb(
+ . /etc/rsync/default.rules
+ : .per-dir-filter
+ :n- .non-inherited-per-dir-excludes
+)
+
+The following modifiers are accepted after the "." or ":":
+
+itemize(
+ it() A "-" specifies that the file should consist of only exclude
+ patterns, with no other rule-parsing except for the list-clearing
+ token ("!").
+
+ it() A "+" specifies that the file should consist of only include
+ patterns, with no other rule-parsing except for the list-clearing
+ token ("!").
+
+ it() A "C" is a shorthand for the modifiers "sn-", which makes the
+ parsing compatible with the way CVS parses their exclude files. If no
+ filename is specified, ".cvsignore" is assumed.
+
+ it() A "e" will exclude the merge-file from the transfer; e.g.
+ ":e_.rules" is like ":_.rules" and "-_.rules".
+
+ it() An "n" specifies that the rules are not inherited by subdirectories.
+
+ it() An "s" specifies that the rules are split on all whitespace instead
+ of the normal line-splitting. This also turns off comments. Note: the
+ space that separates the prefix from the rule is treated specially, so
+ "- foo + bar" is parsed as two rules (assuming that "-" or "+" was not
+ specified to turn off the parsing of prefixes).
+)
+
+Per-directory rules are inherited in all subdirectories of the directory
+where the merge-file was found unless the 'n' modifier was used. Each
+subdirectory's rules are prefixed to the inherited per-directory rules
+from its parents, which gives the newest rules a higher priority than the
+inherited rules. The entire set of per-dir rules is grouped together in
+the spot where the merge-file was specified, so it is possible to override
+per-dir rules via a rule that got specified earlier in the list of global
+rules. When the list-clearing rule ("!") is read from a per-directory
+file, it only clears the inherited rules for the current merge file.
+
+Another way to prevent a single per-dir rule from being inherited is to
+anchor it with a leading slash. Anchored rules in a per-directory
+merge-file are relative to the merge-file's directory, so a pattern "/foo"
+would only match the file "foo" in the directory where the per-dir filter
+file was found.
+
+Here's an example filter file which you'd specify via --filter=". file":
+
+verb(
+ . /home/user/.global-filter
+ - *.gz
+ : .rules
+ + *.[ch]
+ - *.o
+)
+
+This will merge the contents of the /home/user/.global-filter file at the
+start of the list and also turns the ".rules" filename into a per-directory
+filter file. All rules read-in prior to the start of the directory scan
+follow the global anchoring rules (i.e. a leading slash matches at the root
+of the transfer).
+
+If a per-directory merge-file is specified with a path that is a parent
+directory of the first transfer directory, rsync will scan all the parent
+dirs from that starting point to the transfer directory for the indicated
+per-directory file. For instance, here is a common filter (see -F):
+
+verb(
+ --filter=': /.rsync-filter'
+)
+
+That rule tells rsync to scan for the file .rsync-filter in all
+directories from the root down through the parent directory of the
+transfer prior to the start of the normal directory scan of the file in
+the directories that are sent as a part of the transfer. (Note: for an
+rsync daemon, the root is always the same as the module's "path".)
+
+Some examples of this pre-scanning for per-directory files:
+
+verb(
+ rsync -avF /src/path/ /dest/dir
+ rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
+ rsync -av --fitler=': .rsync-filter' /src/path/ /dest/dir
+)
+
+The first two commands above will look for ".rsync-filter" in "/" and
+"/src" before the normal scan begins looking for the file in "/src/path"
+and its subdirectories. The last command avoids the parent-dir scan
+and only looks for the ".rsync-filter" files in each directory that is
+a part of the transfer.
+
+If you want to include the contents of a ".cvsignore" in your patterns,
+you should use the rule ":C" -- this is a short-hand for the rule
+":sn-_.cvsignore", and ensures that the .cvsignore file's contents are
+interpreted according to the same parsing rules that CVS uses. You can
+use this to affect where the --cvs-exclude (-C) option's inclusion of the
+per-directory .cvsignore file gets placed into your rules by putting a
+":C" wherever you like in your filter rules. Without this, rsync would
+add the per-dir rule for the .cvignore file at the end of all your other
+rules (giving it a lower priority than your command-line rules). For
+example:
+
+verb(
+ cat <<EOT | rsync -avC --filter='. -' a/ b
+ + foo.o
+ :C
+ - *.old
+ EOT
+
+ rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
+)
+
+Both of the above rsync commands are identical. Each one will merge all
+the per-directory .cvsignore rules in the middle of the list rather than
+at the end. This allows their dir-specific rules to supersede the rules
+that follow the :C instead of being subservient to all your rules. (The
+global rules taken from the $HOME/.cvsignore file and from $CVSIGNORE are
+not repositioned from their spot at the end of your rules, however -- feel
+free to manually include $HOME/.cvsignore elsewhere in your rules.)
+
+manpagesection(LIST-CLEARING FILTER RULE)
+
+You can clear the current include/exclude list by using the "!" filter
+rule (as introduced in the FILTER RULES section above). The "current"
+list is either the global list of rules (if the rule is encountered while
+parsing the filter options) or a set of per-directory rules (which are
+inherited in their own sub-list, so a subdirectory can use this to clear
+out the parent's rules).
+
+manpagesection(ANCHORING INCLUDE/EXCLUDE PATTERNS)
+
+As mentioned earlier, global include/exclude patterns are anchored at the
+"root of the transfer" (as opposed to per-directory patterns, which are
+anchored at the merge-file's directory). If you think of the transfer as
+a subtree of names that are being sent from sender to receiver, the
+transfer-root is where the tree starts to be duplicated in the destination
+directory. This root governs where patterns that start with a / match.
Because the matching is relative to the transfer-root, changing the
trailing slash on a source path or changing your use of the --relative
option affects the path you need to use in your matching (in addition to
changing how much of the file tree is duplicated on the destination
-system). The following examples demonstrate this.
+host). The following examples demonstrate this.
Let's say that we want to match two source files, one with an absolute
path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
Target file: /dest/you/bar/baz
)
-The easiest way to see what name you should include/exclude is to just
+The easiest way to see what name you should filter is to just
look at the output when using --verbose and put a / in front of the name
(use the --dry-run option if you're not yet ready to copy any files).
-Note that, when using the --recursive (-r) option (which is implied by -a),
-every subcomponent of
-every path is visited from the top down, so include/exclude patterns get
-applied recursively to each subcomponent.
-The exclude patterns actually short-circuit the directory traversal stage
-when rsync finds the files to send. If a pattern excludes a particular
-parent directory, it can render a deeper include pattern ineffectual
-because rsync did not descend through that excluded section of the
-hierarchy.
-
-Note also that the --include and --exclude options take one pattern
-each. To add multiple patterns use the --include-from and
---exclude-from options or multiple --include and --exclude options.
+manpagesection(PER-DIRECTORY RULES AND DELETE)
-The patterns can take several forms. The rules are:
+Without a delete option, per-directory rules are only relevant on the
+sending side, so you can feel free to exclude the merge files themselves
+without affecting the transfer. To make this easy, the 'e' modifier adds
+this exclude for you, as seen in these two equivalent commands:
-itemize(
-
- it() if the pattern starts with a / then it is matched against the
- start of the filename, otherwise it is matched against the end of
- the filename.
- This is the equivalent of a leading ^ in regular expressions.
- Thus "/foo" would match a file called "foo" at the transfer-root
- (see above for how this is different from the filesystem-root).
- On the other hand, "foo" would match any file called "foo"
- anywhere in the tree because the algorithm is applied recursively from
- top down; it behaves as if each path component gets a turn at being the
- end of the file name.
-
- it() if the pattern ends with a / then it will only match a
- directory, not a file, link, or device.
-
- it() if the pattern contains a wildcard character from the set
- *?[ then expression matching is applied using the shell filename
- matching rules. Otherwise a simple string match is used.
-
- it() the double asterisk pattern "**" will match slashes while a
- single asterisk pattern "*" will stop at slashes.
-
- it() if the pattern contains a / (not counting a trailing /) or a "**"
- then it is matched against the full filename, including any leading
- directory. If the pattern doesn't contain a / or a "**", then it is
- matched only against the final component of the filename. Again,
- remember that the algorithm is applied recursively so "full filename" can
- actually be any portion of a path below the starting directory.
-
- it() if the pattern starts with "+ " (a plus followed by a space)
- then it is always considered an include pattern, even if specified as
- part of an exclude option. The prefix is discarded before matching.
-
- it() if the pattern starts with "- " (a minus followed by a space)
- then it is always considered an exclude pattern, even if specified as
- part of an include option. The prefix is discarded before matching.
-
- it() if the pattern is a single exclamation mark ! then the current
- include/exclude list is reset, removing all previously defined patterns.
+verb(
+ rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
+ rsync -av --filter=':e .excl' host:src/dir /dest
)
-The +/- rules are most useful in a list that was read from a file, allowing
-you to have a single exclude list that contains both include and exclude
-options in the proper order.
-
-Remember that the matching occurs at every step in the traversal of the
-directory hierarchy, so you must be sure that all the parent directories of
-the files you want to include are not excluded. This is particularly
-important when using a trailing '*' rule. For instance, this won't work:
+However, if you want to do a delete on the receiving side AND you want some
+files to be excluded from being deleted, you'll need to be sure that the
+receiving side knows what files to exclude. The easiest way is to include
+the per-directory merge files in the transfer and use --delete-after,
+because this ensures that the receiving side gets all the same exclude
+rules as the sending side before it tries to delete anything:
verb(
- + /some/path/this-file-will-not-be-found
- + /file-is-included
- - *
+ rsync -avF --delete-after host:src/dir /dest
)
-This fails because the parent directory "some" is excluded by the '*' rule,
-so rsync never visits any of the files in the "some" or "some/path"
-directories. One solution is to ask for all directories in the hierarchy
-to be included by using a single rule: --include='*/' (put it somewhere
-before the --exclude='*' rule). Another solution is to add specific
-include rules for all the parent dirs that need to be visited. For
-instance, this set of rules works fine:
+However, if the merge files are not a part of the transfer, you'll need to
+either specify some global exclude rules (i.e. specified on the command
+line), or you'll need to maintain your own per-directory merge files on
+the receiving side. An example of the first is this (assume that the
+remote .rules files exclude themselves):
verb(
- + /some/
- + /some/path/
- + /some/path/this-file-is-found
- + /file-also-included
- - *
+ rsync -av --filter=': .rules' --filter='. /my/extra.rules'
+ --delete host:src/dir /dest
)
-Here are some examples of exclude/include matching:
+In the above example the extra.rules file can affect both sides of the
+transfer, but (on the sending side) the rules are subservient to the rules
+merged from the .rules files because they were specified after the
+per-directory merge rule.
-itemize(
- it() --exclude "*.o" would exclude all filenames matching *.o
- it() --exclude "/foo" would exclude a file called foo in the transfer-root directory
- it() --exclude "foo/" would exclude any directory called foo
- it() --exclude "/foo/*/bar" would exclude any file called bar two
- levels below a directory called foo in the transfer-root directory
- it() --exclude "/foo/**/bar" would exclude any file called bar two
- or more levels below a directory called foo in the transfer-root directory
- it() --include "*/" --include "*.c" --exclude "*" would include all
- directories and C source files
- it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
- only foo/bar.c (the foo/ directory must be explicitly included or
- it would be excluded by the "*")
+In one final example, the remote side is excluding the .rsync-filter
+files from the transfer, but we want to use our own .rsync-filter files
+to control what gets deleted on the receiving side. To do this we must
+specifically exclude the per-directory merge files (so that they don't get
+deleted) and then put rules into the local files to control what else
+should not get deleted. Like one of these commands:
+
+verb(
+ rsync -av --filter=':e /.rsync-filter' --delete host:src/dir /dest
+ rsync -avFF --delete host:src/dir /dest
)
manpagesection(BATCH MODE)
scripts (such as .cshrc or .profile) that contain output statements
for non-interactive logins.
-If you are having trouble debugging include and exclude patterns, then
+If you are having trouble debugging filter patterns, then
try specifying the -vv option. At this level of verbosity rsync will
show why each individual file is included or excluded.