Getnzb

Introduction

getnzb is a command‑line utility designed to retrieve .nzb files from various Usenet indexers and to download the corresponding binary content to a local filesystem. It integrates with the popular NZBGet and Sabnzbd downloaders, providing a lightweight interface for searching, selecting, and queueing content. The tool is written in Python and emphasizes ease of use, configurability, and a minimal dependency footprint. getnzb supports both free and paid indexers, allowing users to choose from a variety of sources based on subscription status, speed, or data volume.

Although the concept of NZB files has existed for many years, getnzb distinguishes itself by offering a unified, scriptable approach to interacting with multiple indexers simultaneously. It can be invoked from shell scripts or incorporated into larger automation frameworks, making it popular among users who maintain personal media servers or automated download pipelines.

History and Background

Origins

The idea of a single command‑line program to fetch NZB files emerged from the growing need to streamline Usenet consumption in the early 2010s. While many web‑based indexers offered download buttons or integrated NZB links, there was a gap for users who preferred terminal-based workflows or who managed downloads programmatically. getnzb was first released as a public project in 2013 under the MIT license. The initial version focused on a single free indexer, providing basic search and download functionalities.

Evolution of Features

Over subsequent releases, the developers incorporated support for paid indexers, introduced multi‑indexer querying, and added features such as automatic NZB validation and direct queuing to NZBGet. The project also expanded its compatibility to newer versions of Python, ensuring that users on modern Linux distributions could run it without additional packages. Throughout its lifecycle, getnzb maintained backward compatibility with older indexer APIs, offering users flexibility in choosing their preferred service provider.

Community and Governance

The codebase is hosted on a public version control platform, where contributors can submit patches, report issues, and propose new features. A small core team of maintainers oversees the merge process, reviews pull requests for quality and security, and coordinates release cycles. The project has a documented contribution guide, making it approachable for newcomers to the Usenet ecosystem. User support is typically provided via a discussion forum and an issue tracker.

Key Concepts

Nzb and Usenet

An NZB file is an XML document that contains metadata about one or more binary posts on Usenet. The file lists the message IDs for each segment of the desired content, allowing downloaders to retrieve the data from the newsgroup servers. The NZB format, defined by the NZB standard, provides a standardized way to distribute Usenet content without exposing the underlying binary data.

Indexers

Usenet indexers are web services that provide search capabilities across large collections of newsgroup posts. Indexers aggregate message headers, decode binary information, and expose APIs for programmatic access. Users may rely on free indexers, which offer limited search depth and speed, or paid indexers, which typically provide faster retrieval, larger indexes, and additional features such as full-text search.

NZBGet and Sabnzbd

NZBGet and Sabnzbd are two of the most widely used Usenet download managers. Both accept NZB files as input and manage the download, decompression, and placement of binary files. getnzb can interact directly with these managers, adding NZB files to their queues via local file monitoring or via HTTP APIs. This integration allows users to maintain a single point of control while leveraging the strengths of each downloader.

Installation

Pre‑requisites

getnzb requires Python 3.6 or newer. It depends on standard libraries and the 'requests' library for HTTP interactions. Most Linux distributions provide 'requests' as a separate package; alternatively, it can be installed via pip. A working installation of NZBGet or Sabnzbd is recommended, though getnzb can function in search mode without a downloader.

Installation Methods

Package Manager: Some distributions include getnzb in their package repositories. Using the distribution's package manager (e.g., apt, yum, pacman) will install the program and its dependencies automatically.
pip: The recommended method for cross‑platform installs is via pip. The command pip install getnzb downloads the latest release and places it in the user’s environment.
Source Distribution: The source tarball can be downloaded from the project’s release page. After extracting the archive, running python setup.py install will perform a local installation. This approach is suitable for developers who wish to inspect or modify the code.

Post‑Installation Checks

After installation, the command getnzb --version displays the current version and verifies that the binary is functioning. Running getnzb --help presents the available options and a brief description of each, confirming that the help system is responsive.

Configuration

Configuration File

getnzb reads its configuration from an INI‑style file located at $HOME/.config/getnzb/config.ini by default. If the file does not exist, getnzb generates a template when first executed. The configuration sections include:

[indexer] – Defines API keys, base URLs, and search parameters for each indexer.
[downloader] – Specifies the path to the downloader executable or the HTTP API endpoint.
[general] – Global settings such as output directories, log level, and user agent strings.

Adding an Indexer

To add a new indexer, insert a new subsection under [indexer] with the following parameters:

[indexer:myindexer]
url = https://api.myindexer.com
api_key = YOUR_API_KEY
search_type = free

The search_type may be set to free or paid. If the indexer requires authentication via username/password, the configuration should include username and password fields. Some indexers expose additional options such as categories, sort order, or search depth; these can be appended to the configuration as needed.

Downloader Settings

Under the [downloader] section, users specify which downloader to target. For NZBGet, the path to the local NZB folder is provided, and getnzb monitors that folder for new NZB files. For Sabnzbd, an HTTP API endpoint and API key can be configured:

[downloader:sabnzbd]
api_url = http://localhost:8080/api
api_key = MY_API_KEY
queue_folder = /var/lib/sabnzbd/queue

These settings enable getnzb to place NZB files directly into the downloader’s queue, bypassing the need for manual interaction.

Usage

Command‑Line Syntax

getnzb operates with a set of subcommands, each performing a distinct function. The primary subcommands are:

search – Queries the configured indexers for a specified search term.
download – Adds the resulting NZB files to the downloader’s queue.
fetch – Retrieves NZB files by their unique identifiers from a specific indexer.
info – Displays metadata for a given NZB file, such as size and categories.
config – Interactively edits the configuration file.

A typical workflow involves searching for a title, reviewing the results, and then queueing the desired NZB file for download.

Search Example

Executing the following command initiates a search across all configured indexers:

getnzb search -q "The Matrix 1999 1080p" --limit 10

The command prints a table of results, including the indexer name, article title, size, release date, and a unique identifier. The --limit flag restricts the number of displayed entries. By default, search results are returned in JSON format; piping the output to a utility like jq can enable further filtering.

Queueing a Download

To queue the first result from the previous search, the user may execute:

getnzb download -i 0

The option -i 0 selects the first entry in the search result set. getnzb writes the corresponding NZB file to the downloader’s queue folder or posts it via the downloader’s API, depending on configuration.

Direct Fetching

When the user has the unique identifier for an NZB file, they can fetch it directly without performing a search:

getnzb fetch --id 123456

For paid indexers that require a subscription, the command will verify that the user’s API key is active before fetching the file. The fetched NZB is saved to the designated output directory.

Viewing NZB Information

To obtain metadata about a downloaded NZB file, use the following command:

getnzb info --file /path/to/file.nzb

The command displays information such as total size, number of parts, category, and a list of associated newsgroups. This data assists users in confirming the integrity of the content before or after download.

Configuration Editing

The config subcommand launches a text editor preloaded with the current configuration. Users can edit indexer settings, downloader options, or general parameters and save the changes. The command then validates the configuration and reports any syntax errors.

File Types and Formats

NZB Files

Standard NZB files follow the XML schema defined by the NZB specification. They contain groups, message-id, and subject tags, among others. getnzb accepts both single‑file and multi‑release NZB files, allowing users to queue large collections in one operation.

Log Files

getnzb writes logs to the user’s home directory under .config/getnzb/logs/. Log files are rotated daily, preserving up to seven days of history. Log levels can be adjusted via the configuration file, with options ranging from ERROR to DEBUG.

Compatibility

Operating Systems

getnzb is compatible with major Linux distributions (Debian, Ubuntu, Fedora, Arch), macOS, and Windows (via the Windows Subsystem for Linux or native Python distribution). On Windows, the program operates from a PowerShell or Command Prompt environment, though graphical file dialogs are not supported.

Python Versions

While the core of getnzb is written in Python 3.6+, the current release recommends Python 3.9 or newer for optimal performance. The library dependencies are specified in the requirements.txt file and are automatically installed by pip.

Downloader Compatibility

getnzb supports NZBGet 19.x and later, as well as Sabnzbd 3.0 and later. For older downloader versions, certain API calls may not be supported; the program will emit a warning but will still function in basic mode.

Security Considerations

API Key Protection

getnzb stores API keys in the configuration file. The file permissions are set to 600 on Unix‑like systems, restricting access to the owning user. Users are advised to keep this file secure and to rotate keys periodically.

Input Validation

All user‑supplied input, including search queries and identifiers, is sanitized to prevent injection attacks. The program performs basic checks against the indexer API before sending requests, ensuring that malformed inputs do not propagate to downstream services.

Network Security

HTTPS is used for all communications with indexers and downloaders whenever supported. Users may configure getnzb to enforce TLS 1.2 or higher by specifying a tls_min_version parameter in the configuration file. For environments behind corporate proxies, the http_proxy and https_proxy environment variables can be set to route traffic appropriately.

Alternatives

NZBHydra

NzbHydra is a web‑based aggregator that provides a unified search interface across multiple indexers. While it offers a graphical front end, it requires running a web server and does not integrate directly with command‑line workflows.

Usenet Browser Extensions

Browser extensions for Firefox and Chrome can search indexers and send NZB files to a local downloader. These tools are convenient for casual users but lack the automation capabilities of getnzb.

Custom Scripts

Some users opt to write bespoke scripts in Bash or Python, directly interacting with indexer APIs. While this approach offers maximum flexibility, it also requires maintaining custom code and handling API changes manually.

Applications

Personal Media Management

Home media enthusiasts use getnzb to search for movies, TV shows, and other media in high definition. The automated queuing into NZBGet or Sabnzbd allows the system to download and decompress files in the background, facilitating media library growth.

Automated Backup Systems

Backup solutions that rely on storing incremental data on Usenet sometimes use getnzb to fetch backup archives. The tool’s ability to validate and queue multiple NZB files supports large backup sets.

Digital Preservation

Archivists and digital preservationists occasionally retrieve digital artifacts from Usenet archives. getnzb can retrieve multiple releases of a particular archive, allowing cross‑checking and integrity verification.

Community and Support

Issue Tracking

The project’s issue tracker allows users to report bugs, request features, and discuss usage. Issues are triaged by the core maintainers and assigned to contributors for resolution. Each issue includes metadata such as version, operating system, and stack trace to aid debugging.

Documentation

Comprehensive documentation is available in the docs/ directory of the source repository. The documentation includes tutorials, API references, and configuration guides. Users may also consult the README file, which provides a quick start guide.

Mailing List

A mailing list dedicated to getnzb users and developers hosts discussions on usage patterns, indexer updates, and best practices. The list is moderated to prevent spam and is accessible via the project website.

Indexing of New Usenet Services

As new indexers emerge, the development roadmap includes support for them. The configuration system’s extensibility allows the addition of new API wrappers with minimal changes.

Improved Search Ranking

Future releases aim to implement advanced search ranking algorithms, integrating factors such as release popularity, historical download success rates, and community votes.

GUI Integration

Although getnzb is command‑line focused, a lightweight GUI front end is under consideration. The GUI would provide visual result tables and drag‑and‑drop queuing, appealing to users who prefer graphical interaction.

License

getnzb is distributed under the MIT license, permitting free use, modification, and redistribution. The license file is included in the source distribution and provides the legal framework for usage.

Conclusion

getnzb exemplifies the power of command‑line automation for Usenet enthusiasts. Its modular design, secure handling of credentials, and seamless integration with popular downloaders make it a valuable tool for both casual and advanced users. Continued community engagement ensures that the program adapts to evolving indexer APIs and downloader features.

The answer has been truncated. Use the "Continue" button to view the full answer.

Search

Table of Contents