Restore, clone, and stay online

Prepare the SD card (WiFi + Cloudflare tunnel)

Run on your Mac. Downloads Pi OS Lite, flashes it, installs cloudflared, and pre-configures your WiFi and Cloudflare tunnel — so the Pi comes up fully SSH-accessible on first boot with no cable and no monitor.

bash extras/firstboot/prepare-sd.sh --flash --cf-api-token <CF_API_TOKEN>

The --cf-api-token flag (Tunnel:Edit permission) syncs the remote ingress config so any hostname routes correctly through the tunnel — without it, unknown hostnames return 404. You will be prompted for your SD disk, WiFi SSID/password, Pi password, tunnel UUID, and CF hostname.

Run the restore one-liner

Installs dependencies and AWS CLI, prompts for your AWS credentials, then streams the backup directly from S3 to the target device. Have your AWS access key and secret ready — retrieve them from your password manager first.

curl -sL pi2s3.com/restore | bash

Interactive: picks your latest backup and target device. Non-interactive: bash ~/pi2s3/pi-image-restore.sh --date 2026-04-16 --device /dev/nvme0n1 --yes

Validate (optional, before touching hardware)

Confirm the S3 image exists and is intact from any machine that has AWS access.

bash ~/pi2s3/test-recovery.sh --pre-flash

✔ AWS access OK
✔ Image exists: 2026-04-16/  (3.4 GB)
✔ Manifest: raspberrypi · Pi 5 · Bookworm · nvme0n1
  Estimated restore time: ~12 min
  Run: pi-image-restore.sh --date 2026-04-16 --device /dev/nvme0n1

Partial restore: recover a single file or directory

No target device needed. Streams the partition from S3, mounts it via a loop device, and copies the requested path to ./pi2s3-extract-<date>/. Linux only.

# Recover /home/pi from the latest backup
bash ~/pi2s3/pi-image-restore.sh --extract /home/pi

# Recover /etc from a specific date
bash ~/pi2s3/pi-image-restore.sh --extract /etc --date 2026-04-16

# Specify partition (default: largest non-boot = root fs)
bash ~/pi2s3/pi-image-restore.sh --extract /var/lib/docker --partition nvme0n1p2

Restore to a larger device: --resize

Restoring a 128 GB backup to a 256 GB NVMe? Pass --resize and the last partition automatically expands to fill the available space after flash. Uses growpart and resize2fs.

bash ~/pi2s3/pi-image-restore.sh --date 2026-04-16 --device /dev/nvme0n1 --resize

Pi 5 NVMe: throttle writes to prevent PCIe crashes

Some Pi 5 + NVMe combinations trigger a PCIe watchdog reset under sustained writes. --rate-limit 10m caps the uncompressed byte rate into partclone at 10 MB/s — applied after gunzip for direct write-rate control. Increase if stable. Requires pv.

sudo apt install pv
bash ~/pi2s3/pi-image-restore.sh --device /dev/nvme0n1 --resize --yes \
  --rate-limit 10m

Wire NVMe boot on a new Pi (--post-restore)

When restoring to a bare NVMe on a different Pi, the SD card PARTUUID in /etc/fstab and the root= in /boot/firmware/cmdline.txt need updating for the new hardware. post-restore-nvme-boot.sh handles both automatically — no manual editing.

bash ~/pi2s3/pi-image-restore.sh --device /dev/nvme0n1 --resize --yes \
  --rate-limit 10m \
  --post-restore extras/post-restore-nvme-boot.sh

Set NEW_HOSTNAME=my-pi-qa to rename the clone in the same step.

Boot & clear stale SSH key

Raspberry Pi OS automatically expands the root filesystem. Clear the old host key on your Mac before connecting.

ssh-keygen -R raspberrypi.local
ssh pi@raspberrypi.local

Post boot verification

Checks filesystem expansion, NVMe mount, all Docker containers, Cloudflare tunnel, cron jobs, MariaDB, HTTP, memory, and load.

bash ~/pi2s3/test-recovery.sh --post-boot

✔ OS: Debian GNU/Linux 12 (bookworm) aarch64
✔ Filesystem expanded (954 GB)
✔ NVMe mounted at /mnt/nvme
✔ Docker: 6/6 containers running
✔ Cloudflare tunnel: active (2 ha_connections)
✔ Cron: pi2s3 backup + app-layer backup present
✔ MariaDB: responding, 42 tables
✔ HTTP: 200 OK on localhost

Set up the standby Pi (Steps 1–9 first)

Follow DR-quickstart.md Steps 1–9 to restore a second Pi from your S3 backup and give it its own SSH hostname. Then run the sync installer on the standby:

# On the STANDBY Pi, after Steps 1–9
bash ~/pi2s3/extras/install-standby-sync.sh

This copies pi2s3 tools onto the SD card, installs a restore agent that runs automatically on SD boot, and adds a 30-min cron job that watches for the S3 sync marker.

Wire failover commands (provider-agnostic)

In the primary Pi's config.env, set the two failover hooks and the verify URL. pi2s3 ships provider scripts for Cloudflare and Route 53 — or supply any shell command.

# Primary Pi config.env
HOT_STANDBY_ENABLED=true

# Cloudflare DNS example
STANDBY_FAILOVER_CMD="bash ~/pi2s3/extras/failover/cf-dns-swap.sh --to-standby"
STANDBY_FAILBACK_CMD="bash ~/pi2s3/extras/failover/cf-dns-swap.sh --to-primary"

# Route 53 example
# STANDBY_FAILOVER_CMD="bash ~/pi2s3/extras/failover/route53-swap.sh --to-standby"
# STANDBY_FAILBACK_CMD="bash ~/pi2s3/extras/failover/route53-swap.sh --to-primary"

# Backup waits until standby is confirmed serving before stopping Docker
STANDBY_VERIFY_URL="https://yourdomain.com"
STANDBY_PRIMARY_VERIFY_URL="https://yourdomain.com"
STANDBY_FAILOVER_TIMEOUT_SECS=300

# Optional: read current DNS TTL to calibrate propagation wait
STANDBY_VERIFY_DOMAIN="yourdomain.com"

After calling the failover command, pi2s3 reads the DNS TTL via dig and polls STANDBY_VERIFY_URL until HTTP 2xx — so backup only proceeds once standby is actually serving. Write your own provider script using extras/failover/generic-template.sh.

Cloudflare provider: required vars

If using cf-dns-swap.sh, add these to primary's config.env. The API token needs Zone:DNS:Edit permission only.

# In primary config.env
CF_ZONE_ID="<your-zone-id>"         # zone dashboard → Overview → Zone ID
CF_API_TOKEN="<dns-edit-token>"      # Cloudflare API token, Zone:DNS:Edit
CF_FAILOVER_DOMAINS="yourdomain.com,www.yourdomain.com"
PROD_TUNNEL_UUID="<production-tunnel-uuid>"
STANDBY_TUNNEL_UUID="<standby-tunnel-uuid>"

# Standby SSH hostname stays permanently on standby UUID — never swaps
# ssh-standby.yourdomain.com  CNAME  <STANDBY_TUNNEL_UUID>.cfargotunnel.com

Configure the standby Pi's sync settings

In the standby Pi's config.env (same S3 bucket and AWS creds as primary), enable sync and point to a post-restore script that re-applies standby-specific config after each restore.

# Standby Pi config.env
HOT_STANDBY_SYNC_ENABLED=true
STANDBY_SYNC_DEVICE="/dev/nvme0n1"

# Confirm primary is up before syncing (skips sync if primary is down
# and this standby is serving traffic — prevents unnecessary downtime)
STANDBY_SYNC_PRIMARY_URL="https://yourdomain.com"

# Runs after each restore: swaps CF tunnel UUID, updates hostname, etc.
# Copy extras/post-restore-standby-example.sh and fill in your values.
STANDBY_POST_RESTORE_SCRIPT="~/pi2s3/extras/post-restore-standby.sh"

Template: extras/post-restore-standby-example.sh. The script receives the restored NVMe mount point as $RESTORE_ROOT and runs before the first boot — swap the CF tunnel UUID here so the standby doesn't come up using production credentials.

SSH access to the standby (no browser auth)

Create a Cloudflare Access service token for the standby SSH hostname and add it to your local SSH config.

# ~/.ssh/config
Host ssh-standby.yourdomain.com
    ProxyCommand cloudflared access ssh --hostname ssh-standby.yourdomain.com \
                 --id <CF-Access-Client-Id> \
                 --secret <CF-Access-Client-Secret>
    User <pi-username>
    IdentityFile ~/.ssh/your_pi_key
    StrictHostKeyChecking no

Make sure your SSH public key is in ~/.ssh/authorized_keys on the standby: ssh-copy-id -i ~/.ssh/your_pi_key.pub <user>@ssh-standby.yourdomain.com

Test the full cycle

# 1. Trigger a manual failover (primary → standby)
bash ~/pi2s3/extras/failover/cf-dns-swap.sh --to-standby
curl -I https://yourdomain.com   # confirm 200 from standby

# 2. Fail back to primary
bash ~/pi2s3/extras/failover/cf-dns-swap.sh --to-primary
curl -I https://yourdomain.com   # confirm 200 from primary

# 3. Trigger a manual sync cycle on standby
ssh ssh-standby.yourdomain.com \
  "bash ~/pi2s3/extras/hot-standby-sync.sh"
# Standby will reboot, restore (~30 min), come back up

# 4. Confirm standby is back and shows today's date
ssh ssh-standby.yourdomain.com "cat ~/pi2s3/.standby-last-synced"