rclone

rclone is “rsync for cloud storage”: it copies, syncs, mounts and encrypts across 70+ providers (S3, B2, Google Drive, OneDrive, SFTP, WebDAV, local disk). It is a file mirroring tool, not a versioned backup tool, so use --backup-dir or a real backup program (restic, BorgBackup) when you need history.

Documentation: rclone docs · Commands · Filtering · Crypt · Bisync

Verification: Only the bisync status (no longer labelled beta, --resync required on the first run) was checked against rclone.org. All other commands and flags are standard rclone usage written from knowledge and were not re-checked this session. No command was executed. Always dry-run sync first.

See also: Backup Strategy · restic · rsync · Docker Volume Backup · OpenSSH Cheat-Sheet · Linux · Mount

Remotes and Config #

The config file holds credentials: chmod 600, back it up with the other secrets (see Backup Strategy). It can be encrypted with rclone config -> “Set configuration password”, then supply RCLONE_CONFIG_PASS or --password-command.

Remotes without a config file, from the environment:

export RCLONE_CONFIG_B2_TYPE=b2
export RCLONE_CONFIG_B2_ACCOUNT=<KEY_ID>
export RCLONE_CONFIG_B2_KEY=<APPLICATION_KEY>
rclone lsd B2:

Example S3-compatible remote in rclone.conf:

[s3]
type = s3
provider = Other
access_key_id = <ACCESS_KEY_ID>
secret_access_key = <SECRET_ACCESS_KEY>
endpoint = https://<ENDPOINT>

copy, sync, move #

Remember: rclone sync is one-way and destructive on the destination. The direction is SRC DEST. Check twice.

Safe sync routine #

# 1. Preview. Nothing is changed.
rclone sync /srv/data <REMOTE>:<BUCKET>/data --dry-run -v

# 2. Real run with guard rails.
rclone sync /srv/data <REMOTE>:<BUCKET>/data \
  --max-delete 50 \
  --backup-dir <REMOTE>:<BUCKET>/archive/$(date +%F) \
  --log-file /var/log/rclone-data.log --log-level INFO \
  --stats-one-line

# 3. Verify. Compares sizes and hashes, reports differences.
rclone check /srv/data <REMOTE>:<BUCKET>/data --one-way

--max-delete N aborts if more than N deletions would happen. --backup-dir moves overwritten and deleted files into a dated archive, giving cheap versioning. It must be on the same remote as the destination and outside the destination path.

Common Flags #

--bwlimit can be changed live on a running rclone that has --rc enabled, or with SIGUSR2 to toggle.

Filters #

Patterns use ** for any path depth and a leading / to anchor at the root of the transfer. Rules apply in order, first match wins.

Test filters before running:

rclone ls /srv/data --filter-from /etc/rclone/filters.txt

Crypt (client-side encryption) #

A crypt remote wraps another remote and encrypts file contents and, optionally, names.

[secret]
type = crypt
remote = <REMOTE>:<BUCKET>/encrypted
filename_encryption = standard
directory_name_encryption = true
password = <OBSCURED_PASSWORD>
password2 = <OBSCURED_SALT>

Create it with rclone config (it generates and obscures the passwords) rather than hand-editing.

Back up the crypt passwords and rclone.conf separately. Without them the data is unrecoverable. Obscured is not encrypted: anyone with the config file can decrypt.

Mount and Serve #

Mount flags that matter: --vfs-cache-mode full, --vfs-cache-max-size 20G, --dir-cache-time 72h, --allow-other (needs user_allow_other in /etc/fuse.conf). Mounts are fine for browsing and light access. Do not put a database directory on one.

Scheduled Sync with systemd #

/etc/systemd/system/rclone-backup.service:

[Unit]
Description=rclone sync to offsite
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
Environment=RCLONE_CONFIG=/etc/rclone/rclone.conf
ExecStart=/usr/bin/rclone sync /srv/data <REMOTE>:<BUCKET>/data --max-delete 100 --backup-dir <REMOTE>:<BUCKET>/archive --log-file /var/log/rclone-backup.log --log-level INFO

/etc/systemd/system/rclone-backup.timer:

[Unit]
Description=Daily rclone sync

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true

[Install]
WantedBy=timers.target

sudo systemctl daemon-reload && sudo systemctl enable --now rclone-backup.timer

Gotchas #

• sync direction and trailing slashes: rclone treats src and src/ the same (unlike rsync); it always syncs the contents of the source into the destination.
• A sync from an empty or unmounted source deletes everything at the destination. Guard with --max-delete, or check the source mount first (findmnt /mnt/data || exit 1).
• Provider rate limits (Google Drive, OneDrive) may need --tpslimit and fewer --transfers, and for Drive your own client ID.
• rclone mount and copy run as the user whose rclone.conf they read. Under systemd, set RCLONE_CONFIG explicitly.
• Copying a live database file gives an inconsistent copy. Dump first, see Database Dumps.