Field Note
Tor Guard Relay v2.2.1: New DoS Defenses and Verified Source Builds
Tor’s security fixes need to reach the process running on a relay. A new image tag, a green build or a torrc reload cannot establish that on its own.
I’ve released Tor Guard Relay v2.2.1 with Tor 0.4.9.15: new directory-request defenses, authenticated upstream source builds and an upgrade that preserves the relay’s existing identity. Relay and bridge operators should upgrade as soon as possible.
The v2.2.1 release
is the starting point for release notes and retained evidence. After pulling an image, recreate the container and check tor --version; an image reference alone does not establish which binary is running.
🛡️ Why this Tor update matters
The Tor Project’s announcement asks operators to upgrade as soon as possible, especially relays and bridges. Tor 0.4.9.15, released on 28 October 2026, adds defenses against the large volume of directory requests hitting the network.
🔎 What relay operators measured
Three reports from 1AEO, a separate relay operator, help explain why directory work needs attention:
- Their traffic-path overview maps reported pressure across circuit setup, directory requests and other relay roles. Setup work can exhaust CPU or memory while application bandwidth barely changes. A bandwidth graph alone can miss the bottleneck.
- Their BEGIN_DIR measurements recorded 3.62 billion directory-stream starts across 775 relays reporting HSDir or V2Dir in a 48-hour window ending on 21 October 2026. The counter combines different directory operations; it cannot classify intent or establish that each start became a completed request.
- Their detailed request study examined 29 flood periods on 23 relays using custom metrics on Tor 0.4.9.14. Some periods were dominated by descriptor fetches; others by streams that closed while Tor was still waiting for an HTTP request. The dominant pattern could change on the same relay.
These are 1AEO’s observations, not measurements from my relay fleet. Their detailed study describes the older release, so it does not measure the effectiveness of Tor 0.4.9.15’s controls. It does show why operators should consider CPU, memory, circuit activity and directory work alongside bandwidth when investigating overload.
🛡️ What Tor 0.4.9.15 changes
BEGIN_DIR cells request directory information over a circuit. The new behavior makes that work harder to abuse:
| Defense | What changes |
|---|---|
| Per-circuit BEGIN_DIR rate limit | Enabled by default for directory caches, including relays and bridges; the network consensus controls its settings. |
| One BEGIN_DIR per circuit | Applies to circuits from authenticated relays. Initially disabled and controlled only by the consensus, so operators should not enable it individually. |
| One HSDir request per circuit | For circuits from authenticated relays, a later descriptor fetch or upload on the same circuit closes it. This defense remains active independently of the preceding limit. |
HSDir eligibility also becomes sticky across qualifying restarts. A relay still needs 96 hours of uptime to qualify initially, must remain in the consensus and must satisfy the other requirements. A restart does not automatically guarantee an HSDir flag.
Upstream also updates required protocol capabilities, excluding Tor 0.4.8 and earlier. Its corrected release notes document TROVE-2026-072, a directory-authority consensus bug, plus channel-padding and client retry fixes omitted from the original notes. The correction changes documentation and version metadata, without changing runtime source relative to the release tag.
These defenses reduce abusive directory work. They do not make every attack circuit or all CPU load disappear.
📝 What belongs in torrc
No new mandatory torrc lines are needed. The upstream operator guidance asks operators to leave these settings unset:
DoSBeginDirRateEnabled
DoSBeginDirRate
DoSBeginDirBurst
DoSBeginDirDefenseType
Those are option names for reference, not a configuration block to paste. The samples and generated comments explain following the consensus instead of fixing thresholds locally. DoSBeginDirLimitEnabled is a consensus parameter, not a torrc option.
If you added DirCache 0 as an attack workaround, upgrade first, then review removing it and observe the relay. Disabling caching also opts out of directory-cache, fallback-directory, Guard and HSDir roles. DirPort 0 is different: keep the existing standalone-listener setting unless your deployment independently requires a change.
Mounted torrc files and includes remain operator-owned. Persist generated settings in deployment ENV. Reloading configuration does not replace Tor itself.
🏗️ Tor comes from the verified upstream release
Alpine’s Tor package availability should not hold up a relay security update. v2.2.1 builds the pinned upstream release directly on each matching Alpine base. Alpine continues to supply the base, build tools and runtime libraries.
The reviewed source lock
records the version, archive SHA256 and approved signing fingerprint. The builder verifies the signed checksum in an isolated keyring and hashes the archive before compilation. It packages Tor as a locally signed APK with GeoIP data, licenses, runtime dependency metadata and /usr/share/tor/source.json.
Compilers and the temporary private package-signing key stay in the build stage. There is no older Alpine Tor installation underneath a replacement binary, and no silent fallback when verification fails.
This remains the v2.2.0 operational model : persistent data and keys, verified encrypted recovery and promotion of the exact images that passed validation. No compiler is needed on a relay server, and no new port is opened by this change.
🔄 The next Tor security release
The 🔒🧅 workflow checks upstream stable releases every six hours. A newer release is authenticated and recorded as a proposed source lock for review. Equal versions leave the pin unchanged; downgrades and authentication failures are rejected.
Detection does not merge or publish an update. After review and complete validation, a main-branch rebuild can refresh the existing 2.2.1, latest and edge image tags. GHCR also retains 2.2.1-edge. The Git v2.2.1 tag remains an immutable record of the original release.
For an exact deployment, retain the image digest and its publication evidence. A project version alone cannot identify which later security rebuild is running.
📦 Upgrade one relay at a time
Before changing the image, record the fingerprint, digest and deployment configuration. Create and verify an encrypted recovery set, including the active torrc/includes, relay data, family material and transport state. Keep required rollback images available.
Select the intended v2.2.1 image reference in Compose, then replace <service> with the actual service name:
docker compose pull <service>
docker compose up -d --no-deps --force-recreate <service>
docker compose exec <service> tor --version
docker compose exec <service> config validate
docker compose exec <service> fingerprint
docker compose exec <service> doctor --json
Keep the existing data/configuration mounts and compare the fingerprint with the recorded value. Never start two copies of one relay identity or delete volumes to upgrade. Check fresh bootstrap/readiness and external reachability separately.
Encrypted recovery was introduced in v2.2.0. This release adds compatibility rehearsals and fixes bridge/exit diagnostics to read Tor’s effective configuration, including torrc includes. The startup banner also reads the image’s actual build version.
✅ Validation and release evidence
The published release workflow passed 193 regression tests and the complete native AMD64 and ARM64 candidate matrix for stable and edge. Each candidate passed upstream tests, image/security checks and encrypted recovery rehearsals. Separate local upgrade rehearsals covered guard, exit and bridge roles using ENV and mounted/include configuration with existing v2.2.0 images.
The retained evidence archive contains image identities, Tor source provenance, SBOMs and scan reports for all four candidates. The post-publication security audit also passed for both registries and both architectures. At publication review, the version and alias manifests in Docker Hub and GHCR matched the retained promotion record.
The release pipeline requires behavior, security and provenance evidence for stable and edge on both AMD64 and ARM64 before publication. Tor’s sandbox checks need kernel support that ordinary user-mode emulation cannot establish. Consult the retained release evidence for the published images, then check each deployed relay’s current-run readiness and external reachability separately.
Registry cleanup remains a separate operation. It preserves current architecture graphs and reviewed deployment/rollback identities, and its notice window does not override stale fleet evidence. Publishing v2.2.1 does not silently retire protected v2.2.0 images or delete GitHub release assets.
The v2.2.1 release , migration guide , backup guide and published release workflow carry the operational detail. Upgrade one relay at a time and confirm the running Tor version after each restart.