Where to look when you want to know what the service thinks its own state is: the readiness card, rdownloader doctor, the log viewer, the audit log, the diagnostic bundle, and the data directory.

Settings → System — System & maintenance, in the Administration group — is the status page. The global settings reset sits in its header; below it are three tabs:

• Status — the status cards (HTTP and hosters, capture-agent pairing, Usenet), the readiness checklist (see below) and the facts: rDownloader with its publisher, DEGOYA.digital, and licence, the version, the web UI address and the configured port, the capture agent's 127.0.0.1:9666, the hotfolder interval, the NZB intake.
• Updates — the update check; see Updates.
• Logs & retention — the log level, log retention, a way straight into the log viewer, and Clear for the service log; audit retention, the OpenTelemetry export switch beside it, and Clear for the audit log; the download history retention; statistics retention, and Clear for the transfer statistics; and Import history — whether imported NZB entries and stored .torrent files are kept once their download is done.

The Updates and Logs & retention tabs carry the save bar for their fields.

Pairing a capture agent or the browser extension, and the list of paired clients, are under Settings → Clients & API (tabs Desktop and Browser).

It states whether setup is finished, showing four things as settled or outstanding, each with a way to the place that fixes it:

1. The login.
2. A storage destination.
3. A category.
4. The setup having been completed.

The steps the wizard lets you skip are deliberately not listed.

It also flags a storage root that will not survive the container, and a tool version that blocks a capability.

rdownloader doctor --database data/rdownloader.sqlite3 --downloads downloads

Checks:

• Paths — the database and downloads directories, and whether they are writable.
• SQLite — that the database opens and migrates.
• External tools — yt-dlp, ffmpeg, ffprobe, gallery-dl, streamlink, unrar, 7z, rclone, apprise: where each was found, which version it reports, its verdict, and — when there is something to do — the upgrade path.
• The reverse-proxy contract — the resolved external URL, trusted proxies and cookie setting, with warnings about half-configured combinations that work at first and misbehave later.
• The service — whether an rDownloader service runs on this data directory (service: running with its process and address, service: running (starting, or not answering yet), or service: not running).
• The stored settings — a value a start would refuse is named as settings: a start refuses them: …, with the statement that repairs it (see below).
• The stored credentials — how many there are and whether this installation's master key opens them all: vault: 12 stored credentials, all readable, or how many it cannot read, with what to do (see Troubleshooting). It only counts: no value and no name is printed.

The tool and reverse-proxy sections are the same checks the diagnostic bundle carries.

doctor is safe to run while the service runs: it does not touch the queue. Interrupted downloads and post-processing steps are recovered by the service itself when it starts.

Only one service runs per data directory: a second rdownloader serve on the same database stops at once with "another rDownloader service already runs on …". Stop the first with rdownloader stop. The guard is the lock file serve.lock in the data directory; doctor holds it while it works when no service runs, so none starts beside it. On a network share that cannot lock files at all (some CIFS and NFS mounts) the service starts anyway with the warning the file system cannot lock; a second service on this data directory is not refused — then making sure only one runs is up to you.

A start reads the stored settings field by field. Only the values the queue runs with — the parallel files, chunks and connections, the NNTP limits, the speed limits, the retries and the automatic retry, the global proxy profile, the custom CA, pausing during post-processing and the service switches — refuse the start when they do not read, and the message names the field and how to reset it, for example:

the stored setting `max_retries` (…) cannot be used: …. To repair it, stop the service and remove
the value so it reads as its default, for example with the sqlite3 shell on the database file:
UPDATE settings SET value_json = json_remove(value_json, '$.max_retries') WHERE key = '…'

Any other field that does not read — after a hand edit, say — takes its default, and the log names it with a warning; open the settings and save the value again. rdownloader doctor reports the same without starting anything.

In Docker:

docker exec rdownloader rdownloader doctor

doctor observes no request. It prints the configured trusted range, not the address requests actually arrive from — that is in the proxy's access log or docker network inspect.

rdownloader doctor site-rules                    # every switched-on rule
rdownloader doctor site-rules --rule debian-cd   # one of them, repeatable

Tries each switched-on site rule against its own probe address and reports what it found — ok, structural, blocked or dead, shown in Settings → Site rules as Working, Changed, Blocked or Dead — so a rule broken by a redesigned page says so instead of quietly matching nothing. The exit code is 1 as soon as one rule is not ok. See Site rules.

curl -fsS http://127.0.0.1:8710/api/v1/health

The container image uses this as its health check, with a start period long enough for the plugin installation.

Two things share the word, and they answer different questions. Logs is what the service did; the audit log is who asked it to.

Logs in the sidebar, its first tab, Log; the second tab is the diagnostic bundle. Every event the service lets through its log level is also written to the database and shown here. The filter card sits above the list: minimum level, component prefix, exact code, exact correlation id, and a case-insensitive search in messages; Apply sets them, Clear filters empties them. Each row shows time, level, component, code, correlation id and message; a record with further fields opens them behind the chevron. The list says when it is a full page and offers the page behind it, and it states the retention in force.

Redaction happens before storage, not before display: a field whose name says it holds a credential — password, token, api_key, authorization, cookie, the signed-URL parameter names — is replaced whole. See Redaction.

Logging never blocks a download. When the store falls behind, records are dropped and counted; the viewer shows the drop count above the list.

Retention is two settings under Settings → System → Logs & retention, applied within a minute, without a restart. To start from an empty log instead — before a test run, say — see Clearing logs, audit records and statistics.

Audit log in the sidebar: who did what, from where, and how it ended — sign-ins and refusals, tokens created, revoked and rescoped, settings changed and reset, plugins installed and removed, plugin repositories added, changed and removed, every plugin version choice, signing keys revoked and packages withdrawn, downloads, packages, categories and storage roots deleted, backups restored.

Records are appended and never edited; no single record can be changed or deleted. The whole log can be emptied from the settings, and that act becomes the emptied log's first entry — see below. Deleting a download leaves its record behind, and restoring a configuration backup does not touch the log. It is a record of what happened, not a protection against somebody with access to the file itself.

Filter by action, outcome, actor kind, channel, target and trace id; export what the filter matched. The channel says how an action came: through the web interface or another REST client, through an AI assistant over MCP, through the browser extension or desktop agent, through a SABnzbd or qBittorrent client, or from the service itself — so one token's changes over MCP and over REST are told apart. No password, token or signed link ever reaches this list.

Log level decides what the service records — Error, Warning, Info (the default) or Debug. Set it under Settings → System → Logs & retention or at the top of the Logs page. A change holds from the next line, without a restart, and is kept in the settings; the same level governs the console, the log viewer and the trace export.

Debug for a while, on the Logs page, puts one area on debug for 15, 30 or 60 minutes — plugins (all of them or one), hosters and providers, Usenet, torrent, media, the LinkGrabber, subscriptions, HTTP or the scheduler — while everything else stays at the level you set. The page says until when; End now stops it early. Afterwards the level holds again by itself, also when rDownloader restarted in between. Secrets stay redacted on debug too.

RUST_LOG wins. Set when the service starts, it decides what is logged; the page then names its value, and the level and debug for a while cannot be changed until the service starts without it. Over MCP the same is get_log_level, set_log_level, start_log_debug and stop_log_debug.

A plugin writes at most 50 log lines per call. What it writes beyond that is dropped and counted in one warning at the end of the call — … n more lines suppressed, with the plugin's id, version and the operation. Lines the level filters out do not count towards the 50.

Without a RUST_LOG, the level above decides. RUST_LOG overrides it for the whole run — the same filter then governs stderr and the store:

RUST_LOG=info rdownloader serve …          # info everywhere
RUST_LOG=rd_api=debug rdownloader serve …  # one component louder
RUST_LOG=debug rdownloader serve …         # everything

The portable launchers write below logs/ — appended by the Unix launchers, rewritten on each start by the Windows one. In Docker: docker logs -f rdownloader.

A refused MCP token is logged with the first eight characters of its SHA-256 digest, so the line can be matched against the token list without the token itself ever appearing. A client that keeps knocking with the same refused API token is logged once, and then at most once every ten minutes per address, path and reason, with a count of the refusals in between.

A warning means you should do or know something. Routine Usenet cases are logged at debug: obfuscated posts whose articles disagree on the file name (the NZB subject decides it), a segment no server has, and a server falling out of step while pipelining. A file with missing segments gets one line saying how many, and a warning only when it stays incomplete because its set has no PAR2 to repair it; a set beyond repair warns once. A server on which pipelining is given up warns once.

Every request and every queued job carries a trace id from intake to post-processing. Paste it from the audit log into the log viewer's correlation filter and you read one piece of work end to end.

Traces can additionally be exported over OpenTelemetry — off by default, switched on under Settings → System → Logs & retention with an endpoint and a timeout.

The Diagnostic bundle tab of the Logs page, /logs?tab=bundle — one click, no scrolling through the log. An archive for a support request, written on this machine only — there is no upload — under <data directory>/diagnostics/rdownloader-diagnostics-<UTC>.zip.

It is created in two steps:

1. Preview contents shows the inventory: every file the archive would hold, what it contains, how many items are in it right now, what was redacted in it, and what no bundle ever contains. Untick what the recipient should not get.
2. Create bundle approves exactly that preview. If the inventory has changed since, it is refused and you look at it again.

Never included, whatever the settings hold: file contents and file names of downloads, full URLs with credential-bearing query values, secrets of any kind — passwords, tokens, API keys, cookies, certificates, vault references —, notification titles, texts, endpoints and topics, and package names and folders.

Two bundles from the same installation with the same selection can be compared by diffing their manifests.

The preview is in the interface language; manifest.json inside the archive stays in English, with a description per entry, whatever language you previewed in.

data/
  rdownloader.sqlite3     the database
  secrets/                the encrypted secret store
  plugins/                installed plugin versions
  plugin-cache/           compiled plugin code, rebuilt when missing; cleaned up, see below
  plugin-repositories/    the last verified index of each plugin repository
  torrents/               uploaded .torrent files
  torrent-session/        the BitTorrent engine's session
  tools/<name>/<version>/ managed external tools
  scripts/                post-processing user scripts
  passwords.txt           the archive password list
  vendor/                 helper binaries, searched before PATH
  diagnostics/            diagnostic bundles you created
  pre-migration/          database copies from before the last upgrades; cleaned up, see below
  pre-update/             the backup before each update rDownloader installed itself; likewise
  update/                 an update being installed: the download, its journal, the updater
  local-control.json      while the service runs: the key `rdownloader stop` uses

In Docker this is /config. Where the folder itself is — beside the programs, or in your user's data folder for an installed build — is under Installation.

Three things in the data folder grow with use: the database copies kept for taking an update back, each a whole database, the compiled plugin code, and the database itself. rDownloader removes what is no longer needed ten minutes after every start — time for a fresh update to prove itself first — and once a day after that, and the card Update backups, plugin cache and database under Settings → System → Logs & retention does it on request.

• Before updates (pre-update/) and Before database upgrades (pre-migration/): behind a proven update only the newest file of each kind stays — the database copy and the encrypted backup before the update, and the copy the first start took before upgrading the database. Once those are older than Keep the newest copy — 14 days by default, 0 keeps them for good, at most 3,650 — they go too. An update rDownloader installed itself is proven once the new version answered as itself; one installed any other way once the new version runs. While the last update is not proven, or was taken back or failed, every copy stays and the card says so.
• Plugin cache (plugin-cache/): the compiled code of plugin versions no longer installed, code an older version of the plugin engine (Wasmtime) wrote, and beyond 256 MiB the code used least recently. A plugin whose code went is compiled again the next time it loads.
• Subscription archive: a skipped or dismissed subscription entry older than Keep skipped subscription entries whole — 30 days by default, 0 keeps everything, at most 3,650 — loses its title, link and details and keeps only what the subscription recognises it by. It leaves the subscription's archive and its counts, but a feed that still lists it brings nothing back. Open and queued entries are never touched. See Subscriptions.
• Database file: the space freed inside the file is handed back to the disk. A database created by 1.24 or later does this by itself during every clean-up.

The first clean-up after updating to 1.24 empties most of the plugin cache once. The cache knows which plugin an entry belongs to only for what it compiled from 1.24 on, so older entries count as unused; the next start compiles the plugins again and takes noticeably longer, once.

A database from before 1.24 is rewritten once. It cannot hand free space back by itself until it has been written anew, so the card says so, and Clean up now rewrites it — after that it is like a new one. The rewrite needs room in the data folder for a second copy of the database, and it waits for a quiet moment: while anything downloads, verifies, unpacks or records, it is refused (system.cleanup_rewrite_busy), and without the room as well (system.cleanup_rewrite_no_space). The rest of the clean-up runs either way; try again once everything is done. The automatic clean-up never rewrites the file.

Usenet and LinkGrabber progress no longer stays in the database at all: the interface still shows it live, but only the events that matter later are stored, for 30 days.

The card shows each kind's size and how much of it is removable — for the database, the stored events, the subscription archive with the number of entries to compact, and the file itself. Clean up now asks first, naming the size, and then says how much was freed. Downloads, settings and open subscription entries stay as they are; the clean-up is recorded in the audit log as Data folder cleaned up. Over REST it is GET /api/v1/system/cleanup (what would go) and POST with "confirmed": true; over MCP get_cleanup_preview and clean_up_data_directory, which asks you first. Both need api:admin.

A plugin installed or updated runs from the next start; rDownloader then offers Restart now — see Restarting when needed. Everything that matters is persisted. After a restart:

• the queue, packages, priorities and manual ordering are as they were;
• interrupted transfers resume from their last checkpoint;
• interrupted post-processing resumes at its step;
• torrent seeding resumes, and seed time keeps counting;
• a job running at a provider is picked up where it stood;
• sessions are still valid;
• a storage root blocked on free space stays blocked.

Three things are deliberately not persisted:

• A waiting captcha. The download behind it returns to the queue and raises a fresh challenge.
• An active IP block. The first free link of that hoster is tried once more and re-arms the block if the hoster still refuses.
• The event stream's replay buffer. A browser or agent that reconnects is normally handed what it missed; after a restart it is told there is nothing to replay.

rDownloader says in the sidebar when a new version is out; the portable archive and the Windows installer install it themselves, with a backup before it and the previous version back if the new one does not start. See Updates. By hand: stop the service, replace the program, start it again. Migrations run on the first start of the new version. Bundled plugins newer than the installed ones are installed automatically; plugins update from their repositories.

At every start, an installed plugin version that this rDownloader can no longer load is removed once a loadable version of the same plugin is installed. A version that cannot be removed — or a plugin with no loadable version at all — gets one warning per plugin in the log.

Back up data/ first — see Backup and restore; migrations are not designed to be undone.

Settings → About rDownloader, under Administration, names on the tab About the running build — Version, Commit, Built, Plugin contract and Platform — the build a bug report should quote. Below it are the project's addresses (source code, website, the handbook, the changelog and private vulnerability reporting), the author — Alexander Herling / DEGOYA.digital — and the thanks to the projects rDownloader is built on, with a link to the tab Licenses. That tab lists the licenses of everything the packages ship — rDownloader itself, the bundled helper tools and every shipped library — summarised by license and listed in full with Show all, filterable by name or license. An address that is not public yet reads not yet published.

The page is behind the sign-in (api:read); the public health check names only the version. The Linux and Windows packages carry the helper tools' license texts under vendor/licenses/.

Retention governs how old records age out; it does not give you a fresh start. For that, Settings → System → Logs & retention has a Clear button in each of the three cards — the service log, the audit log and the transfer statistics — each with the number of records currently stored beside it.

• Each store is cleared on its own; there is no "reset everything".
• The dialog (Clear the service log?, Clear the audit log?, Clear the transfer statistics?) says how many records will go and what stays: the other two stores, the downloads, the packages and the settings. Clear for good then reports how many records were removed.
• Clearing the audit log is itself audited. The first entry of the emptied log records the moment, the account that cleared it and how many records went.
• Clearing the statistics removes the all-time totals too, and the Prometheus counters built on them start again from zero. Tell your monitoring before you do it.

The notification delivery history has a Clear of its own, at the list in Settings → Notifications → History — see Notifications.

Each clear is also a REST call and an MCP tool; it needs the administration area and an explicit confirmation in the request. Downloaded files, the queue, accounts and categories stay as they are.

The header of Settings → System offers a global settings reset. It clears the configuration; it does not delete downloaded files, and it does not clear the audit log.

To start completely fresh, stop the service and remove the data directory — that destroys the queue, the history, the credentials and the installed plugins.

• Troubleshooting — symptom-first
• External tools
• Backup and restore
• Defaults and limits
• Reverse proxy
• Security and privacy — what redaction covers