SoFunction
Updated on 2025-05-21

Detailed explanation and example of rsync command

1. Core functions and basic syntax of rsync command

1. Core functions

  • Incremental synchronization: Only transfer the difference between the source file and the target file, greatly reducing the amount of data transmission.
  • Cross-platform support: Suitable for servers connected to local file systems, remote SSH or rsync protocol.
  • Metadata retention: Supports preservation of file permissions, timestamps, symbolic links, hard links and other attributes.
  • Flexible filtering: Synchronous files can be filtered by regular expressions, exclusion/inclusion rules.
  • Transmission optimization: Support compression (-z), bandwidth limitation (--bwlimit), breakpoint continuous transmission (need to cooperate with tools), etc.

2. Basic syntax

# Local synchronization syntaxrsync [Options] [Source path] [Target path]
# Remote synchronization syntax (via the SSH protocol)rsync [Options] [Source path] [user@]Remote host:[Target path]
rsync [Options] [user@]Remote host:[Source path] [Target path]
# Remote synchronization syntax (through rsync daemon protocol)rsync [Options] rsync://Remote host模块名/[Target path]

Core parameter classification：

  • Mode parameters：
    -a(archiving mode, equivalent to-rlptgoD, keep all metadata and synchronize recursively)
    -n/--dry-run(Simulate synchronization, do not actually transfer files, used for testing)
    -v/-vv(Show detailed/more detailed synchronization process)
  • Transmission control：
    -z(Compress data transmission to improve network transmission efficiency)
    --delete(Delete files that do not exist in the target source to achieve mirror synchronization)
    --ignore-errors(Ignore file deletion/read errors and continue synchronization)
  • Filtering rules：
    --exclude="Mode"(Exclude files/directories that match the pattern)
    --include="Mode"(Forced to include files/directories that match the pattern)
  • Performance optimization：
    --bwlimit=KB/s(Limit transmission bandwidth, such as--bwlimit=1024）
    -P(equivalent to--partial --progress, display progress and retain some of the transferred files)
    -D(Retain device files and special files)

2. Common use cases and command examples

1. Local file synchronization

Scenario: Synchronize the local directory /data/source to /data/backup, retain all attributes and display the detailed process.

rsync -av /data/source/ /data/backup/

The end slash / represents the content in the synchronized directory and will be automatically created when the target directory does not exist.

If the source path does not have a slash (such as /data/source), the target directory will create a subdirectory named source.

2. Remote synchronization (via SSH)

Scenario 1: Upload local files to remote server

rsync -avz /local/ user@:/remote/path/

-z Compressed files, suitable for network transmission; remote paths require users to have permission to write.

Scenario 2: Download the file from the remote server

rsync -avz user@:/remote/ /local/path/

Scenario 3: Cross-server synchronization (no local transit required)

rsync -avz -e "ssh -p 2222" user1@server1:/source/ user2@server2:/dest/

-e Specifies the use of SSH protocol and port (default 22), and supports encrypted transmission.

3. Synchronize incremental backup and mirroring

Scene 1: Incremental backup (only update the changed files, delete unnecessary files in the target)

rsync -av --delete /source/ /backup/

--deleteIt will strictly align the target and source and be used with caution in important data! It is recommended to use it first--dry-runSimulation.

Scene 2: Keep incremental backups of historical versions (use hard links to save space)

rsync -av --link-dest=/backup/last/ /source/ /backup/current/

--link-destLet the new backup share the same file from the last backup, and only the difference part is stored.

4. Exclude/Include specific files

Scene: Exclude log files and temporary files when synchronizing directories

rsync -av --exclude="*.log" --exclude="tmp/" /data/ /backup/

Supports wildcard characters (*、?) and directory paths (such astmp/means to exclude the entire directory).

Complex filtering can be used--exclude-from=file, write an exclusion pattern per line in the file:

rsync -av --exclude-from= /source/ /dest/

5. Performance optimization and advanced options

Speed ​​limit transmission(Avoid affecting bandwidth):

rsync -avz --bwlimit=2048 /large_data/ remote:/storage/

Checksum mode(Skip the timestamp check to ensure that the file content is consistent):

rsync -av --checksum /source/ /dest/

Keep symbolic links(Remained by default. If you need to follow the link to synchronize the actual file, add--follow-symlinks）：

rsync -av --follow-symlinks /source/ /dest/

3. Frequently Asked Questions and Solutions

1. Permission issue: rsync: failed to open dir: Permission denied

reason: Source/destination directory has no read/write permissions, or remote user permissions are insufficient.

solve：

Local synchronization: UsesudoElevate permissions, or ensure that users have corresponding permissions to the path.

Remote synchronization: Check whether the remote user is the directory owner, or usessh-keygenConfigure password-free login to avoid permission interruption.

2. Delete the file by mistake: --delete Accidentally delete the target file

prevention：

Always use it first--dry-runSimulate synchronization and confirm that there is no error deletion operation in the output:

rsync -av --delete --dry-run /source/ /dest/

Back up the target directory first, or use the important data--delete-after(Transfer new files first and then delete them to reduce risks).

3. Transmission interruption: Network instability leads to synchronization failure

solve：

use-P（--partial) Keep temporary files that have not completed transmission and support breakpoint continuous transmission:

rsync -avP /large_file.iso remote:/dest/

If it is interrupted frequently, it can be matchedrsync + nohuporscreenKeep the session persistent.

4. File conflict: Files with the same name as the source and the target but different contents

Phenomenon：rsyncBy default, overwriting the target file with the source file, which may lead to data loss.

solve：

use--compare-dest=Reference directoryComparing three-party files, the latest version is reserved first (requiresrsync >= 3.1.0）：

rsync -av --compare-dest=/reference/ /source/ /dest/

Manually check conflicting files (by--itemize-changesDetailed differences in output):

bash

rsync -av --itemize-changes /source/ /dest/

5. Symbolic link exception: link invalid or pointing error after synchronization

reason:defaultrsyncKeep the symbolic link itself and not follow the file it points to.

solve：

If you need to keep the link (recommended): No additional parameters are required, the default behavior is correct.

If you need to synchronize the actual file pointed to by the link: Add--follow-symlinks, but may cause loop link errors.

6. Metadata loss: Permissions/timestamps are not properly retained

reason: Archive mode is not used-a, or remote server restricts permissions to write.

solve：

Always use-aOr explicitly add-rltp(Recursive, reserved symbolic links, timestamps, permissions).

When syncing remotely, ensure that the target user haschmod/chownPermissions (such as using root user orsudo）。

7. Invalid compression: -z Not reduced transmission

reason: The transferred file is already in a compressed format (such as.zip、.), compression actually increases overhead.

solve: Used for binary or text files-z, use compressed files instead-z0(minimum compression) or directly disabled-z。

8. Network connection timeout: The remote host is unreachable

reason: SSH port error, firewall blocks connection, host name resolution failed.

solve：

Check the remote host IP/port (ping orssh user@ -p port）。

Add to-e "ssh -o ConnectTimeout=10"Limit connection timeout:

rsync -avz -e "ssh -o ConnectTimeout=10" /local/ remote:/dest/

4. Summary of best practices

Test priority: Use complex synchronization tasks first--dry-runSimulate, confirm that the output is correct before executing.

Back up key data: Manually backup target data (especially including--deleteoperation).

Logging:pass--log-file=Record the synchronization process to facilitate subsequent audits or troubleshooting:

rsync -av --delete --log-file= /source/ /dest/

Version control: Combined--link-destImplement versioned backup based on hard links to save storage space.

By mastering the above usage, you can efficiently use rsync to complete local/remote file synchronization, incremental backup, server mirroring and other tasks, while avoiding common traps. In actual use, it is recommended to adjust parameters according to the specific scenario, and if necessary, please refer to the official documents (man rsync) Get the full description of options.