# How qBittorrent Handles Tracker Communication Protocols: Embedded HTTP Tracker Implementation > Discover how qBittorrent handles tracker communication through its embedded HTTP tracker. Learn about peer registries and BEP compliant bencoded responses. - Repository: [qBittorrent project/qBittorrent](https://github.com/qbittorrent/qBittorrent) - Tags: internals - Published: 2026-05-05 --- **qBittorrent handles tracker communication protocols through a built-in HTTP tracker that processes `/announce` requests, maintains per-torrent peer registries, and returns bencoded responses compliant with BEP-3, BEP-7, BEP-23, and BEP-24.** qBittorrent implements standard BitTorrent tracker communication protocols via a lightweight embedded HTTP server that runs inside the client process. This server, encapsulated in the `BitTorrent::Tracker` class within `src/base/bittorrent/`, manages peer discovery by parsing announcement parameters, tracking peer states, and generating protocol-compliant responses without relying on external tracker infrastructure. ## Architecture of the Built-in Tracker The tracker implementation follows a modular design that separates HTTP transport from BitTorrent protocol logic. ### The Tracker Class Structure The core tracker functionality resides in the `BitTorrent::Tracker` class defined in [`src/base/bittorrent/tracker.h`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/tracker.h) (lines [71-78](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.h#L71-L78)). This class inherits from both `QObject` and `Http::IRequestHandler`: ```cpp class Tracker final : public QObject, public Http::IRequestHandler ``` This dual inheritance allows the tracker to integrate with Qt's object model while implementing the interface required by qBittorrent's minimal HTTP server framework. The `Http::IRequestHandler` interface enables the server to delegate incoming requests directly to the tracker instance for processing. ### Server Initialization and Port Configuration The embedded HTTP server initializes in the tracker constructor and begins listening via the `Tracker::start()` method implemented in [`src/base/bittorrent/tracker.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/tracker.cpp) (lines [95-129](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L95-L129)): ```cpp bool Tracker::start() { const int port = Preferences::instance()->getTrackerPort(); // user-configurable port ... m_server->listen(QHostAddress::Any, port); } ``` The server binds to all available network interfaces (`QHostAddress::Any`) using a port retrieved from user preferences. The `m_server` object is instantiated in the constructor as `new Http::Server(this, this)`, passing the tracker itself as the request handler. ## Processing Tracker Communication Protocols All tracker communication follows the BitTorrent specification, beginning with HTTP request handling and parameter validation. ### Request Routing and Validation Incoming HTTP requests enter through `Tracker::processRequest` (starting at line [30](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L30)): ```cpp Http::Response Tracker::processRequest(const Http::Request &request, const Http::Environment &env) { if (request.method != Http::HEADER_REQUEST_METHOD_GET) throw MethodNotAllowedHTTPError(); if (request.path.startsWith(ANNOUNCE_REQUEST_PATH, Qt::CaseInsensitive)) processAnnounceRequest(); // ← main entry point for tracker comms else throw NotFoundHTTPError(); } ``` The tracker strictly enforces **GET** requests only, rejecting other HTTP methods with `MethodNotAllowedHTTPError`. Valid requests must target the `/announce` endpoint defined by the constant `ANNOUNCE_REQUEST_PATH` (`"/announce"`); any other path triggers `NotFoundHTTPError`. ### Parsing Announce Parameters `processAnnounceRequest()` extracts mandatory and optional query parameters defined by the BitTorrent specification: | Parameter | Protocol Meaning | Implementation Location | |-----------|------------------|-------------------------| | `info_hash` | 20-byte SHA1 torrent identifier | Lines [90-99](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L90-L99) | | `peer_id` | 20-byte peer identifier | Lines [101-108](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L101-L108) | | `port` | Peer listening port | Lines [110-119](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L110-L119) | | `compact` | Request compact peer list (default `true`) | Lines [138-140](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L138-L140) | | `no_peer_id` | Omit peer IDs from response | Line [133](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L133) | | `event` | Lifecycle event (`started`, `stopped`, `completed`) | Lines [153-167](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L153-L167) | | `left` | Bytes remaining (determines seeder status) | Line [136](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L136) | | `numwant` | Desired number of peers | Lines [122-129](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L122-L129) | | `ip` | Optional self-reported IP address | Lines [78-84](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L78-L84) | Parsed data stores in the internal `TrackerAnnounceRequest` struct (defined at lines [46-57](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L46-L57)) before processing peer registration logic. ## Peer Lifecycle Management The tracker maintains accurate peer lists by processing lifecycle events according to the `event` parameter. ### Registration and Deregistration Logic Based on the `event` value parsed at lines [153-167](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L153-L167): - **`started`**, **`completed`**, **`paused`**, or empty → `registerPeer()` (lines [162-166](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L162-L166)) - **`stopped`** → `unregisterPeer()` (lines [167-170](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L167-L170)) `Tracker::registerPeer` inserts peers into per-torrent containers, while `Tracker::unregisterPeer` removes them and cleans up empty torrent entries. Both helpers are defined around lines [180-200](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L180-L200) in [`tracker.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/tracker.cpp). ### Torrent Statistics Containers The tracker organizes peers using a `TorrentStats` structure containing a `QSet` for each active torrent. This container tracks **seeders** (peers with `left=0`) and **leechers** (peers with `left>0`) separately, enabling accurate reporting in announce responses. ## Constructing Bencoded Responses After processing peer registration, `prepareAnnounceResponse()` assembles a **bencoded dictionary** with mandatory tracker response fields. ### Response Fields and Intervals The response dictionary includes these keys (implemented around lines [408-414](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L408-L414)): - **`interval`** – Re-announce interval set to 30 minutes (lines [408-409](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L408-L409)) - **`complete`** – Number of seeders (line [410](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L410)) - **`incomplete`** – Number of leechers (line [411](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L411)) - **`external ip`** – Client's external IP per BEP-24 (lines [413-414](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L413-L414)) ### Compact and Non-Compact Peer List Formats The tracker supports both response formats as specified in BEP-7 and BEP-23: **Compact format** (default, when `compact=1`): - Binary string of 6-byte IPv4 entries (4-byte IP + 2-byte port) or 18-byte IPv6 entries (16-byte IP + 2-byte port) - Implementation at lines [227-237](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L227-L237) **Non-compact format** (when `compact=0`): - Bencoded list of dictionaries containing `ip`, `port`, and optional `peer id` (controlled by `no_peer_id` parameter) - Implementation at lines [245-265](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L245-L265) The final dictionary is encoded using `lt::bencode` and written to `m_response.content` (lines [271-276](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L271-L276)). ## Protocol Compliance and Error Handling The tracker enforces protocol compliance through strict validation and structured error responses. Missing or malformed parameters raise `TrackerError` exceptions (derived from `RuntimeError`). These exceptions are caught in `processRequest()` and converted to bencoded `failure reason` fields (lines [56-69](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L56-L69)). HTTP-level errors throw `MethodNotAllowedHTTPError` or `NotFoundHTTPError`, which the framework converts to appropriate HTTP status codes (405 and 404 respectively). ## Practical Implementation Example The following example demonstrates starting the embedded tracker and sending a compliant announce request: ```cpp // tracker_start.cpp #include #include #include #include #include "base/bittorrent/tracker.h" int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); // 1️⃣ Start the built-in tracker BitTorrent::Tracker tracker; if (!tracker.start()) { qCritical() << "Failed to start embedded tracker"; return 1; } // 2️⃣ Build an announce URL (matching the tracker's listening port) QUrl announceUrl(QStringLiteral("http://127.0.0.1:%1/announce") .arg(Preferences::instance()->getTrackerPort())); QUrlQuery query; query.addQueryItem(QStringLiteral("info_hash"), QStringLiteral("0123456789abcdef0123456789abcdef01234567")); query.addQueryItem(QStringLiteral("peer_id"), QStringLiteral("-QT0001-123456789012")); query.addQueryItem(QStringLiteral("port"), QStringLiteral("6881")); query.addQueryItem(QStringLiteral("uploaded"), QStringLiteral("0")); query.addQueryItem(QStringLiteral("downloaded"), QStringLiteral("0")); query.addQueryItem(QStringLiteral("left"), QStringLiteral("0")); query.addQueryItem(QStringLiteral("compact"), QStringLiteral("1")); announceUrl.setQuery(query); // 3️⃣ Send the GET request QNetworkAccessManager nam; QNetworkReply *reply = nam.get(QNetworkRequest(announceUrl)); QObject::connect(reply, &QNetworkReply::finished, [&]() { QByteArray body = reply->readAll(); qInfo() << "Tracker response (bencoded):" << body; reply->deleteLater(); app.quit(); }); return app.exec(); } ``` This example uses the same parameter names and constants that `Tracker::processAnnounceRequest()` expects, demonstrating peer registration, interval calculation, and compact peer list generation. ## Summary - **qBittorrent implements tracker communication protocols** via the `BitTorrent::Tracker` class in [`src/base/bittorrent/tracker.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/tracker.cpp), acting as an embedded HTTP server. - **Request processing** strictly follows BitTorrent specifications, accepting only GET requests to `/announce` and validating mandatory parameters like `info_hash`, `peer_id`, and `port`. - **Peer management** uses `registerPeer()` and `unregisterPeer()` to maintain per-torrent `QSet` containers, tracking seeder and leecher counts. - **Response generation** produces bencoded dictionaries with `interval`, `complete`, `incomplete`, and either compact binary or non-compact dictionary peer lists per BEP-7 and BEP-23. - **Error handling** converts validation failures into bencoded `failure reason` responses and HTTP protocol violations into appropriate status codes. ## Frequently Asked Questions ### What BitTorrent protocol extensions does qBittorrent's embedded tracker support? According to the source code in [`src/base/bittorrent/tracker.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/base/bittorrent/tracker.cpp), the embedded tracker implements **BEP-3** (base tracker protocol), **BEP-7** (IPv6 support), **BEP-23** (compact peer lists), **BEP-24** (external IP indication), and **BEP-21** (extensions for partial seeders). ### How does the tracker determine whether a peer is a seeder or leecher? The tracker examines the **`left`** parameter from the announce request (line [136](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L136)). If `left` equals zero, the peer is classified as a **seeder** (complete) and increments the `complete` counter; otherwise, it is classified as a **leecher** (incomplete) and increments the `incomplete` counter. ### Can the embedded tracker handle IPv6 peers? Yes. The tracker supports IPv6 through **BEP-7** implementation. When `compact=1`, IPv6 peers are encoded as 18-byte binary strings (16 bytes for IPv6 address plus 2 bytes for port) placed in the `peers6` field of the bencoded response, while IPv4 peers use 6-byte encoding in the `peers` field. ### What happens when a peer sends the "stopped" event? When `event=stopped` is received (line [167](https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/tracker.cpp#L167)), the tracker calls `unregisterPeer()` to remove the peer from the torrent's peer set. If this results in an empty peer set for that torrent, the tracker deletes the torrent entry from its internal registry to free resources.