Running over Tor - Parallax Technical Documentation

The Parallax client has first-class Tor support, modeled closely on Bitcoin Core’s: outbound connections can be routed through a SOCKS5 proxy, the node can host a Tor v3 onion service for inbound connections with no port forwarding, onion addresses are gossiped and stored like any other peer address, and a node can run entirely inside Tor with --onlynet=onion. See Tor Integration for the protocol-level design.

Quick start

Install Tor and enable its control port in /etc/tor/torrc:

ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

restart Tor (sudo systemctl restart tor), add the user running parallaxd to the Tor group (debian-tor on Debian/Ubuntu, tor on Arch — on Arch also add DataDirectoryGroupReadable 1 to torrc, since the auth cookie lives inside /var/lib/tor there), then simply start the node:

parallaxd

No Tor-specific flags are needed for the default experience. On startup the node connects to the control port, creates a v3 onion service pointing at its P2P listener, and — because --onion wasn’t set — asks the Tor daemon for its SOCKS listener and configures it as the onion proxy automatically. Watch for:

torcontrol: onion proxy auto-configured   proxy=127.0.0.1:9050 reachable=true
torcontrol: onion service established     service=xxxx….onion virtualPort=32110

From that point the node is reachable at its onion address, advertises it to the network, and can dial other nodes’ onion addresses. The network reachability line logged at startup summarizes what the resolved configuration allows.

Flags

Flag	Default	Effect
`--listenonion`	on	Create a v3 onion service for the P2P listener via the Tor control port. A no-op (with quiet periodic retries) until a control port answers.
`--torcontrol`	`127.0.0.1:9051`	Tor control port address.
`--torpassword`	unset	Control-port password (`HashedControlPassword` auth). Cookie auth is used automatically when unset.
`--proxy`	unset	SOCKS5 proxy for all outbound connections, including clearnet ones. Also suppresses everything that would expose the node’s real IP regardless of the proxy: DNS-seed bootstrapping moves off the system resolver, the discv4 UDP socket is not opened, enrtree resolution is skipped, and UPnP/NAT-PMP is disabled.
`--onion`	auto-discovered	SOCKS5 proxy used only for `.onion` targets, overriding both `--proxy` and the auto-discovery. `--onion=0` disables onion outbound entirely.
`--onlynet`	unset	Restrict automatic outbound connections to the named networks (`ipv4`, `ipv6`, `onion`, comma-separated). Manual dials (`addnode`, `addPeer`, `dialV2`) and static nodes are exempt, as in Core.
`--proxyrandomize`	on	Fresh SOCKS5 credentials per connection, so Tor puts every peer on its own circuit (stream isolation).

The onion service identity

The service key persists in <datadir>/onion_v3_private_key, so the node keeps the same .onion address across restarts. Treat the file like the node key: back it up to keep the address, protect it because whoever holds it can impersonate the service. Deleting it yields a fresh address on next startup. The onion service always advertises the network default port (32110) regardless of the local --port, so nodes on non-standard ports are not decloaked by their port number.

Verifying

On the console:

> admin.nodeInfo.onion
"xxxx….onion:32110"

> admin.nodeInfo.networks
[{name: "ipv4", reachable: true, ...},
 {name: "ipv6", reachable: true, ...},
 {name: "onion", reachable: true, proxy: "127.0.0.1:9050", proxy_randomize_credentials: true}]

admin.peers shows each peer’s transport and logical address. A proxied peer’s remoteAddress is always the SOCKS5 proxy — the socket-level truth — while network.address names the actual target:

network: {
  address: "yyyy….onion:32110",
  network: "onion",
  remoteAddress: "127.0.0.1:9050",
  inbound: false, ...
}

An inbound onion peer shows an empty address: it reached us through a Tor rendezvous and is anonymous by design. To test reachability from another machine with Tor, dial the address directly:

parallax-cli dialv2 xxxx….onion:32110      # one-shot
parallax-cli addnode xxxx….onion:32110     # persistent, survives restarts

setban/listbanned accept onion addresses the same way, and removenode accepts them too — outbound peers are matched by the address they were dialed at, so a peer reached through a proxy is addressed by its real address rather than the proxy’s.

Fully dark: `--onlynet=onion`

parallaxd --onlynet=onion

restricts outbound to onion peers. No discv4 UDP socket is opened, NAT traversal and DNS seeding are disabled, and the node bootstraps from the onion addresses in the hardcoded bootnode list, then from gossip. It is legal to start this way before the Tor daemon is up: the node begins with no reachable network and flips onion reachable the moment the control port answers. An onion-only node never reveals its IP address to any peer — the client refuses to advertise an IP over a Tor circuit even when it knows one. A dual-stack node (clearnet listener + onion service) advertises both addresses, which allows observers to link them. Operators who need unlinkability must run onion-only.

Clearnet through Tor: expectations

--proxy=127.0.0.1:9050 routes clearnet connections through Tor exit relays. This works, but most exit policies do not carry non-standard ports, so only a fraction of circuits complete a connection to clearnet peers on 32110 — measured at roughly 1 in 6 on the live network (Bitcoin has the same property on 8333). Onion-to-onion connections use rendezvous circuits, never exits, and connect reliably in seconds. Treat exit-based clearnet dialing as a bootstrap fallback; onion peering is the real transport.

Troubleshooting

No torcontrol: lines at all — the control port isn’t answering, or the auth cookie is unreadable. The controller retries with backoff and logs failures only at debug level; run debug.verbosity(4) on the console to see the exact error (connection refused → torrc lacks ControlPort; permission denied → group membership or, on Arch, the missing DataDirectoryGroupReadable 1).
Onion dial says no route to network — the node has no onion proxy: no --proxy/--onion, and no control port for the auto-discovery. Onion entries are then neither stored nor dialed.
First dial to a fresh onion address fails with onion service descriptor can not be found — the descriptor hasn’t propagated yet; retry after 30-60 seconds.

​Quick start

​Flags

​The onion service identity

​Verifying

​Fully dark: --onlynet=onion

​Clearnet through Tor: expectations

​Troubleshooting