Back to Blog
Homelab 4 min read

Self-Hosted Backups to Cloudflare R2 with rclone — Scoped Tokens and the /tmp Trap

Daily backups from the Pi to R2 via rclone, scheduled with systemd timers. Common pitfalls: /tmp sizing, scoped token permissions, and S3 ACL incompatibilities with R2.

The Raspberry Pi 5 runs the entire network infrastructure. Technitium DNS, Samba shares, monitoring, alerting — all on one device. A disk failure means outage. Backups need to happen, and they need to be automated and tested regularly.

Backup Architecture#

A script at /usr/local/bin/pi-backup.sh runs daily at 02:00 AM via a systemd timer unit with Persistent=true enabled. Persistent mode ensures that if the Pi reboots or is powered off during the scheduled time, the timer will execute the backup the next time the Pi boots.

The script stages backup archives to /var/backups/, not /tmp. Once the archive is built, rclone syncs the entire directory to Cloudflare R2 bucket shaferpi-backups. After the sync completes, rclone deletes any archives older than 7 days from R2, keeping the bucket size manageable.

The /tmp Trap: Sizing and tmpfs#

On a Raspberry Pi 5 running Raspberry Pi OS, /tmp is a tmpfs mounted with a default size limit of 1 GB. Staging large backup archives to /tmp will hit the size cap and silently fail or produce truncated archives. The script will exit happily thinking the backup succeeded, but the R2 bucket will receive a corrupted partial file.

Always stage to a real filesystem path like /var/backups/. /var is typically on the root filesystem with plenty of space. The archives land there first, then rclone syncs them to R2, then the local copies are deleted if needed.

Scoped Token Pitfalls#

Using a Cloudflare R2 API token with scoped permissions (restricted to specific buckets) introduces two gotchas that trip up nearly everyone.

First: acl = private causes 403 errors. Cloudflare R2 emulates S3 but does not support all S3 headers. Specifically, the S3 x-amz-acl header (which rclone's acl config option sets to private) is not supported by R2. Setting acl = private in the rclone R2 config causes every upload to fail with 403 Forbidden. The fix: remove the acl = private line from the rclone config entirely. R2 defaults to private visibility regardless.

Second: --s3-no-check-bucket is required. Scoped API tokens lack the s3:ListBuckets permission. When rclone starts, it attempts to verify the target bucket exists by listing all buckets (a standard S3 operation). With a scoped token, this permission is missing, and the verification fails. rclone exits before any upload happens, even though the token has full read/write access to the specific bucket.

The fix: add --s3-no-check-bucket to the rclone command, or set skip_bucket_check = true in the rclone config. This skips the bucket verification step and trusts that the bucket exists. Since scoped tokens are restricted to specific buckets, they implicitly require this flag.

Retention: 7-Day Rolling Window#

The backup script includes rclone delete --min-age 7d as the final step. This removes any backup archives from R2 that are older than 7 days. A rolling 7-day window keeps the bucket size under control without sacrificing too much historical depth.

Alerting on Failure#

The systemd timer unit includes an OnFailure= override that triggers a failure notification. If the backup script exits with a non-zero status, ntfy sends a push notification to the admin's phone immediately. Silence from the timer means the backup succeeded. Absence of notification means absence of failure. This is the opposite of most monitoring — the system is loud when things are wrong, not when they're right.

Verification After Initial Setup#

After initial setup, manually run rclone ls r2-backup:shaferpi-backups/ to confirm objects are landing in the bucket. Verify the file sizes match what you expect. Then trigger a manual backup run with systemctl start pi-backup.timer and monitor the output. If the upload succeeds but the timer doesn't fire from the cron schedule, check that the timer's unit is enabled: systemctl enable pi-backup.timer.