Rsync Reference

▾ How to use this page

Status card — shows whether the global rsync gate is open. Red = all syncs blocked regardless of tier toggles.

Sync windows — per-tier enable/disable. A tier can be enabled here but still blocked by the global gate.

Settings → Global gate — RSYNC_ENABLED in master.conf. Master switch; turn off during rebuilds or maintenance.

Settings → Tier toggles — CRITICAL/DAILY/etc._RSYNC_ENABLED. Disable one tier without affecting others.

Bandwidth history — last 30 days of per-profile rsync runs. Bar = relative time spent. Click recent runs for detail.

Manual Rsync — one-off transfer to any partner host. Browse remote dirs via SSH. Runs in background, output streams below.

Profile Editor — create and edit named profiles used by appdata syncs. Each profile controls flags, BW limit, container stop lists, and excludes.

▸ Sync windows

Critical (30 min) — appdata (arrs, auth, databases), partnership health check, play state sync. Designed to be fast — uses dirty-sync profiles where possible.

Intermediate (4 hr) — arr sync between the nightly runs. Catches new indexer hits without waiting until midnight.

Daily (nightly) — media shares, arr maintenance, media cleaner, docker updates, daily container restarts.

Weekly — bulk media shares, update checks, weekly restarts, SMART health digest.

Fallback — fires when a server comes back online after being the active fallback. Syncs any changes that happened during downtime.

Two-tier toggle — global gate (RSYNC_ENABLED) blocks everything. Per-tier flags (e.g. DAILY_RSYNC_ENABLED) disable just that window. Both must be ON for syncs to run.

▸ Profile system

What is a profile? — A named set of rsync options applied to a specific appdata directory. Appdata shares match a profile by their directory basename (lowercased).

PROFILE_RSYNC_OPTS — Full rsync flag string for this profile. Does NOT inherit DEFAULT_RSYNC_OPTS — list every desired flag explicitly. Use $BW_LIMIT to reference the profile's bandwidth limit.

PROFILE_BW_LIMIT — Bandwidth cap in KB/s. Overrides the global BW_LIMIT for this profile.

PROFILE_RETRY_COUNT / SLEEP — How many times to retry on failure, and how long to wait between attempts.

PROFILE_CRITICAL_CONTAINER_NAMES — Containers stopped on BOTH hosts before rsync. Local stops first (flush DBs), then remote. Only running containers get restarted — stopped ones stay stopped.

PROFILE_DELAYED_CONTAINERS — Containers that need a delay after the others start (e.g. NextCloud waits for Postgres).

PROFILE_CONTAINER_DELAY — Seconds to wait before starting delayed containers.

PROFILE_EXCLUDE_DIRS — Space-separated patterns excluded from the rsync. Supports globs (e.g. logs *.tmp *.db-wal).

PROFILE_REMOTE_RESTART_CONTAINERS — Used by dirty-sync profiles. Restarts these containers on the remote after sync so it picks up the new data.

Clean vs dirty sync — Clean: stop containers, --delete, full mirror. Dirty: containers keep running, WAL files excluded, --inplace --no-whole-file for safe partial writes. Use dirty for frequent critical syncs.

App layer — Scripts add their appdata directory to HOST*_CRITICAL_SYNC_SHARES or HOST*_DAILY_SYNC_SHARES using /path/to/dir|profile-name syntax. Creating the profile here makes it available for that reference.

▸ Common flag combinations

Clean sync (weekly appdata)
-av --human-readable --bwlimit=$BW_LIMIT --delete
Full mirror — removes files on destination that no longer exist at source. Safe when containers are stopped.

Dirty sync (every 30 min)
-av --human-readable --bwlimit=$BW_LIMIT --delete --inplace --no-whole-file
Containers stay running. --inplace writes directly to destination file (avoids temp-file rename issues). --no-whole-file uses delta transfer. Exclude WAL files to avoid corrupt state.

Database sync (arrs)
-av --info=progress2 --human-readable --bwlimit=$BW_LIMIT --delete --inplace
Stop containers first. --info=progress2 gives cleaner progress output in logs. Lower BW limit to not starve other syncs running concurrently.

Large media (weekly)
-av --human-readable --bwlimit=$BW_LIMIT --delete --inplace --no-whole-file
High BW limit, inplace for large files, delete to keep mirror clean. No container stops — media files are read-only.

--delete — remove files at destination that no longer exist at source. Essential for a true mirror.

--inplace — write file data directly into destination file instead of creating a temp copy first. Faster for large files; required for some databases.

--no-whole-file — force delta transfer even over fast LAN. Reduces data sent for files that change incrementally.

--checksum — compare files by checksum rather than mtime+size. Slower but catches any corruption. Use for archive syncs, not frequent syncs.

Profile Editor

Select a profile above to edit, or click ＋ New to create one.

Profile name

Rsync opts does NOT inherit defaults — list every desired flag

-av --human-readable --info=progress2 --delete --inplace --no-whole-file --checksum --bwlimit=$BW_LIMIT --compress

Extra flags

            rsync_opts =
            
          

BW limit KB/s

Retry count

Retry sleep s

Container delay s

Stop containers space-separated — stopped on both hosts before rsync, restarted after

Delayed containers start after delay (e.g. app waits for its database)

Exclude dirs space-separated globs — e.g. logs *.tmp *.db-wal *.db-shm

Remote restart dirty-sync only — restarted on remote after sync so it picks up changes