usenet - degoya/rDownloader GitHub Wiki

Usenet and NZB

rDownloader has a native NNTP client: NZB files are imported, reviewed and downloaded on the same queue as everything else, with yEnc decoding, CRC verification, segment-level resume and PAR2 repair. No external Usenet client is involved.

You need at least one NNTP server before anything can download. Configure servers under Settings → Usenet.

Setting up servers

Settings → Usenet on its Servers tab, beside Indexers: the form for a new NNTP server, its provider connections a number field with minus and plus, beside a server chain of demo servers in fallback order, the first one switched on and showing how many of its connections are busy while a Usenet download runs

Settings → Usenet holds a server chain. Per server:

Field Notes
Host and port
TLS
Username and password Stored in the encrypted vault
Provider connections The maximum this provider allows you, across all requests. The Usenet files running at once share them, unless NNTP connections per server lowers the number per server
Proxy An existing SOCKS5 proxy profile

Servers are ordered by priority — move a row up or down — and each one can be enabled or disabled without deleting it. Duplicate copies a server under a free name and opens the copy in the form; the password is not copied and has to be entered again. The chain is a fallback order: an article missing on the first server is asked of the next.

While something downloads, each server card shows N busy beside its provider connections: the connections fetching an article from that server right now, shared by every running file.

Test checks the whole path: proxy, TCP, TLS and login. Do that before queueing anything. A certificate authority you configured under Settings → Network → Proxies & TLS applies to NNTP as well as to web and FTP downloads, including to this test.

Traffic and quota per server

Every server row shows what that server delivered today (since midnight UTC), over the last 30 days and in total — the same figures the Statistics tab lists for all servers.

A block account or a plan with a volume gets a quota: Set quota on its row takes

Field Notes
Volume In GiB. What the server may deliver before the action applies
When used up Use only as backup — asked only for articles the other servers do not have, which is how a block account is meant to be used. Pause the server — not asked at all
Reset on (optional) On this day the used figure starts again at zero, once — set the next day after it

The bar under the row fills as the volume is used. Reset usage starts the figure at zero now, for example after you bought a new block; Remove quota drops it. The figure counts from the moment the quota is set, and it is the server's own: clearing the statistics does not touch it.

When the volume is used up, a usenet_quota_reached notification goes out once, and the action applies from the next file on — a file already being fetched finishes over the servers it started with. The quota is checked every ten seconds, so a server can go a little past its volume. Raising the volume, resetting the usage or the reset day gives the server back at once. If every enabled server is paused, Usenet downloads wait — they show Every enabled Usenet server is paused because its quota is used up and try again every 15 minutes — instead of failing.

What is counted is what the server sent: the article bodies as they come over the wire, a few per cent more than the files they make, and an article fetched twice because it arrived damaged counts twice. That is what a provider meters too. rDownloader cannot ask your provider how much is left on the account; the figure is its own count since you set the quota.

Indexers

An indexer is where NZBs are found — or torrents, from a Torznab indexer such as Jackett or Prowlarr. Define each one once under Settings → Usenet → Indexers:

Field Notes
Name How the search and the subscription form call it
API address The Newznab or Torznab API base, e.g. https://api.omgwtfnzbs.org/api, or a Jackett indexer's Torznab feed (http://jackett:9117/api/v2.0/indexers/all/results/torznab/). An NZBHydra, Jackett or Prowlarr on your own network works too
API key Stored in the encrypted vault and never shown again. Leave it empty when editing to keep it
Default categories What a search asks for when it names no category. Load categories from the indexer fills the choice
Search list style Compact — one line per hit — or Detailed, with a small cover and the indexer's metadata (see below). Compact unless you choose otherwise
Enabled Only enabled indexers are searched

Test asks the indexer for its capabilities (t=caps) with the stored key and says how many categories it offers — the cheapest request that proves address and key.

Searching indexers from the LinkGrabber

Search indexers in the LinkGrabber's top bar — or f from any page, which goes to the LinkGrabber first — opens the search in a drawer, with the keyboard in its field. Until at least one indexer is enabled under Settings → Usenet → Indexers, the field is disabled and a hint below it links there — an indexer subscription alone is not searched, the indexer has to be defined once (above); f then lands on that link. With an indexer enabled, choose one indexer or all of them, then:

  • Search term — sent as q, as you wrote it: !word excludes a word. Leave it empty for the newest releases, otherwise use at least three characters; a shorter term is refused before anything is sent, because the indexer would refuse it too.
  • Categories — category ids such as 5040; empty uses each indexer's default categories.
  • Search type — Free search, TV series or Film (see below).
  • Max. age in days, Hide passworded (pw=2) and hits per page (50 to 500).

A TV series search (t=tvsearch) takes the season, the episode and the series' TVDB, TVmaze or IMDb id; a Film search (t=movie) takes the film's IMDb (tt0133093 or just the digits) or TMDb id. You type the ids in — rDownloader looks nothing up — and with them the search is as exact as Sonarr's or Radarr's. Only what the chosen indexers can do is offered: the first time you open the search type, rDownloader asks them for their capabilities, then switches off a type none of them answers and shows only the ids one of them takes. A typed search goes only to the indexers that answer it; when none does, nothing is sent and the panel says so.

Search sends one request per indexer — never more, and nothing is searched while you type. Indexers count requests against a daily limit, and some keep an answer for ten minutes, so the next page is the arrows' next request rather than anything automatic. The hits come in a table you sort by title, size, age or category; a lock marks a release the indexer calls passworded. A long release name is cut with an ellipsis — point at it for the whole name — so the download button always stays in view; on a phone the table scrolls sideways with that button pinned to the right edge. An indexer that refuses — a wrong key, a rejected search, a reached limit — is named above the table with its reason, while the others' hits still show.

An indexer set to the Detailed list style draws its hits with a small cover left of the title and, under it, one line of what the indexer sends along — year, genre, IMDb score, language, resolution and a short description; point at the line to read all of it. Size, age, category and the download button stay where they are. The covers load only while Show cover images is on (Settings → Interface → Display, the same switch the subscription hits follow); without one, or when it does not load, the row shows the rDownloader mark in its place, so the titles still start in one column. Searching all indexers, each hit follows its own indexer's style. Which indexers send covers and metadata differs — set the style per indexer where it pays off.

Press the download button at the end of a row for that one release, or tick the releases you want and press Add selected: rDownloader fetches each NZB with the indexer's key and imports it exactly like an uploaded file, so it appears in the LinkGrabber's list for review. The drawer stays open, so you can take more and page on; closed, it keeps your search and its hits. The row's button shows how it went — busy while the NZB is fetched, a check mark once it is in the list, a warning sign when it could not be fetched (press it again to retry). The key never reaches the browser — a hit's address carries a placeholder where the key stands, and it is put back only for the indexer's own server.

A hit from a Torznab indexer is marked Torrent and shows its seeders (arrow up) and leechers (arrow down). Adding it puts the torrent into the LinkGrabber as a package, the way an uploaded .torrent or a pasted magnet arrives: rDownloader fetches the .torrent from the indexer with its key, or takes the hit's magnet — also when the download only leads to a magnet, as Prowlarr's does for trackers that have nothing else. The BitTorrent service has to be switched on.

An indexer subscription can take a defined indexer over, together with a search term of its own.

Importing an NZB

Any of these work:

  • Import in the LinkGrabber, or the n shortcut.
  • Drag the file anywhere into the application.
  • Double-click the .nzb file, once the capture agent has installed the file association.
  • Drop it into a watched folder.
  • POST it to the REST API — as an upload, or as JSON with the file in base64 (at most 48 MiB that way), which is also how the MCP tool import_nzb hands one in.

An .nzb can also be handed to a TorBox or Premiumize.me account instead, which fetches it there and returns the files as links — see Remote jobs.

The limit is 64 MiB per NZB file.

The import dialog asks for package name, category, priority and archive password, and shows the file list and segment counts before anything is queued. Whether a password was detected, and whether this NZB is a duplicate, is shown too.

Import lands in the LinkGrabber for review, next to collected links — it is one list, not a separate Usenet screen.

NZB history

Every imported NZB is recorded with its status, size and date. Deleting an entry from the history makes the same NZB importable again — that is the switch that turns duplicate detection off for one file.

An NZB that will not parse is recorded too, as a failed import with its reason, and shown in the LinkGrabber as a row naming the file. Its failed badge opens the import with its error, its files and its steps — and says so when the service reported no reason at all. It cannot be queued; delete the row to import the file again.

An archive password written into the NZB is used for extraction, whatever route the NZB came in by. An explicit package password or a {{password}} marker in the file name still wins.

The history is kept by default. Switched off — Keep import history under Settings → System → Logs & retention — an entry is removed once its download finishes, and a re-imported NZB is no longer recognised as a duplicate.

How the download works

Settings → Usenet below the server chain: NNTP connections per server left at using every connection the servers allow, the hint how the files running right now share them, and Usenet files at once

  • The Usenet files running at once share the providers' connections. By default they use every connection the enabled servers allow. The setting is NNTP connections per server under Settings → Usenet, below the servers; its default 0 means exactly that, and a lower number lowers the connections per server that all running Usenet files share together. The hint under the setting says whether the value binds and what the largest enabled server allows — and while files run, how they split the connections at this moment, for example Right now 2 files with 5 of 10 connections each.
  • Several Usenet files download at once, so every connection stays busy across file boundaries. The setting is Usenet files at once under Settings → Usenet. The default 0 is automatic — between two and eight files, fewer when they are large; a fixed value from 1 to 8 is possible too. However many run, all Usenet files together take one slot of Simultaneous downloads, because they share the server connections.
  • Segments are yEnc-decoded and CRC-checked, both per segment and for the complete file.
  • File names are reconstructed from the yEnc header and the Subject line, which is what makes obfuscated posts usable.

Resume

After a restart the segments already on disk are CRC-checked again and only the missing ones are fetched. A crash costs at most the last few articles. An existing final file is validated against all segment CRCs before it is accepted.

A server that cannot answer costs nothing

Only a refusal that means this server does not have the article leaves a hole for PAR2 to close. Anything else — a server that is temporarily offline, a body that does not decode, a connection that breaks mid-article — is retried on a fresh connection, three times, with a growing pause. If no server delivers, the file goes back into the queue as a retryable failure with its partial data intact, rather than being called complete while full of zeros.

What a server sends is checked against the NZB: an article whose yEnc header announces a file size outside what the NZB counts for that file is refused (usenet.declared_size_implausible), and the holes of articles every server refused are filled only while the disk keeps its free-space reserve — otherwise the file waits and is tried again (usenet.gap_fill_no_space).

PAR2 and post-processing

PAR2 files are detected by name and by content, so a renamed or obfuscated recovery set still works. Renaming a file yourself re-decides the marking.

When the articles of a fully obfuscated file disagree on its yEnc name, the NZB subject decides the name, as in SABnzbd, and the log says so once per file.

A file with missing segments waits for its PAR2

A payload file that finishes with segments missing does not fail at once. It waits in Verifying, saying how many segments are missing, until the rest of the package has settled. Then repair data present sends it to repair; none fails it. A restart in the middle keeps the assembled file. A waiting file can be cancelled, removed or deleted like any other row.

Recovery volumes are fetched only when they are needed

An NZB's vol recovery volumes are postponed — shown as Postponed in the queue — rather than downloaded whether or not anything is damaged. If PAR2 verification reports missing blocks, only as many volumes as are needed are released, smallest first, and the pipeline runs again once they land. The main index is never postponed. Where the postponed volumes cannot cover the gap, the step reports the blocks needed against the blocks available.

Download all PAR2 volumes under Settings → Post-processing → Repair & cleanup fetches every volume instead. It is off by default, as it is in SABnzbd.

A recovery volume whose segments are all gone is not counted as an error and raises no notification; a missing payload file still fails the package and notifies.

A download that cannot be repaired stops early

When more is missing than the recovery volumes can repair, rDownloader stops the download instead of fetching the rest of it, like SABnzbd's fail_hopeless_jobs. On a block account that is volume you do not pay for. After every file that finished with holes, it counts the PAR2 blocks the missing articles have cost at least against the blocks every vol volume of the set can supply at most — downloaded, still queued or postponed alike. When the missing blocks are more, the waiting files fail, the running ones stop, and the package ends failed with the reason Beyond repair: 9 PAR2 blocks are missing and at most 1 are available to repair them. What was downloaded stays on disk; retrying a file puts the package back into the queue.

Only an article every server refused counts — one your primary lacks and a backup server delivers is not missing. And where the set does not say enough to be sure — obfuscated file names still to come, recovery data without a block count in its name, or no vol volume at all — the download carries on and the PAR2 step decides at the end.

It is on by default; Abort hopeless Usenet downloads under Settings → Post-processing → Repair & cleanup switches it off. A notification rule or an automation can react to it with the event usenet_job_hopeless.

Verification and repair are followed by unpacking if the package's post-processing level asks for it.

The full pipeline — levels, SFV verification, the RAR integrity test, cleanup and user scripts — is on Post-processing.

Controls and statistics

Usenet packages sit in the same Downloads view as everything else, with the same priorities, the same global speed limit, the same bulk actions and the same statistics. A package carrying an NZB is marked Usenet, and its segments can be inspected from the package header.

Connections at work

A Usenet package opened in the download queue while it downloads: in its header the connections icon with the connections busy for its files instead of the active files, each running file with its own connections, and the next file of the package waiting in the queue

A Usenet package does not count its running files the way other packages do. Its header shows a connections icon with the number of connections busy for its files, because those connections are what the files share — two files at once that hold all ten connections of your server, five each, are using everything there is. Hover the number for the split, for example 10 connections: 2 files at once, 5 each, or the shares in brackets when the split is uneven, followed by whether the servers' limit is reached: All 10 connections the servers allow are busy, or how many of them are. While no connection is busy — the package is verifying or repairing — the header falls back to the number of active files.

Expand the package and each running Usenet file shows its own connections the same way. A connection two files share counts half for each, so the files never add up to more than the servers have busy. Each server card under Settings → Usenet shows its N busy at the same time.

Switching Usenet off

Settings → Services → Usenet switches the whole service off. NZB links are then refused at intake, and anything already queued moves to Blocked with that reason. Switching it back on returns those entries to the queue.

Related pages

⚠️ **GitHub.com Fallback** ⚠️