Skip to content
Skills Library
DevOps & cloud · Automation

linux-rsync-sync

/linux-rsync-sync

Use when designing, previewing, running, or verifying rsync copies, mirrors, offsite transfers, or hard-linked backups on Debian/Ubuntu or RHEL-family hosts. Covers SSH, filters, deletion, checksums, and resume; use linux-archive-integrity for tar archives.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use when designing, previewing, running, or verifying rsync copies, mirrors, offsite transfers, or hard-linked backups on Debian/Ubuntu or RHEL-family hosts. Covers SSH, filters, deletion, checksums, and resume; use linux-archive-integrity for tar archives.

Original author description

Use when designing, previewing, running, or verifying rsync copies, mirrors, offsite transfers, or hard-linked backups on Debian/Ubuntu or RHEL-family hosts. Covers SSH, filters, deletion, checksums, and resume; use linux-archive-integrity for tar archives.

How it works

  1. Distro support
  2. Use When
  3. Do Not Use When
  4. Required Inputs
  5. Capability Contract
  6. Degraded Mode
  7. Decision Rules
  8. Workflow
  9. Quality Standards
  10. Anti-Patterns
Original SKILL.md headings · 344 lines, 1,961 words
SKILL.md preview
---
name: linux-rsync-sync
description: Use when designing, previewing, running, or verifying rsync copies, mirrors, offsite transfers, or hard-linked backups on Debian/Ubuntu or RHEL-family hosts. Covers SSH, filters, deletion, checksums, and resume; use linux-archive-integrity for tar archives.
license: MIT
metadata:
  portable: true
  compatible_with: [claude-code, codex]
  author: Peter Bamuhigire
  author_url: techguypeter.com
  author_contact: "+256784464178"
---
# rsync Sync & Incremental Backup

## Distro support

Single-tool skill: `rsync` is byte-for-byte identical on both families. The only
differences are the install package and the SSH server package for
rsync-over-SSH. Body uses Debian/Ubuntu; the **RHEL family** (Fedora, RHEL,
CentOS Stream, Rocky, Alma, Oracle) equivalents are in the matrix.

| Concept | Debian/Ubuntu | RHEL family |
|---|---|---|
| Install rsync | `apt install rsync` | `dnf install rsync` |
| SSH server (for pull/push over SSH) | `apt install openssh-server` | `dnf install openssh-server` |
| Daemon unit (rsyncd, rarely used) | `rsync.service` | `rsyncd.service` |
| `rsync -a` archive mode | identical | identical |
| `--link-dest` / `--bwlimit` / `--checksum` / `--partial` | identical | identical |
| SELinux on the target | not enforcing | **enforcing** — restore contexts with `restorecon -R` after a cross-host copy |

**RHEL-family gotcha:** SELinux is enforcing. rsync preserves file *contents*
and (with `-a`) ownership/perms, but a file landing in a new path may carry the
wrong SELinux context. Run `restorecon -R <target>` after restoring into
SELinux-labelled trees such as `/var/www` or `/home`. The `-X` (xattrs) flag
preserves the context only when source and target both label the same way.

In `sk-*` scripts use the `common.sh` package primitives (`pkg_install`, etc.)
rather than hardcoding apt/dnf. See
[`../../10-automation-and-scripting/linux-bash-scripting/SKILL.md`](../../10-automation-and-scripting/linux-bash-scripting/SKILL.md)
and [`../../docs/multi-distro/plan.md`](../../docs/multi-distro/plan.md).

<!-- dual-compat-start -->
## Use When

- Mirroring a directory tree to another disk, host, or offsite target.
- Building space-efficient incremental snapshot backups with `--link-dest`.
- Resuming a large transfer that was interrupted, or throttling one so it does
  not saturate a production link.
- Verifying a copy by content (`--checksum`) rather than size/mtime.

## Do Not Use When

- You need a *restore* of an existing GPG-encrypted backup or an emergency
  recovery checklist; use
  [`../../09-troubleshooting-and-recovery/linux-disaster-recovery/SKILL.md`](../../09-troubleshooting-and-recovery/linux-disaster-recovery/SKILL.md).
- You need a single sealed, integrity-verified archive (tar.gz/tar.xz with
  checksums); use
  [`../linux-archive-integrity/SKILL.md`](../linux-archive-integrity/SKILL.md).
- You need a crash-consistent point-in-time image of a live database volume;
  use [`../linux-filesystem-snapshots/SKILL.md`](../linux-filesystem-snapshots/SKILL.md).

## Required Inputs

| Artefact | Required? | Source | If absent |
|---|---|---|---|
| Canonical source and destination paths, including trailing-slash intent | yes | Data owner | Stop before transfer. |
| Mirror/history mode, deletion scope, excludes, retention, and ownership needs | yes | Backup policy | Run preview-only and request decisions. |
| SSH identity/host key and bandwidth window | remote transfer | Secret/network policy | Do not weaken host verification or saturate production. |

- The source path and the destination (local path, or `user@host:path`).
- Whether the run is a one-shot mirror, a `--delete` mirror, or a `--link-dest`
  incremental snapshot.
- Any bandwidth ceiling, exclude list, and whether SSH transport is required.

## Capability Contract

Source/destination inspection and dry-run are read-only. Transfer writes require destination authority; `--delete` requires explicit destructive approval tied to the reviewed preview. Remote access uses approved keys and verified host identity.

## Degraded Mode

Without destination access, produce a dry-run command and verification plan. Without delete approval, omit `--delete`. Without checksum capacity, report metadata-based verification and label content integrity unassessed.

## Decision Rules

| Choice | Action | Failure or risk avoided |
|---|---|---|
| `src` or `src/` | Choose deliberately from desired destination layout and prove it in dry-run output. | Nested/flattened path error. |
| Mirror or history | Use `--delete` only for an exact mirror; use `--link-dest` snapshots for recovery history. | Mistaking deletion propagation for backup. |
| Quick check or checksum | Use checksum for integrity/clock uncertainty; otherwise size+mtime for routine efficiency. | False integrity or needless load. |
| Interrupted large files | Use partial/append verification only where source files are stable during transfer. | Corrupt resumed copy. |

## Workflow

1. Always `--dry-run` first, especially before any `--delete` mirror.
2. Run the real transfer with the smallest correct flag set.
3. For incrementals, point `--link-dest` at the previous snapshot directory.
4. Verify with a second `--dry-run` (should report nothing to do) or
   `--checksum`.

5. Stop when dry-run layout, deletion scope, host identity, or destination capacity differs from plan; recover deleted data only from the recorded backup-dir/history and rerun verification.

## Quality Standards

- A trailing slash on the source means "contents of"; no slash means "the
  directory itself". Decide deliberately — this is the most common rsync bug.
- Preview `--delete` before running it. Deletion is unrecoverable.
- Throttle (`--bwlimit`) any transfer that shares a production link.

## Anti-Patterns

- Running deletion without preview. Fix: review itemised dry-run output and obtain destructive approval.
- Guessing slash semantics. Fix: prove the intended tree layout in a temporary/dry-run destination.
- Calling a mirror historical backup. Fix: add retained `--link-dest` snapshots or another history layer.
- Disabling SSH host verification. Fix: provision and verify the destination host key.
- Using append resume on changing files. Fix: use stable sources and `--append-verify`, or restart transfer.

- Running `--delete` without a prior `--dry-run`.
- Confusing `src/` and `src` and silently nesting or flattening the tree.
- Using `--size-only`/default mtime checks when bit-rot detection is the point
  (use `--checksum`).
- Treating an rsync mirror as a backup with history — a mirror has no
  point-in-time recovery unless you use `--link-dest` snapshots.
- Disabling SSH host verification. Correction: provision and verify the destination host key.
- Using `--append` on changing source files. Correction: use `--append-verify` only for stable files or restart transfer.

## Outputs

| Artefact | Consumer | Acceptance condition |
|---|---|---|
| Reviewed transfer plan | Operator | Records exact paths, slash semantics, flags, excludes, deletion preview, bandwidth, and rollback/history. |
| Transfer report | Data owner | Exit status, bytes/files changed, deletions, and destination capacity are recorded. |
| Verification evidence | Recovery owner | Second dry-run is empty or approved checksum comparison passes; exceptions are named. |

## Evidence Produced

| Artefact | Acceptance |
|---|---|
| Transfer evidence | Contains itemised preview, approved deletion scope, transfer statistics, host verification, and post-run comparison. |

Capture the itemised dry-run, approved destructive scope, command with secrets omitted, transfer statistics, SSH identity verification, post-run comparison, and snapshot link target where used.

## Worked Example

Mirror `/srv/data/` to an offsite `data/` path over SSH with a reviewed exclude file and bandwidth cap. Approve deletion only after inspecting itemised dry-run output, then require an empty second dry-run before declaring sync success.

- The exact rsync command run and the dry-run preview that justified it.
- Bytes transferred, files deleted (if any), and the verification result.
- The snapshot directory created, for incremental runs.

<!-- dual-compat-end -->

## References

- [`references/rsync-reference.md`](references/rsync-reference.md)
- [`references/incremental-snapshots.md`](references/incremental-snapshots.md)

**This skill is self-contained.** Every command below is stock `rsync` on both
families (the body shows Debian/Ubuntu; see **Distro support** above for the
RHEL-family install). The `sk-rsync-backup` script in the **Optional fast path**
section is a convenience wrapper — never required.

## Archive Mode (the baseline)

```bash
# -a = archive: -rlptgoD (recurse, links, perms, times, group, owner, devices).
# This is the correct default for backups: it preserves metadata.
rsync -a /var/www/ /mnt/backup/www/

# -v verbose, -h human sizes, --progress per-file progress, --stats summary
rsync -avh --progress --stats /var/www/ /mnt/backup/www/
```

> **Trailing slash matters.** `rsync -a src/ dst/` copies the *contents* of
> `src` into `dst`. `rsync -a src dst/` creates `dst/src/`. Get this wrong and
> you either flatten or double-nest the tree.

---

## Dry Run First (always, before --delete)

```bash
# Show exactly what WOULD change, transfer nothing:
rsync -avn --delete /var/www/ /mnt/backup/www/
#       ^^ -n = --dry-run

# Read the itemized change list (-i): >f+++++++ = new file, *deleting = removed
rsync -ain --delete /var/www/ /mnt/backup/www/
```

Only after the dry-run output is what you expect, drop the `-n` and run for
real.

---

## Mirror With --delete

```bash
# Make dst an EXACT copy of src — files removed from src are removed from dst.
rsync -a --delete /var/www/ /mnt/backup/www/

# Safety net: move deletions aside instead of removing them
rsync -a --delete --backup --backup-dir=/mnt/backup/deleted-$(date +%F) \
      /var/www/ /mnt/backup/www/
```

`--delete` is destructive on the destination. Never run it without a prior
`--dry-run`.

---

## Exclude Filters

```bash
# Inline excludes (repeatable)
rsync -a --exclude='node_modules' --exclude='*.log' --exclude='/cache/' \
      /var/www/ /mnt/backup/www/

# From a file — one pattern per line, '#' comments allowed
rsync -a --exclude-from=/etc/backup-excludes.txt /var/www/ /mnt/backup/www/
```

```text
# /etc/backup-excludes.txt
node_modules
vendor/
.git/
*.tmp
/var/cache/
```

A leading `/` anchors the pattern to the transfer root; without it the pattern
matches at any depth.

---

## Checksum Verification

```bash
# Default: rsync decides "changed" by size + mtime (fast).
# --checksum: compare a full checksum of every file (slow, catches bit-rot
# and clock-skew cases where size+mtime lie). Use for integrity audits.
rsync -avc /var/www/ /mnt/backup/www/
```

A good post-backup integrity check: `rsync -avnc src/ dst/` — if it reports any
files to transfer, the destination has drifted from the source.

---

## Bandwidth Throttling

```bash
# Cap at 5000 KB/s (~5 MB/s) so a backup never saturates a production uplink.
rsync -a --bwlimit=5000 /var/www/ backup@offsite:/srv/backups/www/

# --bwlimit takes KB/s by default; suffixes allowed: --bwlimit=5M
```

[GROUNDING-GAP: `--bwlimit` units, the leaky-bucket behaviour, and interaction
with `--whole-file`/SSH compression are from upstream rsync(1) man page; deepen
with UNIX & Linux System Administration Handbook.]

---

## Incremental Snapshots With --link-dest

`--link-dest` makes unchanged files **hard links** to the previous snapshot, so
each daily snapshot is a complete browsable tree but only consumes disk for the
files that actually changed. This is the classic `rsnapshot`/Time Machine model.

```bash
DEST=/mnt/backup/snapshots
TODAY=$DEST/$(date +%F)
LAST=$(ls -1d "$DEST"/20* 2>/dev/null | tail -1)   # most recent prior snapshot

rsync -a --delete \
      ${LAST:+--link-dest="$LAST"} \
      /var/www/ "$TODAY/"
```

Each `$TODAY` is a full snapshot you can browse and restore from directly; only
changed files cost extra disk. Delete an old snapshot dir to expire it — hard
links mean shared data survives until the last referencing snapshot is gone.

[GROUNDING-GAP: `--link-dest` (and multiple `--link-dest` dirs, the
hard-link/inode accounting, and pruning semantics) is from upstream rsync(1)
man page and the rsnapshot design; deepen with UNIX & Linux System
Administration Handbook.]

Full snapshot rotation strategy: [`references/incremental-snapshots.md`](references/incremental-snapshots.md).

---

## rsync Over SSH

```bash
# Push to a remote host (rsync uses ssh as the transport by default for host:path)
rsync -a -e ssh /var/www/ backup@offsite:/srv/backups/www/

# Pull from a remote host
rsync -a backup@offsite:/srv/backups/www/ /var/www/

# Non-standard SSH port and an identity key
rsync -a -e 'ssh -p 2222 -i ~/.ssh/backup_ed25519' /var/www/ backup@offsite:/srv/backups/www/

# -z compress in transit (skip for already-compressed data / fast LANs)
rsync -az -e ssh /var/www/ backup@offsite:/srv/backups/www/
```

Grounded in the RHCSA flow: `rsync -a server2:/etc/ /tmp` synchronizes a remote
directory locally over SSH (Sander van Vugt, RHCSA 8 Cert Guide).

---

## Restartable / Resumable Transfers

```bash
# --partial keeps a partially transferred file so the next run resumes it
# instead of starting over. --append-verify resumes AND checksums the existing
# bytes. --progress shows where it is.
rsync -a --partial --append-verify --progress \
      bigfile.img backup@offsite:/srv/backups/

# Convenience bundle for flaky links: -P = --partial --progress
rsync -aP big-dir/ backup@offsite:/srv/backups/big-dir/

# Run again after an interruption — it picks up where it left off.
```

Full flag reference and the source-trailing-slash rules:
[`references/rsync-reference.md`](references/rsync-reference.md).

---

## Optional fast path (when sk-* scripts are installed)

Running `sudo install-skills-bin linux-rsync-sync` installs:

| Task | Fast-path script |
|---|---|
| Dry-run-first mirror or `--link-dest` snapshot, bwlimit-aware | `sudo sk-rsync-backup --src /var/www --dst /mnt/backup/www` |

This is an optional wrapper around the `rsync` commands above.

## Scripts

This skill installs the following scripts to `/usr/local/bin/`. To install:

```bash
sudo install-skills-bin linux-rsync-sync
```

| Script | Source | Core? | Purpose |
|---|---|---|---|
| sk-rsync-backup | scripts/sk-rsync-backup.sh | no | Wrapper around `rsync -a`: ALWAYS previews with `--dry-run` and asks before a real run; supports `--delete` mirror or `--link-dest` incremental snapshot mode, `--bwlimit` throttling, `--exclude-from`, and SSH targets (`user@host:path`). Verifies with a post-run dry-run. |
Files in this package (3)
  • SKILL.md 14 KB
  • references/incremental-snapshots.md 4 KB
  • references/rsync-reference.md 7 KB

Versions

The database has no other skills named linux-rsync-sync.

Database snapshot: 13.11.2026 · package version 2c9f2e0a98c9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100linux-archive-integrity
    Use when creating, signing, encrypting, listing, comparing, or restoring metadata-preserving tar archives on Debian/Ubuntu or RHEL-family hosts. Covers ACLs, xattrs, incrementals, and verification; use linux-rsync-sync for file-tree mirrors.
  • 100linux-filesystem-snapshots
    Use when creating, monitoring, replicating, mounting, or rolling back LVM, Btrfs, or ZFS snapshots on Debian/Ubuntu or RHEL-family hosts. Covers consistency, COW, and rollback; use linux-rsync-sync or linux-archive-integrity for independent backups.
  • 100rsync
    rsync copies and synchronizes files locally or over SSH, sending only the parts that changed. Use when someone asks to "copy files to a server", "sync two directories", "mirror a folder", "make incremental backups with hard links", "deploy a build to a remote host", "resume a…
  • 100model-sync
    Synchronizes ML model files across servers. Supports rsync-based transfer with bandwidth control and checksum verification. Use for "모델 동기화", "모델 배포", "rsync 모델", "서버로 전송" requests.
  • 100ssh
    SSH remote access - connections, tunnels, keys, file transfers. Use when connecting to servers, managing SSH keys, setting up port forwarding, or transferring files with scp/rsync.
  • 90ostiary
    Run commands and transfer files on remote servers through ostiary. Use whenever a task needs a shell on a server, logs from a host, a service restart, or a file copied to/from a host. Never use ssh/scp/rsync directly.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.