Back up with rsync

Sync any directory to your CapyArk storage node using rsync over SSH. Works on Linux, macOS, and Windows (WSL or Cygwin).

Prerequisites

• Tailscale installed and connected on the machine you’re backing up
• Your CapyArk storage node online (check the Connect tab in the portal)
• rsync installed — rsync --version should return 3.x or later

Step 1 — Find your storage hostname

In the portal, go to Connect. Copy the Tailscale hostname of your storage node — it looks like:

storage-baas_xxxxx

You can also get it by running tailscale status on any connected device.

Step 2 — Authenticate

CapyArk uses password authentication over SSH. Your SSH password is the same one you set during registration. You can also add SSH public keys in Settings → SSH Keys to avoid typing a password.

Test the connection:

ssh storage-baas_xxxxx

You should see a restricted shell message — that’s expected. Full PTY access is intentionally disabled; only file transfer commands are permitted.

Step 3 — Run rsync

Replace storage-baas_xxxxx with your actual hostname and /path/to/local/data/ with the directory you want to back up.

rsync -avz --progress \
  /path/to/local/data/ \
  storage-baas_xxxxx:/backup/

What the flags do:

Trailing slashes matter. /data/ (with slash) syncs the contents of data/ into /backup/. /data (no slash) syncs the data/ directory itself into /backup/data/.

Step 4 — Schedule recurring backups

Linux / macOS — cron

crontab -e

Add a line to run daily at 2 AM:

0 2 * * * rsync -az /path/to/local/data/ storage-baas_xxxxx:/backup/ >> /var/log/capyark-backup.log 2>&1

Linux — systemd timer (recommended)

Create /etc/systemd/system/capyark-backup.service:

[Unit]
Description=CapyArk rsync backup

[Service]
Type=oneshot
ExecStart=/usr/bin/rsync -az /path/to/local/data/ storage-baas_xxxxx:/backup/

Create /etc/systemd/system/capyark-backup.timer:

[Unit]
Description=Run CapyArk backup daily

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target

Enable and start:

systemctl enable --now capyark-backup.timer
systemctl list-timers capyark-backup.timer   # verify

Useful rsync options

# Dry run — see what would transfer without actually transferring
rsync -avzn /data/ storage-baas_xxxxx:/backup/

# Delete files from the destination that were deleted locally
rsync -avz --delete /data/ storage-baas_xxxxx:/backup/

# Exclude directories
rsync -avz --exclude='.git/' --exclude='node_modules/' /data/ storage-baas_xxxxx:/backup/

# Limit bandwidth (in KB/s) — useful on metered connections
rsync -avz --bwlimit=10000 /data/ storage-baas_xxxxx:/backup/

# Resume interrupted transfers (for large files)
rsync -avz --partial --progress /data/ storage-baas_xxxxx:/backup/

What happens to the files

Files transferred via rsync land in your ZFS dataset. The portal’s Backups tab shows the daily and weekly ZFS snapshots that CapyArk creates automatically — these capture the state of your entire dataset (including rsync’d files) at that point in time.

To restore specific files from a snapshot, see Restore from a snapshot.

Troubleshooting

ssh: connect to host storage-baas_xxxxx port 22: Connection refused Your Tailscale connection may not be up. Run tailscale status and confirm the storage node shows as online.

rsync: change_dir "/path" failed: No such file or directory The destination path (/backup/) is created automatically on first sync. If you’re specifying a sub-path, the parent must exist: ssh storage-baas_xxxxx mkdir -p /backup/mydir.

Permission denied (publickey,password) Double-check your password in Settings → Security in the portal. If you’re using SSH key auth, make sure the public key was added in Settings → SSH Keys and you’re using the matching private key.