A Tor WebTunnel bridge relay, declared once.
services.tor-webtunnel-bridge = {
enable = true;
domain = "example.org";
path = "/vRsQ4Nk2";
contactInfo = "ops@example.org";
acme.email = "ops@example.org";
};That deploys Tor as a bridge relay with the webtunnel pluggable transport, nginx terminating TLS in front of it, a certificate issued automatically, the transport reachable on one path, and a cover site on every other path.
A WebTunnel bridge is not another transport switched on an existing relay. It needs its own domain, a valid TLS certificate and a real web server in front of it, because the point is that its traffic is indistinguishable from ordinary HTTPS to that site.
Every piece is already in nixpkgs — the webtunnel package, Tor's ServerTransportPlugin,
nginx, ACME. What was missing was the composition, and getting it wrong is quiet: the bridge
comes up, the certificate is valid, and clients still cannot use it.
A domain holding a valid certificate that answers on exactly one unusual path is itself a pattern worth noticing. The module serves a site on every path except the transport's.
The bundled default is a starting point, not something to ship as-is. Replace it with something that belongs to your domain name.
services.tor-webtunnel-bridge.coverSite = ./my-site;There is no default, on purpose. A shared default would make every deployment of this module identifiable with a single request.
Pick something unremarkable and unguessable:
$ head -c 9 /dev/urandom | base64 | tr -d '/+=' | sed 's|^|/|'Prototype. It is not yet something to trust with anyone's safety.
What is here:
- the module, intended to deploy a bridge from one declaration
- a NixOS VM test covering the plumbing: nginx serves the cover site over TLS, Tor starts and registers the transport, the transport listens where nginx proxies to it, Tor holds an identity key, and the ORPort is not exposed
- CI running that test
What is not here yet, and matters before you rely on it:
- an end-to-end test. The VM test proves the parts are wired together. It does not prove a client completes a Tor circuit through the bridge, which needs a private Tor network in the test and is the honest boundary of what is verified today
- an edge-case matrix — certificate renewal, restarts, transport crash and recovery
- an external security review
- operator documentation beyond this file
- any meaningful record of behaviour over time
If you run this, run it as an experiment.
From upstream's setup guide, plus what running one actually costs:
- A domain you control. It becomes public — it goes in the bridge line handed to users — and it will eventually be blocked somewhere, which is what happens to a bridge that works. Do not use a domain you need for anything else.
- A valid TLS certificate. Obtained automatically unless you set
acme.enable = false. - A resolver that returns errors. Many consumer ISPs answer a name that does not exist with
an address of their own rather than NXDOMAIN — Portugal's NOS hands back
62.169.70.160for every one. While setting a bridge up that is actively misleading: a record that has not propagated yet, or a domain you never registered, resolves perfectly well, so a failed ACME issuance reads as an ACME problem when it is a DNS one. Check with a resolver that does not rewrite errors —dig @1.1.1.1 your.domain— before believing anything about DNS state. The irony is worth noting: intercepting DNS answers is itself one of the cheaper censorship techniques, and here it is running on the operator's own connection. - At least 1 GB of RAM, 4 GB recommended. A 512 MB host will start this and then have Tor killed under memory pressure, which presents as an intermittent bridge rather than an undersized one.
- A static IPv4 address, preferably, and port 443 reachable.
- A host whose provider permits Tor bridge relays. A bridge is not an exit node and attracts none of an exit's abuse reports, but confirm it in writing rather than assume it: some otherwise unremarkable providers prohibit Tor outright.
Wang and Cho (FOCI 2026) measured transit concentration in Tor and found five ASes carrying over half of exit probability. Adding capacity to an already dominant network makes that worse. If two providers are otherwise equal, prefer the one that is under-represented — OrNetStats shows the current distribution.
A bridge that works is one a censor eventually blocks. That is stated above as a fact about the domain, but it has a harder corollary for whoever runs it: on a network that interferes, a working deployment and a broken one look the same from the inside.
| What you see | Could be this module | Could be the network |
|---|---|---|
| A domain resolves that was never registered | — | the resolver rewrites NXDOMAIN |
| ACME issuance fails | wrong path, or 443 unreachable | DNS answers rewritten, or 80 filtered |
| Cover site loads, clients still cannot connect | wrong path, transport not running |
the path or SNI filtered upstream |
| Reachable from one network, not another | — | working as intended — this is what being blocked looks like |
The last row is the one that costs time. Every instinct says a tool that fails for some users is faulty; here it is the tool doing its job and meeting the thing it exists to defeat. Before changing configuration, reproduce from a second network you control, and check the bridge's own logs rather than the client's symptoms.
This cuts both ways for the operator's own machine. The resolver note under Requirements is the mild version: interference that is not hostile, just commercial, and it still sends you chasing the wrong fault.
The asymmetry is the hard part. A bridge is run from somewhere it works and used from somewhere it does not. Every diagnostic you can run — curl, dig, the journal, the test suite — describes a network that is not the one the bridge exists for. From where you sit it will look healthy long after it has stopped being reachable for the people it was set up to serve, because in a censored network the local operator is the one deciding what resolves and what connects, and none of that is visible from here.
So reachability is the one property you cannot verify yourself:
- The bridge's own logs are the honest source. Connections arriving is evidence; anything you probe from outside is not.
- OONI publishes measurements from inside censored networks. It will not test your bridge on request, but it shows what is being blocked and how.
- Silence is ambiguous. A bridge with no users may be blocked, or may simply not have been handed out yet by BridgeDB. Do not read either into the other.
Everything else in this README is verifiable from your terminal. This is not, and treating it as if it were is how an operator concludes a working bridge is broken and takes it down.
$ nix flake check
$ nix build .#checks.x86_64-linux.bridge -LThe test supplies its own self-signed certificate through acme.enable = false, since ACME
cannot run against a domain that does not exist outside the VM.
MIT. See LICENSE.