fips/docs/how-to/deploy-tor-onion.md

Deploy a Tor Onion Service for FIPS

This guide covers running a Tor onion service that accepts inbound FIPS peer connections.

For the Tor transport's design and the bridge-node pattern (running Tor and UDP simultaneously), see ../design/fips-transport-layer.md. For the full transports.tor.* config knob inventory, see ../reference/configuration.md.

Inbound modes

FIPS supports two inbound Tor modes. (A third mode, socks5, is outbound-only and not covered here.)

• directory mode (recommended). Tor manages the onion service via HiddenServiceDir and HiddenServicePort directives in torrc. FIPS reads the resulting .onion hostname from a file and binds a local TCP listener for Tor to forward inbound connections to. No control-port interaction is required, which makes this mode compatible with Tor's Sandbox 1 seccomp-bpf hardening.
  • torrc requires: HiddenServiceDir + HiddenServicePort.
• control_port mode. FIPS speaks to Tor's control port to create an ephemeral onion service at startup (ADD_ONION). The onion key lives only for the lifetime of the FIPS daemon's control-port session. This mode is incompatible with Sandbox 1 — the sandbox forbids control-port-driven onion service management.
  • torrc requires: ControlPort (typically the Unix socket /run/tor/control) and a usable auth method (CookieAuthentication 1 is the common choice).

Pick directory unless you have a specific reason to prefer control_port. The rest of this guide covers directory mode end-to-end.

Prerequisites

• Tor daemon installed and running (Debian/Ubuntu: apt install tor)
• FIPS daemon configured and able to start
• Operator access to /etc/tor/torrc (or a drop-in under /etc/tor/torrc.d/)

Step 1: Configure Tor's HiddenServiceDir

Add the following to /etc/tor/torrc:

HiddenServiceDir /var/lib/tor/fips
HiddenServicePort 8443 127.0.0.1:8444

HiddenServiceDir tells Tor where to store the onion service's private key and hostname file. HiddenServicePort declares that inbound TCP traffic to port 8443 of the onion address should be forwarded to 127.0.0.1:8444 on the local host — that is where FIPS will bind its listener.

The external port (8443 here) is what peers will connect to over Tor; the internal target (127.0.0.1:8444) is purely local and is not directly reachable from the network.

Step 2: Reload Tor and read the onion hostname

sudo systemctl reload tor@default     # or `tor` on systems without instance support

After Tor processes the new config, the hostname file appears:

sudo cat /var/lib/tor/fips/hostname
# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.onion

Tor regenerates the onion key only on first run (or if you remove HiddenServiceDir). The hostname value is stable across daemon restarts as long as HiddenServiceDir is preserved.

Step 3: Verify HiddenServiceDir permissions

The directory must be readable only by the Tor user (Tor refuses to start otherwise):

ls -la /var/lib/tor/fips
# drwx------ debian-tor debian-tor ...

With the shipped Debian systemd unit, FIPS runs as root and reads the hostname file directly — no permission adjustment is needed.

Non-default deployments

If you run FIPS as an unprivileged user (custom packaging, hardened deployment, etc.), the FIPS daemon user needs read access to hostname. Options:

• Add the FIPS user to the debian-tor group and loosen group read on HiddenServiceDir (Tor still requires the directory itself to be 0700, so this typically means making hostname itself group-readable rather than the directory).
• Read hostname once at startup as root, then drop privileges.
• Copy the hostname into a path the FIPS user can read, refreshed whenever the onion key changes.

Step 4: Configure the FIPS Tor transport

In /etc/fips/fips.yaml, configure transports.tor with mode: directory:

transports:
  tor:
    mode: directory
    socks5_addr: "127.0.0.1:9050"
    connect_timeout_ms: 120000
    mtu: 1400
    advertised_port: 8443
    directory_service:
      hostname_file: "/var/lib/tor/fips/hostname"
      bind_addr: "127.0.0.1:8444"

The bind_addr must match the target of the HiddenServicePort directive in torrc. The hostname_file path must match HiddenServiceDir plus /hostname.

advertised_port is the virtual onion port peers dial — i.e. the first number on the HiddenServicePort line, not the local target. The default is 443; this guide uses 8443 on both sides to match the HiddenServicePort 8443 127.0.0.1:8444 example above. Setting this explicitly is important if you ever flip advertise_on_nostr: true: the published advert otherwise defaults to tor:<hash>.onion:443, which won't match the actual onion port.

The socks5_addr is the Tor SOCKS5 proxy used for outbound connections to other onion services or clearnet endpoints (separate from inbound onion service handling).

Optional monitoring knobs: control_addr and control_auth (e.g. /run/tor/control and cookie) let the daemon read Tor's status through the control port even in directory mode. They are non-fatal on failure — the onion service still works without them. See ../reference/configuration.md for the full key list and examples.

Step 5: Reload the FIPS daemon

sudo systemctl reload-or-restart fips

At startup the daemon reads the .onion hostname from hostname_file, binds 127.0.0.1:8444, and announces the onion endpoint internally. From this point inbound connections to <your-onion>.onion:8443 arrive at FIPS over Tor.

Step 6: Verify

Check that the FIPS daemon log shows the onion endpoint at startup:

sudo journalctl -u fips -e | grep -i 'onion\|directory'

You should see a line indicating the onion address FIPS will accept inbound connections on, and that the local bind on 127.0.0.1:8444 succeeded.

From another node configured with the Tor transport in socks5 or directory mode, attempt to dial:

fipsctl connect <peer-npub-or-hostname> <your-onion>.onion:8443 tor

A successful fipsctl show peers afterwards on the inbound side shows the new peer with transport=tor.

Optional: advertise the onion endpoint via Nostr discovery

If node.discovery.nostr.enabled: true, set transports.tor.advertise_on_nostr: true so the onion endpoint appears in this node's published advert. See enable-nostr-discovery.md Scenario 2.

Troubleshooting

• Tor refuses to start with Sandbox 1 and onion-service errors. Sandbox 1 requires directory mode and forbids creating onion services through the control port. Verify your torrc uses HiddenServiceDir (this guide), not ADD_ONION via control port.
• FIPS daemon fails to bind 127.0.0.1:8444. Another process is already bound to that port. Either stop the conflicting process or pick a different port and update both torrc's HiddenServicePort target and fips.yaml's bind_addr to match.
• Onion hostname is empty or missing. Check journalctl -u tor for permission errors on HiddenServiceDir. The directory must be owned by the Tor user with mode 0700.
• FIPS daemon cannot read hostname_file. File is owned by the Tor user and not readable by the FIPS daemon user. Adjust permissions, or copy the hostname into a path the FIPS user can read.

See also

• ../design/fips-transport-layer.md — Tor transport design, three modes (socks5, control_port, directory), bridge-node pattern
• ../reference/configuration.md — full transports.tor.* configuration knob table
• enable-nostr-discovery.md — Scenario 2 for advertising the onion endpoint to peers via Nostr