Installation on Docker

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.

Requirements

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

Kernel setup

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

Supported Architectures

Currently, only the x86-64 architecture is supported. The TunnelHound team is open to supporting new architectures. Please contact [email protected] to request support for a new architecture.

Running the TunnelHound image

To run the latest TunnelHound image, you can launch the tunnelhound/tunnelhound:latest image.

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.

The TUNNELHOUND_PG_URI environment variable should be set to a postgresql:// URI. See the corresponding section of the PostgreSQL manual.

Setup with Docker Postgres

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

Stopping the container

The container can be stopped like any other. Simply use docker kill <container name>.

Reverse proxying

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 protected] if you’re interested in this functionality.

Next Steps

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.

Troubleshooting

I can’t access the appliance frontend

Make sure you’ve enabled passthrough for ports 80 and 443.

I can’t access any endpoints I create

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.