Docker is a conveniont solution for deploying servers on clouds or on-premise. TunnelHound provides pre-built Docker images for the TunnelHound access server. You will need to be able to grant the
NET_ADMIN capability to the container.
The only runtime requirement for TunnelHound is a PostgreSQL database. This database stores information on users, endpoints, and devices. It also stores private keys for the TunnelHound endpoint, so you should host your database on an encrypted filesystem
You can host the PostgreSQL instance in Docker. See the section below on hosting PostgreSQL
Due to the unique nature of container environments and the unique requirements of WireGuard®, there is some host-side setup needed before TunnelHound can successfully run. Firstly, you’ll need to be using a kernel that supports WireGuard®. Most common distributions support WireGuard®, but some require you to load the
wireguard module. This happens automatically when running directly on hardware, but Docker containers cannot insert new kernel modules.
To install the
wireguard kernel module:
sudo modprobe wireguard
Your distribution will also need to support NFTables. NFTables is the new Linux replacement for IPTables. You’ll need to load both the main NFTables modules as well as some accessory modules:
sudo modprobe nf_tables nf_tables_set nft_masq nft_chain_nat nf_nat nf_conntrack nft_ct
Currently, only the
x86-64 architecture is supported. The TunnelHound team is open to supporting new architectures. Please contact firstname.lastname@example.org to request support for a new architecture.
To run the latest TunnelHound image, you can launch the
docker run -p 51820:51820/udp -p 80:80 -p 443:443 --name tunnelhound --cap-add NET_ADMIN -e TUNNELHOUND_PG_URI=<postgres conn uri> -d tunnelhound/tunnelhound:latest
The image serves its main HTTPS endpoint on port 443 (and an HTTP redirect to the HTTPS endpoint on port 80). The command above will map this to port 443, which may interfere with other services on your host. Additionally, we open UDP port 51820, which is the default TunnelHound port. You should change this to whatever ports you’re going to run TunnelHound endpoints on.
TUNNELHOUND_PG_URI environment variable should be set to a
postgresql:// URI. See the corresponding section of the PostgreSQL manual.
You can use the official Docker Postgres image to run your PostgreSQL server.
First, create a private Docker network for TunnelHound and the Postgres database.
docker network create -d bridge tunnelhound
Now, run the
postgres container with the appropriate options:
docker run --network tunnelhound --name th-postgres -e POSTGRES_PASSWORD=<your password> -e POSTGRES_USER=tunnelhound -e POSTGRES_DB=tunnelhound -d postgres
Finally, launch the TunnelHound container:
docker run -p 51820:51820/udp -p 80:80 -p 443:443 --name tunnelhound --network tunnelhound --cap-add NET_ADMIN -e TUNNELHOUND_PG_URI=postgresql://tunnelhound:<password>@th-postgres/tunnelhound -d tunnelhound/tunnelhound:latest
The container can be stopped like any other. Simply use
docker kill <container name>.
The TunnelHound appliance is happy to sit behind a reverse proxy such as
haproxy, but your proxy must support SSL passthrough. There is currently no ability to terminate SSL before the TunnelHound image. Please write to email@example.com if you’re interested in this functionality.
You should now be able to access the TunnelHound appliance at
https://localhost (or whatever other host you configured). You can now follow the instructions for the initial setup.
Make sure you’ve enabled passthrough for ports 80 and 443.
The listening ports for the endpoints you create must be passed through via the
-p <port>:<port>/udp option. The port ought to be the same on both the host and container side if you want the auto-generated user WireGuard® configurations to work.