Synchronization

This configuration page contains options that influence the behavior of the rsync(1) command that is used to synchronize remote shares with local copies and vice versa. It is only available, if rsync(1) is installed on your system. It is recommended that you read the manual page before you use the synchronization feature the first time. However, safe settings are pre-defined. You will do no harm, if you start right away.

The "Synchronization" configuration page

Basic Settings

Default Destination

Synchronization prefix

This is the base folder below which Smb4K stores the transferred data using rsync(1). It can be changed by using the URL requester (Click the button with the folder icon.) or by directly entering the new path into the text box. Path variables like $HOME are recognized.

For each share you synchronize, a new subdirectory below this prefix will be generated. If you want to synchronize the contents of a share to a different folder, you can define it in the synchronization dialog.

Default: $HOME/smb4k_sync/

Behavior

Archive mode

Option: -a/--archive, same as -rlptgoD (no -H)

Switch the archive mode on. This is a quick way of saying you want recursion and want to preserve almost everything. Note that -a does not preserve hardlinks, because finding multiply-linked files is expensive. You must separately specify -H.

Default: selected

Recurse into subdirectories

Option: -r/--recursive

Recurse into subdirectories.

Default: selected

Use relative path names

Option: -R/--relative

Use relative path names. This means that the full path names specified on the command line are sent to the server rather than just the last parts of the file names.

Default: not selected

Do not send implied directories

Option: --no-implied-dirs

This option affects the default behavior of the --relative option. When it is specified, the attributes of the implied directories from the source names are not included in the transfer. This means that the corresponding path elements on the destination system are left unchanged if they exist, and any missing implied directories are created with default attributes. This even allows these implied path elements to have big differences, such as being a symlink to a folder on one side of the transfer, and a real folder on the other side.

For further information you ought to read the manual page.

Default: not selected

Transfer directories without recursing

Option: -d/--dirs

Tell the sending side to include any directories that are encountered. Unlike --recursive, a folders contents is not copied unless the folder name specified is "." or ends with a trailing slash (e.g. ".", "dir/.", "dir/", etc.). Without this option or the --recursive option, rsync(1) will skip all directories it encounters (and output a message to that effect for each one). If you specify both --dirs and --recursive, --recursive takes precedence.

Default: not selected

Backup

Make backups

Option: -b/--backups

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 implied, and (2) if --delete is also in effect (without --delete-excluded), rsync(1) 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).

Default: not selected

Backup suffix

Option: --suffix=SUFFIX

This option allows you to override the default backup suffix used with the --backup option. The default suffix is a ~ if no --backup-dir was specified, otherwise it is an empty string.

This option is only available if you ticked the Make backups option above.

Default: not selected; SUFFIX: ~

Backup directory

Option: --backup-dir=DIR

In combination with the --backup option, this tells rsync to store all backups in the specified folder. This is very useful for incremental backups. You can additionally specify a backup suffix using the --suffix option (otherwise the files backed up in the specified folder will keep their original filenames).

This option is only available if you ticked the Make backups option above.

Default: not selected; DIR: $HOME

File Handling

General

Update files

Option: -u/--update

This forces rsync(1) to skip any files that exist on the destination and have a modification time that is newer than the one of 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.)

Default: selected

Update files in place

Option: --inplace

This causes rsync(1) not to create a new copy of the file and then move it into place. Instead rsync(1) will overwrite the existing file, meaning that the rsync algorithm cannot accomplish the full amount of network reduction it might be able to otherwise. One exception to this is if you combine the option with --backup, since rsync(1) is smart enough to use the backup file as the basis file for the transfer.

For further information you ought to read the manual page.

Default: not selected

Handle sparse files efficiently

Option: -S/--sparse

Try to handle sparse files efficiently so they take up less space on the destination. Conflicts with --inplace because it's not possible to overwrite data in a sparse fashion.

Note

Do not use this option when the destination is a Solaris™ "tmpfs" file system. It doesn't seem to handle seeks over null regions correctly and ends up corrupting the files.

Default: not selected

Copy files whole (no rsync algorithm)

Option: -W/--whole-file

With this option the incremental rsync(1) 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 destination machines is higher than the bandwidth to disk (especially when the "disk" is actually a networked file system). This is the default when both the source and destination are specified as local paths.

Default: not selected

Only update files that already exist

Option: --existing/--ignore-non-existing

This tells rsync(1) to skip updating files that do not exist yet on the destination. If this option is combined with the --ignore-existing option, no files will be updated (which can be useful if all you want to do is to delete missing files).

Default: not selected

Ignore files that already exist

Option: --ignore-existing

This tells rsync(1) to skip updating files that already exist on the destination. See also --ignore-non-existing.

Default: not selected

Links

Preserve symlinks

Option: -l/--links

Copy symlinks as symlinks.

Default: selected

Transform symlinks

Option: -L/--copy-links

When symlinks are encountered, the item that they point to is copied, rather than the symlink.

Default: not selected

Transform unsafe symlinks

Option: --copy-unsafe-links

Only transform "unsafe" symlinks. This means if a symlink is encountered that is pointing outside the copied tree, the referenced item is transferred rather than the symlink itself.

Default: not selected

Ignore unsafe symlinks

Option: --safe-links

This tells rsync(1) to ignore any symbolic links which point outside the copied tree. All absolute symlinks are also ignored. Using this option in conjunction with --relative may give unexpected results.

Default: not selected

Munge symlinks

Option: -H/--munge-links

This tells rsync(1) to (1) modify all symlinks on the receiving side in a way that makes them unusable but recoverable, or (2) to unmunge symlinks on the sending side that had been stored in a munged state. This is useful if you do not quite trust the source of the data to not try to slip in a symlink to an unexpected place. For further information on this argument, please see the manual page of rsync(1).

Default: not selected

Preserve hard links

Option: -H/--hard-links

This tells rsync(1) to look for hard-linked files in the transfer and link together the corresponding files on the receiving side. Without this option, hard-linked files in the transfer are treated as though they were separate files.

Note that rsync(1) can only detect hard links if both parts of the link are in the list of files being sent.

Default: not selected

Copy directory symlinks

Option: -k/--copy-dirlinks

This option causes the sending side to treat a symlink to a directory as though it were a real directory. This is useful if you don’t want symlinks to non-directories to be affected, as they would be using --copy-links.

Default: not selected

Keep directory symlinks

Option: -K/--keep-dirlinks

This option causes the receiving side to treat a symlink to a directory as though it were a real directory, but only if it matches a real directory from the sender. Without this option, the receiver's symlink would be deleted and replaced with a real directory.

Default: not selected

Permissions, etc.

Preserve permissions

Option: -p/--perms

This option causes the receiving side to set the destination permissions to be the same as the source permissions.

Default: selected

Preserve owner

Option: -o/--owner

This option causes rsync(1) to set the owner of the destination file to be the same as the one of the source file. By default, the preservation is done by name, but may fall back to using the ID number in some circumstances (see the --numeric-ids option for a full discussion). This option has no effect if the receiving rsync(1) is not run as the super user and --super is not specified.

Default: selected

Preserve group

Option: -g/--group

This option causes rsync(1) to set the group of the destination file to be the same as the on of the source file. If the receiving program is not running as the super-user (or with the --no-super option), only groups that the receiver is a member of will be preserved.

Default: selected

Preserve device and special files

Option: -D/--devices --specials

This option causes rsync(1) to transfer character and block device files as well as special files (such as named sockets and fifos) to the remote system. This option has no effect if the receiving side is not run as the super user and --super is not specified.

Default: selected

Preserve times

Option: -t/--times

This tells rsync(1) to transfer modification times along with the files and update them on the remote system.

Default: selected

Omit directories when preserving times

Option: -O/--omit-dir-times

This tells rsync(1) to omit directories when it is preserving modification times (see --times).

Default: not selected

File Transfer

Compression

Compress data during transfer

Option: -z/--compress

Compress file data during the transfer.

Default: not selected

Set compression level

Explicitly set the compression level to use (--compress-level=NUM). If NUM is non-zero, the --compress argument is implied.

Skip compression for following file suffixes

Overwrite the list of file suffixes that will not be compressed (--skip-compress=LIST). The LIST should be one or more file suffixes (without the dot) separated by slashes. You may specify an empty string to indicate that no file should be skipped. The default list of suffixes will be replaced by this list. For further details, see the manual page of rsync.

Files

Do not transfer any file smaller than

Option: --min-size=NUM

This tells rsync(1) to avoid transferring any file that is smaller than the specified SIZE, which can help in not transferring small, junk files.

Default: not selected; NUM: 0 kB

Do not transfer any file larger than

Option: --max-size=NUM

This tells rsync(1) to avoid transferring any file that is larger than the specified SIZE.

Default: not selected; NUM: 0 kB

Keep partially transferred files

Option: --partial

By default, rsync(1) will delete any partially transferred file if the transfer is interrupted. In some circumstances it is more desirable to keep partially transferred files. Using the --partial option tells rsync(1) to keep the partial file which should make a subsequent transfer of the rest of the file much faster.

Default: not selected

Put partially transferred files into

Option: --partial-dir=DIR

A better way to keep partial files than the --partial option is to specify a folder DIR that will be used to hold the partial data (instead of writing it out to the destination file). On the next transfer, rsync(1) will use a file found in this folder as data to speed up the resumption of the transfer and then delete it after it has served its purpose. Before you tick this option, you should read the manual page.

Default: not selected; DIR: $HOME

Miscellaneous

Set bandwidth limit:

Option: --bwlimit=RATE

Set the maximum data transfer rate in kilobytes per second.

Default: not selected; RATE: 0 KiB/s

File Deletion

Files & Directories

Remove synchronized source files

Option: --remove-source-files

This tells rsync(1) to remove from the sending side the files (meaning non-directories) that are a part of the transfer and have been successfully duplicated on the receiving side.

Default: not selected

Delete extraneous files

Option: --delete

This tells rsync(1) 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(1) to send the whole folder (e.g. "dir" or "dir/") without using a wildcard for the folders contents (e.g. "dir/*") since the wildcard is expanded by the shell and rsync(1) thus gets a request to transfer individual files, not the files' parent folder. Files that are excluded from 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.

Default: not selected

Delete files before transfer

Option: --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.

Default: not selected

Delete files after transfer

Option: --delete-after

Request that the file deletions on the receiving side be done after the transfer has completed.

Default: not selected

Delete files during transfer

Option: --delete-during

Request that the file deletions on the receiving side be done incrementally as the transfer happens. This is a faster method than choosing the before- or after-transfer algorithm, but it is only supported beginning with rsync(1) version 2.6.4.

Default: not selected

Delete excluded files

Option: --delete-excluded

In addition to deleting the files on the receiving side that are not on the sending side, this tells rsync(1) to also delete any files on the receiving side that are excluded (see --exclude).

Default: not selected

Delete even if I/O errors occur

Option: --ignore-errors

Tells --delete to go ahead and delete files even when there are I/O errors.

Default: not selected

Force deletion of non-void directories

Option: --force

This option tells rsync(1) to delete a non-empty folder when it is to be replaced by a non-folder. This is only relevant if deletions are not active (see --delete).

Default: not selected

Restrictions

Do not delete more than this many files

Option: --max-delete=NUM

This tells rsync(1) not to delete more than NUM files or directories (NUM must be non-zero). This is useful when mirroring very large trees to prevent disasters.

Default: not selected; NUM: 0

Filtering

General

Auto-ignore files in the same way CVS does

Option: -C/--cvs-exclude

This is a useful shorthand for excluding a broad range of files that you often don't want to transfer between systems. It uses the same algorithm that CVS uses to determine if a file should be ignored.

Default: not selected

Exclude files matching this pattern

Option: --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.

Default: not selected; PATTERN: empty

Read exclude patterns from

Option: --exclude-from=FILE

This option is related to the --exclude option, but it specifies a FILE that contains exclude patterns (one per line). Blank lines in the file and lines starting with ';' or '#' are ignored. You have to choose an existing file to make this option work.

Default: not selected; FILE: $HOME/exclude.txt

Include files matching this pattern

Option: --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.

Default: not selected; PATTERN: empty

Read include patterns from

Option: --include-from=FILE

This option is related to the --include option, but it specifies a FILE that contains include patterns (one per line). Blank lines in the file and lines starting with ';' or '#' are ignored. You have to choose an existing file to make this option work.

Default: not selected; FILE: $HOME/include.txt

Filter Rules

Custom filter rules

Option: -f/--filter=RULE

You can define one or more filter rules here. Each rule has to be prefixed with the --filter= or -f option string, because the contents of the text box will be passed to the rsync(1) command AS IS.

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 --filter options as you like to build up the list of files to exclude.

See the FILTER RULES section of the manual page for detailed information on this option.

Default: empty

Use --filter='dir-merge /.rsync-filter' filter rule

Option: -F

This option tells rsync(1) to look for per-folder .rsync-filter files that have been sprinkled through the hierarchy and use their rules to filter the files in the transfer.

See the FILTER RULES section of the manual page for detailed information on how this option works.

Default: not selected

Use --filter='exclude .rsync-filter' filter rule

Option: -FF

This option filters out the .rsync-filter files themselves from the transfer.

See the FILTER RULES section of the manual page for detailed information on how this option works.

Default: not selected

Miscellaneous

Checksums

Force fixed checksum block size

Option: -B/--block-size=SIZE

This forces the block size used in the rsync algorithm to a fixed value. It is normally selected based on the size of each file being updated. See the technical report for details.

Default: not selected; SIZE: 0

Set block/file checksum seed

Option: --checksum-seed=NUM

Set the MD4 checksum seed to the integer NUM. This 4 byte checksum seed is included in each block and file MD4 checksum calculation. By default the checksum seed is generated by the server and defaults to the current time(). This option is used to set a specific checksum seed, which is useful for applications that want repeatable block and file checksums, or in the case where the user wants a more random checksum seed. Note that setting NUM to 0 causes rsync to use the default of time() for checksum seed.

Default: not selected; NUM: 0

Skip files based on checksum

Option: -c/--checksum

This forces the sender to checksum every regular file using a 128-bit MD4 checksum. It does this during the initial file system scan as it builds the list of all available files. The receiver then checksums its version of each file (if it exists and it has the same size as its sender-side counterpart) in order to decide which files need to be updated: files with either a changed size or a changed checksum are selected for transfer. Since this whole-file checksumming of all files on both sides of the connection occurs in addition to the automatic checksum verifications that occur during a file's transfer, this option can be quite slow.

Default: not selected

General

Do not cross file system boundaries

Option: -x/--one-file-system

This tells rsync(1) to avoid crossing a file system boundary when recursing. This does not limit the user's ability to specify items to copy from multiple file systems, just rsync(1)'s recursion through the hierarchy of each folder that the user specified, and also the analogous recursion on the receiving side during deletion. Also keep in mind that rsync(1) treats a "bind" mount to the same device as being on the same file system.

Default: not selected

Delay updates until the end of transfer

Option: --delay-updates

This option puts the temporary file from each updated file into a holding folder until the end of the transfer, at which time all the files are renamed into place in rapid succession.

It is strongly recommended that you read the manual page before using this option.

Default: not selected