backup and restore

Backup and restore

Three different things are called "backup" here, and they solve different problems:

1. The scheduled full backup — the whole installation, encrypted, on a schedule, to a folder or NAS share, a cloud bucket or an rclone remote.
2. The settings bundle — everything you configured, exported as one versioned JSON file, with or without your credentials.
3. Per-area bundles — subscriptions, stream channels or automations on their own, portable between installations.

None of them backs up your downloaded files. That is your storage's job.

The scheduled full backup

Settings → Backup & restore → Full backup.

What it contains

One archive (rdownloader-backup-<installation>-<time>.rdbackup) with:

• a consistent copy of the database — the queue and its history, the LinkGrabber, post-processing, packages, configuration;
• the settings bundle with your credentials, sealed under the same passphrase;
• the torrent session and the stored .torrent files;
• the plugin trust: confirmed signing keys, withdrawn versions, plugin repositories with their withdrawn keys and installs, and which plugin version runs;
• the list of unfinished transfers with how far each got.

A manifest inside names every part with its size and SHA-256.

Downloads keep running while it is written, and the archive is still one consistent point in time.

The passphrase

Set it up once, in the card's Passphrase form (at least 8 characters). rDownloader turns it into a key, keeps the key in its secret store so scheduled runs need nobody to type anything, and stores the passphrase nowhere. The card shows only the key's fingerprint.

• Without a passphrase no full backup is written at all — there is no unencrypted variant.
• Write the passphrase down somewhere safe. A restore asks for it again; without it the archive cannot be opened, by anyone. A lost passphrase cannot be recovered — the stored key serves the schedule and the verification, never a restore. Check now and then with Verify with passphrase (below) that you still have it.
• Changing it asks for the current passphrase first and applies to future backups. Older archives still open with the passphrase they were written with.

The archive is encrypted with XChaCha20-Poly1305 in 1 MiB chunks, with an Argon2id key: a changed byte, a missing or reordered piece and a cut-off file are all refused.

Schedule

• Schedule — a cron expression with five fields (minute, hour, day, month, weekday), e.g. 0 3 * * * for every night at three, read in the time zone you choose. It keeps its wall-clock time across the summer-time changes: a time that does not exist that night runs right after the gap, a time that exists twice runs once.
• Verification schedule — optional, another cron expression, e.g. 0 5 * * 0 for Sunday morning: it checks the newest archive at every destination (see Verification below). Empty is off.
• After a restart a run is neither repeated nor skipped. If the service was off when a run was due, it runs once at the next start — not once per missed night.

The schedule can only be switched on once a passphrase is set up and at least one destination is there. Back up now starts a run by hand. Only one run happens at a time.

Destinations

Add destination in the card's Destinations list. Add as many as you like — every destination gets its own copy of every archive:

Type	What you enter	How the archive gets there
Folder or NAS	an absolute path on the machine running rDownloader; a mounted NAS share works	must be an absolute, writable folder; the copy is hash-checked
Object storage	one of your object storage profiles and <bucket>/<folder> (without a bucket, the profile's own bucket)	S3, Azure Blob or Google Cloud Storage; an interrupted upload continues where it stopped
rclone remote	name:path of a remote you configured in rclone — WebDAV, SFTP, cloud drives and everything else rclone knows	the rclone rDownloader finds (settings, vendor folder or PATH); the size is checked afterwards

• An archive never replaces another file, and only ever appears under its name complete.
• Uploads keep the upload limit of your bandwidth settings; rclone gets it as --bwlimit.
• No destination stores a password: an object storage profile keeps its credentials where you set it up, and an rclone remote uses rclone's own configuration.
• There is no separate WebDAV destination — a WebDAV share is an rclone remote.
• Remove a destination and its archives stay where they are; rDownloader only forgets them.

A destination that is down costs only itself. It is tried three times, with a longer pause each time; the other destinations get their copy regardless, no download is touched, and the history shows which destination did not get the archive and why. A run counts as succeeded when at least one destination has the archive.

Retention

Each destination has its own rules:

• Keep newest — this many archives;
• Keep days — archives younger than this.

With both set, an archive stays when either rule wants it; with neither, every archive stays. The newest archive always stays, whatever the rules say. Old archives are removed only after the new one arrived at that destination.

Retention only ever removes archives this installation wrote there. A file someone else put in the folder, an archive of another installation writing to the same place, or a file you renamed are never touched.

Preview (in the destination's edit form) shows which archives the rules you are typing would keep and remove — nothing is deleted by looking.

Verification

Verify newest on a destination fetches its newest archive back and checks it where it lies:

1. against what was written — its size and SHA-256. A truncated, extended or changed archive fails here;
2. against itself — opened with your backup key and read to the end, every part checked against the manifest. An archive written under an earlier passphrase is checked by its digest only; the result says so.

The verification schedule does the same for the newest archive at every destination. Results are listed under Verifications, and the destination shows the last result. A check never changes an archive.

The verification uses the key the schedule keeps, and the list says so — it proves the archive is whole, not that you still know its passphrase. Verify with passphrase on a destination opens its newest archive with the passphrase you type, exactly as a restore would, reads it whole and writes nothing.

History

Every run is listed with its state — running, succeeded, failed, interrupted — whether it was scheduled or started by hand, the archive's name and size, how many old archives retention removed, or the reason it failed, per destination. A failed backup never stops or slows a download; it is only recorded here, in the log and in the audit log. A run the service stopped in the middle of is marked interrupted at the next start, and its leftovers are removed.

Restoring a full backup

Settings → Backup & restore → Restore → Restore from a backup …

A restore replaces the whole installation — database, configuration, credentials, torrent session, plugin trust — with the state in the archive. It never touches downloaded files, and it never happens while the service runs: it is prepared now and switched at the next start.

You need the passphrase the archive was made with — every step asks for it, and an archive made before you changed the passphrase needs the old one. A wrong passphrase is refused and recorded in the audit log.

The restore itself also asks for your password, from a signed-in session: it replaces the password, the passkeys and the API tokens at the next start, so an API token alone can never start one. With the login switched off nothing more is asked.

An archive chosen from the history must be exactly the one that run wrote — the same size and SHA-256. One that was changed or swapped at the destination, even for an older archive under the same passphrase, is refused. The database inside the archive must be undamaged and hold nothing this version would not create, and no watched folder or package folder may point into the folders rDownloader keeps its data, plugins, scripts or helper programs in.

1. Choose the archive — from the history, by uploading an .rdbackup file (any size), or by naming its path on the machine running rDownloader. The upload and the unpack below always leave 1 GiB free in the data folder; with less room they stop with not enough free space before the database could run out of it.
2. Show contents — reads the whole archive, checks every part against its manifest and changes nothing: when and by which version it was made, its parts and sizes, the storage roots and folders it refers to, how many categories, accounts, proxies, servers, subscriptions and watched folders it holds, and whether its credentials are included. A backup from a newer version than yours is flagged — update first.
3. Map the storage roots — for each storage root, the folder it lies in on this machine. Leave a field empty to keep the path. Every stored path below a root moves with it: package folders, watched folders inside it, unfinished transfers, torrent output folders. No moved path can end up outside its root — a stored .. refuses the restore.
4. Test restore — unpacks a throwaway copy, brings its database to your version, applies the mapping and reports what it finds, then deletes the copy. The running service, its database and its secret store are untouched. Errors (a path that would leave its root, a reference to something that is not there) block the restore; notes tell you what to do afterwards:
   • paths from another system nothing maps — they will not be found here;
   • storage roots that do not exist yet — created on first use;
   • credentials the backup has no value for — the account asks for them again;
   • secrets outside the settings bundle (notification targets, remote logins, object storage profiles, provider sign-ins) that this machine cannot open — set them up again;
   • the second factor cannot be read on another machine — sign in with a recovery code and set it up again;
   • missing .torrent files and unfinished transfers whose folder is not here — those start over.
5. Confirm and restore at the next start. The same checks run again and the result is staged next to the live data. The card says a restore is waiting; until you restart, Discard restore undoes it completely.

What happens at the next start

rDownloader moves the current database and torrent folders aside into data/restore-previous/ and puts the restored ones in their place. The previous ones are removed once the restored installation has started once.

If the restored database does not open, or that first start does not complete, the next start puts the previous installation back by itself and keeps the restored state in data/restore-failed/ with the reason. The card then shows the restore did not start and why, until you dismiss it. You are never left without a working installation.

Moving to another machine or system

A full backup is the way to move an installation, including between Windows and Linux (or macOS, or into Docker):

1. Install rDownloader on the new machine and complete the setup.
2. Copy the .rdbackup file somewhere the new machine can read it — or upload it in the dialog.
3. In the mapping step, give every storage root its folder on the new machine. Windows paths are understood as Windows paths even on Linux: D:\Downloads, D:/Downloads, \\nas\media and \\?\D:\Downloads are all recognised, with drive letters and names compared regardless of case. For example D:\Downloads → /srv/downloads moves D:\Downloads\Movies\Film to /srv/downloads/Movies/Film.
4. Run the test restore, read its notes, then restore and restart.
5. Afterwards: move or copy the downloaded files into the mapped folders yourself, re-enter what the notes named, and check the watched folders — a watched folder outside every storage root keeps its old path and must be edited.

Credentials in the settings bundle travel with the archive and land in the new machine's secret store; the backup schedule keeps its key when the archive was made with it, otherwise it is switched off until you set up a passphrase there.

The settings bundle

Settings → Backup & restore → Configuration.

What it contains

The settings document and the configuration tables:

• storage roots,
• categories and routing rules,
• watched folders,
• stream channels,
• subscriptions,
• proxy profiles,
• provider accounts,
• Usenet servers,
• authentication profiles,
• Newznab indexers — their API key, like every other credential, only in an export with secrets.

It also records which application version wrote it and when.

What it does not carry: the queue and its history, downloaded files, the audit log, the stored log records, your post-processing scripts, the archive password list, installed plugins, and the site rules — those have an export of their own, below.

With or without secrets

Two export modes:

• Without credentials — safe to keep anywhere. Accounts and servers arrive without their passwords and API keys, which you re-enter afterwards.
• With encrypted credentials — protected by a passphrase you choose. Key derivation is Argon2id, encryption is XChaCha20-Poly1305.

The TOTP seed never travels in a settings backup, in either mode.

Restoring

Importing asks for your password again, from a signed-in session — an API token cannot import a bundle. The bundle is validated before anything is written — watched folders that would lie in rDownloader's own folders are refused like storage roots —, then the configuration is replaced in one step — a failure halfway leaves nothing partially imported. Afterwards you get a summary of what was imported, and settings that can change at runtime take effect immediately.

A bundle that claims no default storage root, or several, is repaired on import — exactly one root is always the default.

What the bundle names again keeps what hangs off it. An account or a stream channel the bundle names is updated in place, so its sign-ins, remote jobs and recording schedules with their runs stay; a subscription it names keeps its archive, its runs and what it has already seen, so its feed is not taken for new. Only what the bundle no longer names is removed, with whatever belongs to it — stored tokens in the vault included.

Per-area bundles

Subscriptions, stream channels with their schedules, and automations each export to their own bundle, from their own view (Subscriptions, Streams, Automation). Site rules export and import the same way, from Settings → Site rules: each rule travels with its switch, and the import shows what it would add or replace before anything is stored — see Site rules. Categories and routing rules export together or on their own from Settings → Storage & rules — see Exporting and importing. LinkFilter rules export and import from their card under Settings → LinkGrabber → LinkFilter — see LinkFilter rules.

Unlike the settings bundle, they merge by name rather than replacing, carry no credentials (so no passphrase), and reference categories, notification targets and channels by name, so the bundle means the same thing on another installation. Consequences:

• A subscription that needed an API key or a token arrives switched off. Enter it, then enable the subscription.
• A script subscription is neither exported nor imported in a bundle, because it starts a program on the machine. The settings backup carries it.
• An automation whose action cannot be resolved is skipped whole, rather than imported as a rule that silently does nothing.

Duplicating a subscription

A subscription can be duplicated as the starting point for a similar one. The copy arrives disabled and without the original's API key.

What to back up on disk

The scheduled full backup above is the easy route. If you want a copy of the whole data directory as well:

Path	Holds
data/rdownloader.sqlite3	The database: queue, packages, configuration, history
data/secrets/	The encrypted secret store
data/plugins/	Installed plugin versions
data/torrents/, data/torrent-session/	Uploaded .torrent files and the BitTorrent engine's session
data/passwords.txt	The archive password list
data/scripts/	Your post-processing scripts
data/vendor/	Helper binaries you placed there
data/tools/	Managed external-tool versions — re-downloadable, so optional
data/plugin-cache/	Compiled plugin code — rebuilt when missing, so optional; cleaned up by itself
data/plugin-repositories/	The last verified index of each plugin repository — fetched again, so optional
data/pre-migration/	Copies of the database from before the last upgrades — see below, so optional
data/pre-update/	The backup before each update rDownloader installed itself — see Updates, so optional
data/diagnostics/	Diagnostic bundles you created — optional

The full layout is under The data directory.

In Docker that is the whole of /config.

Stop the service first, or copy the SQLite database with a tool that understands it — a naive copy of a live database can be inconsistent.

The secret store's master key comes from the operating-system keyring, with a private 0600 fallback file on Unix. A copy of data/ on a different machine or under another user account may therefore not be able to decrypt the secrets. rDownloader says so — a warning at the start, a count in rdownloader doctor, and secret.unreadable wherever such a credential is used — and you enter those credentials again. A full backup with its passphrase, or the settings bundle with encrypted credentials, is the portable route.

Before an upgrade

Back up data/ before replacing binaries. Migrations run automatically on the first start of a new version and are not designed to be undone. An update rDownloader installs itself writes its own backup first, encrypted when a passphrase is set up — see The backup before an update.

That first start also copies the database before it changes anything, into data/pre-migration/rdownloader-<from>-to-<to>-<time>.sqlite3 (the numbers are the database's schema before and after). The newest three copies are kept; once the update is proven, only the newest, and after Keep the newest copy days not that one either — see Cleaning up the data folder. The copy is not encrypted, like rdownloader.sqlite3 beside it; your credentials are in neither, but in the encrypted secret store.

If an upgrade of the database fails, rDownloader puts that copy back in place of the database and stops with an error db.migration_failed that names the copy. Nothing else has changed, so:

• Go back: start the version you had before; it opens the database as it left it.
• Or stay: keep the new version installed and report the error with a diagnostic bundle; every start tries the upgrade again from the same state.

Should the error say the database could not be put back, do it by hand: stop rDownloader, delete rdownloader.sqlite3-wal and rdownloader.sqlite3-shm in data/, replace rdownloader.sqlite3 with the copy the error names, and start the previous version.

Related pages

• Installation — upgrading
• Security and privacy — where secrets live
• Subscriptions · Automation
• Diagnostics and maintenance