The options of rsync are organized into 3 different scopes:
- Hub scope :
Global rsync options, active for every links - Volume scope :
Specific options to a volume, active for the volume's links - Link scope :
Options for a specific link, in 1 direction
The options are passed to the rsync commands in that order, from the global scope then volume, then link scope.
The filters used by
--filter,--excludeand--include, are described in a dedicated Rsync Filter Rules page.
¶ HUBS
Here is a list of the mostly used options in the hub scope. If placed on the hub scope, these options are active everytime rsync is ran. It is safe to use them, otherwise explained.
¶ --recursive, -r
Recurse into directories
This is a good option to put in the global options (enabled for every transfers) unless you have a specific usage and you know what you are doing
¶ --times, -t
Preserve modification times
From rsync manual :
This tells rsync to transfer modification times along with the files and update them on the remote system. Note that if this option is not used, the optimization that excludes files that have not been modified cannot be effective; in other words, a missing -t (or -a) will cause the next transfer to behave as if it used --ignore-times (-I), causing all files to be updated (though rsync's delta-transfer algorithm will make the update fairly efficient if the files haven't actually changed, you're much better off using -t).
A modern rsync that is using transfer protocol 30 or 31 conveys a modify time using up to 8-bytes. If rsync is forced to speak an older protocol (perhaps due to the remote rsync being older than 3.0.0) a modify time is conveyed using 4-bytes. Prior to 3.2.7, these shorter values could convey a date range of 13-Dec-1901 to 19-Jan-2038. Beginning with 3.2.7, these 4-byte values now convey a date range of 1-Jan-1970 to 7-Feb-2106. If you have files dated older than 1970, make sure your rsync executables are upgraded so that the full range of dates can be conveyed.
This is a good option to put in the global options (enabled for every transfers)
¶ --update, -u
Skip files that are newer on the receiver
From rsync manual :
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 modification time equal to the source file's, it will be updated if the sizes are different.)
Note that this does not affect the copying of dirs, symlinks, or other special files. Also, 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 where the destination has a file, the transfer would occur regardless of the timestamps.
This option is a TRANSFER RULE, so don't expect any exclude side effects.
A caution for those that choose to combine --inplace with --update: an interrupted transfer will leave behind a partial file on the receiving side that has a very recent modified time, so
re-running the transfer will probably not continue the interrupted file. As such, it is usually best to avoid combining this with --inplace unless you have implemented manual steps to handle any interrupted in-progress files.
This is a good option to put in the global options (enabled for every transfers). It prevents the files to be overwriten if they have a newer modification date. Also, in a multi-sources scenario, it allows many sources to increment the same files (the newer file wins and is propagated everywhere)
¶ --omit-dir-times, -O
Omit directories from
--times
From rsync manual :
This tells rsync to omit directories when it is preserving modification, access, and create times. If NFS is sharing the directories on the receiving side, it is a good idea to use -O. This option is inferred if you use --backup without --backup- dir.
This option also has the side-effect of avoiding early creation of missing sub-directories when incremental recursion is enabled, as discussed in the --inc-recursive section.
This is a good option to put in the global options (enabled for every transfers). The directories won't have their times propagated but in most cases we don't need it. It also prevents updating times on directories everytime there is an activity inside that directory
¶ VOLUMES
Here is a list of the usual options to consider when configuring a volume.
¶ --compress, -z
Compress file data during the transfert.
From rsync manual :
With this option, rsync compresses the file data as it is sent to the destination machine, which reduces the amount of data be‐ing transmitted -- something that is useful over a slow connection.
Rsync supports multiple compression methods and will choose one for you unless you force the choice using the --compress-choice (--zc) option.
Run rsync --version to see the default compress list compiled into your version.
When both sides of the transfer are at least 3.2.0, rsync chooses the first algorithm in the client's list of choices that is also in the server's list of choices. If no common compress choice is found, rsync exits with an error. If the remote rsync is too old to support checksum negotiation, its list is assumed to be "zlib".
The default order can be customized by setting the environment variable RSYNC_COMPRESS_LIST to a space-separated list of acceptable compression names. If the string contains a "&" character, it is separated into the "client string & server string", otherwise the same string applies to both. If the string (or string portion) contains no non-whitespace characters, the default compress list is used. Any unknown compression names are discarded from the list, but a list with only invalid names results in a failed negotiation.
There are some older rsync versions that were configured to reject a -z option and require the use of -zz because their compression library was not compatible with the default zlib compression method. You can usually ignore this weirdness unless the rsync server complains and tells you to specify -zz.
This option can prevent rsync from working when running on a Synology volume and processing relatively big compressed files in emission or reception. If you encounter this kind of issue, put this option separately on each volume that can handle it or fine-tune using
--compress-choice=STRor--skip-compress=LISTto change the compression algorithm and exclude some file extensions from being compressed.
On high speed network links, it may be longer compressing the files than transmitting them directly.
Depending on the type of transmitted data, processors and bandwidths, it may be efficient to transmit the data compressed. Check all available options to finetune your compression, like
--compress-level,--skip-compress,-compress-choice(in newer rsync version)
¶ --progress
Show progress during transfer
From rsync manual :
This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. With a modern rsync this is the same as specifying --info=flist2,name,progress, but any user-supplied settings for those info flags takes precedence (e.g. --info=flist0 --progress).
While rsync is transferring a regular file, it updates a progress line that looks like this:
782448 63% 110.64kB/s 0:00:04In this example, the receiver has reconstructed 782448 bytes or 63% of the sender's file, which is being reconstructed at a rate of 110.64 kilobytes per second, and the transfer will finish in 4 seconds if the current rate is maintained until the end.
These statistics can be misleading if rsync's delta-transfer algorithm is in use. For example, if the sender's file consists of the basis file followed by additional data, the reported rate will probably drop dramatically when the receiver gets to the literal data, and the transfer will probably take much longer to finish than the receiver estimated as it was finishing the matched part of the file.
When the file transfer finishes, rsync replaces the progress line with a summary line that looks like this:
1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396)In this example, the file was 1,238,099 bytes long in total, the average rate of transfer for the whole file was 146.38 kilobytes per second over the 8 seconds that it took to complete, it was the 5th transfer of a regular file during the current rsync session, and there are 169 more files for the receiver to check (to see if they are up-to-date or not) remaining out of the 396 total files in the file-list.
In an incremental recursion scan, rsync won't know the total number of files in the file-list until it reaches the ends of the scan, but since it starts to transfer files during the scan, it will display a line with the text "ir-chk" (for incremental recursion check) instead of "to-chk" until the point that it knows the full size of the list, at which point it will switch to using "to-chk". Thus, seeing "ir-chk" lets you know that the total count of files in the file list is still going to increase (and each time it does, the count of files left to check will increase by the number of the files added to the list).
This option helps the administrators who have access to the running rsync processes on the hub machine to debug the file transfers and their speed
¶ LINKS
Here is a list of the most used options for configuring a link.
¶ --ignore-existing
Skip updating files that exist on receiver
From rsync manual :
Rsync manual: This tells rsync to skip updating files that already exist on the destination (this does not ignore existing directories, or nothing would get done). See also --existing.
This option is a transfer rule, not an exclude, so it doesn't affect the data that goes into the file-lists, and thus it doesn't affect deletions. It just limits the files that the receiver requests to be transferred.
This option can be useful for those doing backups using the --link-dest option when they need to continue a backup run that got interrupted. Since a --link-dest run is copied into a new directory hierarchy (when it is used properly), using --ignore-existing will ensure that the already-handled files don't get tweaked (which avoids a change in permissions on the hard-linked files). This does mean that this option is only looking at the existing files in the destination hierarchy itself.
This option prevents propagating unwanted changes made to the previously synchronized files (from this volume and from other volumes) and provides a good protection against unwanted propagations such as if a ransomware is running on one of the sites
¶ --delete
Delete extraneous files from dest dirs
From rsync manual :
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 the transfer are also excluded from being deleted unless you use the --delete-excluded option or mark the rules as only matching on the sending side (see the include/exclude modifiers in the FILTER RULES section).
Prior to rsync 2.6.7, this option would have no effect unless --recursive was enabled. Beginning with 2.6.7, deletions will also occur when --dirs (-d) is enabled, but only for directories whose contents are being copied.
This option can be dangerous if used incorrectly! It is a very good idea to first try a run using the --dry-run (-n) option to see what files are going to be deleted.
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 from causing a massive deletion of files on the destination. You can override this with the --ig‐ nore-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 choose the --delete-during algorithm when talking to rsync 3.0.0 or newer, or the --delete-before algorithm when talking to an older rsync. See also --delete-delay and --delete-after.
As the rsync manuel writes, use this option with extrem care as it could destroy unwanted data, a good way of testing it is to use the
--dry-runoption to check the changes before production use.
This option can be very useful for uni-directional propagations (from 1 source volume to N targets). It allows the source volume to clean, delete, rename files so the changes will be propagated to the target volumes which get an exact copy of the source
¶ --dry-run, -n
Perform a trial run with no changes made
From rsync manual :
This makes rsync perform a trial run that doesn't make any changes (and produces mostly the same output as a real run). It is most commonly used in combination with the --verbose, -v and/or --itemize-changes, -i options to see what an rsync command is going to do before one actually runs it.
The output of --itemize-changes is supposed to be exactly the same on a dry run and a subsequent real run (barring intentional trickery and system call failures); if it isn't, that's a bug. Other output should be mostly unchanged, but may differ in some areas. Notably, a dry run does not send the actual data for file transfers, so --progress has no effect, the "bytes sent", "bytes received", "literal data", and "matched data" statistics are too small, and the "speedup" value is equivalent to a run where no file transfers were needed.
This option is useful to check the results before activating a link, to know that everything runs fine before starting the real transfers. Once checked and approved, you can safely remove this option to start the real transfers.
¶ --backup, -b
Make backups (see --suffix & --backup-dir)
From rsync manual :
With this option, preexisting destination files are 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 --backup-dir and --suffix options.
Note that if you don't specify --backup-dir, (1) the --omit-dir-times option will be forced on, and (2) if --delete is also in effect (without --delete-excluded), rsync will add a "protect" filter-rule for the backup suffix to the end of all your existing excludes (e.g. -f "P *~"). This will prevent previously backed-up files from being deleted. Note that if you are supplying your own filter rules, you may need to manually insert your own exclude/protect rule 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 inclusion/exclusion of *, the auto-added rule would never be reached).
¶ --links, -l
Copy symlinks as symlinks
From rsync manual :
When symlinks are encountered, recreate the symlink on the destination.
This option recreates the symbolic link on the destination instead of copiing as if the symlinks were regular files (thus duplicating the linked file). It is a safe option to use, in case your users want to use symlinks. Windows filesystem don't support symlinks so mounting a server that have symlink will show to them regular files.
¶ Next
- Read the Rsync-Filters section for filter-specific options
- Read the html version of the rsync manpage from the official rsync site
- Read the rsync manual page from your system:
man rsync