Table of Contents
Basic `rsync` Concepts
rsync is a fast, incremental file-copying tool commonly used for backups. It compares source and destination and transfers only differences, which makes repeated backups efficient.
In this chapter, the focus is on using rsync as a backup tool—not as a general-purpose copy command.
Key ideas when using rsync for backup:
- It can preserve permissions, ownership, timestamps, links, and more.
- It can work locally (disk to disk) or over the network (via SSH or
rsyncdaemon). - It can delete files on the destination that were removed from the source (to keep them in sync).
- It can create backup copies of changed/removed files instead of deleting them outright.
Basic Command Structure for Backups
The general syntax you will use most often:
rsync [OPTIONS] SOURCE DESTINATIONFor a simple local backup:
rsync -av /home/alice/Documents/ /mnt/backup/documents/Common options in backup use-cases:
-a— archive mode (recursive, preserve permissions, timestamps, etc.)-v— verbose (show what is happening)-h— human-readable numbers (e.g.1.2Minstead of1234567)-n— dry run (shows what would be done, changes nothing)
Example with dry run:
rsync -avhn /home/alice/Documents/ /mnt/backup/documents/
Always experiment with -n before running a new backup command for real.
Trailing Slash Behavior (Very Important)
When backing up directories, the presence or absence of a trailing / on the source changes what gets copied.
- With trailing
/: copy the contents of the directory. - Without trailing
/: copy the directory itself, including its name.
Example:
# 1. Copies the CONTENTS of Documents into /mnt/backup/
rsync -av /home/alice/Documents/ /mnt/backup/
# Result: /mnt/backup/ contains files like report.txt, notes/, etc.
# 2. Copies the Documents directory ITSELF into /mnt/backup/
rsync -av /home/alice/Documents /mnt/backup/
# Result: /mnt/backup/Documents/ contains those files.
For most backup scenarios, you will want the trailing / on the source to copy just the contents.
Preserving Permissions and Ownership
For backups that you might restore on the same system (or similar systems), it is usually important to preserve metadata:
- file ownership
- permissions
- timestamps
- symbolic links
- device files and special files (for system backups)
Archive mode -a bundles many preservation options:
- Equivalent to:
-rlptgoD -r— recursive-l— preserve symlinks-p— preserve permissions-t— preserve modification times-g— preserve group-o— preserve owner (needs root)-D— preserve device and special files (needs root)
Example for a user’s home backup:
rsync -avh /home/alice/ /mnt/backup/home-alice/If you are running as root for system-level backups:
sudo rsync -aAXHv / /mnt/backup/system/New options here:
-A— preserve ACLs (if used on your system)-X— preserve extended attributes
You generally include -A and -X only when you know your filesystem uses them.
Using `rsync` Over SSH (Remote Backups)
One of the strengths of rsync is backing up over the network using SSH.
Basic pattern:
rsync [OPTIONS] SOURCE user@remotehost:DEST
rsync [OPTIONS] user@remotehost:SOURCE DESTExamples:
Local → Remote backup
rsync -avh --delete /home/alice/ alice@backup-server:/backups/alice/
This will connect via SSH as user alice to backup-server and synchronize /home/alice/ to /backups/alice/ on the remote host.
Remote → Local backup (pulling backup)
rsync -avh alice@backup-server:/backups/alice/ /mnt/backup/alice/
To use SSH keys instead of passwords (recommended for automated backups), you’ll combine rsync with SSH key authentication (covered in SSH chapters). To specify a custom SSH port or options:
rsync -avh -e "ssh -p 2222" /home/alice/ alice@backup-server:/backups/alice/
Here -e sets the remote shell command used by rsync (in this case, ssh with a custom port).
Keeping Backups in Sync with `--delete`
When using rsync for backups where the destination should exactly match the source, you can use:
--delete— delete files on the destination that no longer exist on the source.
Example:
rsync -avh --delete /home/alice/ /mnt/backup/home-alice/This is powerful but dangerous:
- If you mistakenly point to the wrong destination, you can delete valid data.
- Always test with
-n(dry run) before using--delete, especially when you modify paths.
Example with dry run:
rsync -avhn --delete /home/alice/ /mnt/backup/home-alice/Check the output carefully to confirm it will delete only what you expect.
There are related options:
--delete-before— delete before transfer (default in many cases).--delete-after— delete after transfer.--delete-excluded— also delete files from destination that match--excludepatterns.
These are usually only needed for fine-tuning; for most backups, plain --delete is enough.
Excluding Files and Directories
Often, you do not want to back up everything. You may wish to exclude:
- cache directories
- temporary files
- large unimportant folders (e.g.,
Downloads) - build artifacts
rsync has powerful exclude options:
--exclude=PATTERN— skip files or directories matching a pattern.--exclude-from=FILE— read exclude patterns from a file.
Examples:
# Exclude a single directory by name
rsync -avh --exclude="Downloads/" /home/alice/ /mnt/backup/home-alice/
# Exclude multiple patterns
rsync -avh \
--exclude="Downloads/" \
--exclude=".cache/" \
/home/alice/ /mnt/backup/home-alice/Using an exclude file:
Create /home/alice/.rsync-excludes:
Downloads/
.cache/
*.iso
*.tmpThen use:
rsync -avh --exclude-from=/home/alice/.rsync-excludes \
/home/alice/ /mnt/backup/home-alice/
Patterns apply relative to the source directory. Test with -n to ensure important files aren’t excluded accidentally.
Creating “Versioned” Backups with `--backup`
Sometimes you want the destination to stay mostly in sync, but you don’t want rsync to simply overwrite or delete older versions of files. The --backup option can help:
--backup— whenrsyncupdates or deletes a file on the destination, it first saves a backup copy.--backup-dir=DIR— store backup copies in a separate directory.
A simple pattern:
rsync -avh --delete \
--backup \
--backup-dir=/mnt/backup/home-alice_old-$(date +%F) \
/home/alice/ /mnt/backup/home-alice/What happens:
- New/changed files are synchronized to
/mnt/backup/home-alice/. - Before overwriting or deleting a file there, the old version is moved into
/mnt/backup/home-alice_old-YYYY-MM-DD/. - Over time, you accumulate dated directories that contain only changed/removed files.
This creates a form of “historical” backups without copying everything each time.
Notes:
$(date +%F)expands toYYYY-MM-DD.- This can consume substantial space over time; combine with cleanup policies (see backup automation topics).
Common `rsync` Backup Examples
1. Local user home backup to external drive
Assume an external drive mounted at /mnt/backup:
rsync -avh \
--exclude=".cache/" \
--exclude="Downloads/" \
/home/alice/ /mnt/backup/home-alice/2. Nightly remote backup via SSH (pull)
From the backup server, pulling data from client workstation1:
rsync -avh --delete \
workstation1:/home/alice/ /backups/workstation1/alice/
Combine with cron to run nightly (covered in scheduling chapters).
3. System backup (root filesystem) to another disk
Be very careful with device names and mount points.
Mount your backup disk at /mnt/sysbackup, then:
sudo rsync -aAXHv \
--exclude={"/dev/*","/proc/*","/sys/*","/tmp/*","/run/*","/mnt/*","/media/*","/lost+found"} \
/ /mnt/sysbackup/
This excludes virtual and temporary filesystems that should not be backed up with rsync.
Performance and Network Considerations
For larger backups, performance tuning can be helpful.
Useful options:
-z— compress data during transfer (good for slow networks, not always useful on LAN).--progress— show per-file progress.--info=progress2— overall progress of the whole transfer (on newerrsync).
Example:
rsync -avhz --info=progress2 /home/alice/ alice@backup-server:/backups/alice/If network bandwidth is limited:
- Use
--bwlimit=KBPSto limit transfer speed.
Example (limit to 2 MB/s):
rsync -avh --bwlimit=2000 /home/alice/ alice@backup-server:/backups/alice/Using `rsync` Safely
Because rsync can delete and overwrite data, safe usage practices are essential:
- Always start with a dry run
Add-nto see what changes would be made. - Double-check source and destination order
The direction matters. A common disaster is swapping them and copying “empty” over “full.” - Be very careful with
--delete
Use it only after verifying with a dry run, especially in scripts. - Protect remote destinations
On remote backup servers, use file permissions, dedicated users, and possibly restricted SSH keys. - Test restores periodically
A backup is only useful if it can be restored. Try restoring a test subset of your data to confirm.
Basic Restore Using `rsync`
Using rsync for restore is conceptually similar to backup, just reverse the source and destination.
Examples:
Restoring a directory from backup drive
rsync -avh /mnt/backup/home-alice/Documents/ /home/alice/Documents/Restoring a single file
You can use rsync or just cp. Using rsync:
rsync -avh /mnt/backup/home-alice/Documents/report.odt \
/home/alice/Documents/report.odtRestoring from versioned backups
If you used --backup-dir with dates, pick the dated directory that contains the older version:
rsync -avh /mnt/backup/home-alice_old-2025-01-10/report.odt \
/home/alice/Documents/report.odt
Again, test partial restores before relying on rsync for full system restoration, especially for root filesystem backups.
Inspecting What Changed
rsync can show only which files differ without copying them, useful for checking what would be backed up.
Use:
rsync -avhn --delete /home/alice/ /mnt/backup/home-alice/
-n ensures nothing is actually transferred; you just see the file list.
If you want a simplified list of changed files, add --out-format:
rsync -avhn --delete \
--out-format="%o %n" \
/home/alice/ /mnt/backup/home-alice/
Where %o is the operation (e.g., send, del) and %n is the filename.
Summary of Common Options for Backups
A compact reference for backup use:
-a— archive mode (recursive, preserve attributes)-v— verbose-h— human-readable sizes-n— dry run (test only)-z— compress data during transfer--delete— delete destination files not present in source--exclude=PATTERN/--exclude-from=FILE— skip specified files--backup--backup-dir=DIR— keep previous versions of changed/deleted files-e "ssh ..."— specify remote shell (usually SSH with custom options)--bwlimit=KBPS— limit bandwidth--info=progress2— overall progress display (if supported)
Combine these with overall backup strategies and automation tools from the broader Backup and Restore topic to build a reliable, efficient backup system with rsync.