WireGuard Container Endpoint (WGCE)

This Container provides a REST API to configure WireGuard interfaces and filters based on iptables on a host (for IPv4 and IPv6). The intended Use-Cases/Scenarios are described here.

How to use

First, you need to start the container with the following command:

docker run -d \
    --name=wgce \
    --cap-add=NET_ADMIN \
    -p 8000:8000 \
    -p 51820:51820/udp \
    --volume wgce_data:/opt/data \
    --sysctl net.ipv4.ip_forward=1 \
    --sysctl net.ipv4.conf.all.src_valid_mark=1 \
    --sysctl net.ipv6.conf.all.forwarding=1 \
    --sysctl net.ipv6.conf.all.disable_ipv6=0 \
    docker.io/hoelsner/wireguard-container-endpoint:latest

The sysctl settings are required to support routing and IPv6 within the Container. By default, a new instance will use a admin user together with a random password that is stored at /opt/data/.generated_password (retrieve with docker exec -it wgce /bin/bash -c "cat /opt/data/.generated_password"). You can also specify the admin password as APP_ADMIN_PASSWORD environment variable, if you want to use a predefined value.

The API to configure the WireGuard Interfaces and filters is exposed by default at https://127.0.0.1:8000/api and the OpenAPI/Swagger documentation is available at https://127.0.0.1:8000/docs.

Application Configuration

Usually, you can start the container without any additional configuration. By default, all data that must be persistet is stored in the Container at /opt/data. This directory is defined as a volume by default.

The REST API will be availalbe on port 8000 using a self signed certificate. To replace the HTTPs certificate, replace the files at /opt/data/ssl or set the UVICORN_SSL_KEYFILE and UVICORN_SSL_CERTFILE environment variable to a different file. The log messages of the container are only printed to stdout.

The following table describes the configuration values for the container.

Name	Description	default value	example value
`APP_NAME`	Name of the endpoint which is used as the application name on the API	---	unset
`APP_ADMIN_USER`	Username for admin access to the API	`admin`	`admin`
`APP_ADMIN_PASSWORD`	Password for the admin access on the API - if not set, a admin password is generated as part of the Container start	unset	`PlsChgMe`
`APP_PORT`	port where the HTTP API is accessbile	`8000`	`8000`
`APP_HOST`	Host IP where the application should be bound to (should not be changed)	`0.0.0.0`	`0.0.0.0`
`APP_PEER_TRACKING_TIMER`	value in seconds that defines how often the peer status is checked. If there is no key exchange for 2 minutes, a peer is considered as dead and the host route is removed from the local routing table. (change not recommended)	`10`	`10`
`LOG_LEVEL`	logging level for the container	`info`	`info`
`UVICORN_SSL_KEYFILE`	path to keyfile for HTTPs within the Container	`/opt/data/ssl/privkey.pem`	`/opt/data/ssl/privkey.pem`
`UVICORN_SSL_CERTFILE`	path to certfile for HTTPs within the Container	`/opt/data/ssl/fullchain.pem`	`/opt/data/ssl/fullchain.pem`
`SELF_SIGNED_CERT_CN`	CN value if a self-signed certificate is created	`example.com`	`example.com`
`APP_CORS_ORIGIN`	CORS origin setting for FastAPI	---	`*`
`APP_CORS_METHODS`	CORS methods setting for FastAPI	---	`*`
`APP_CORS_HEADERS`	CORS headers setting for FastAPI	---	`*`
`DISABLE_HTTPS`	set this environment variable to any value will disable HTTPs on the admin interface (not recommended)	---	unset
`DEBUG`	enables the debug mode for the application (only for development)	`False`	`False`
`WG_CONFIG_DIR`	location, where the WireGuard configuration files should be stored (should not be changed)	`/etc/wireguard`	`/etc/wireguard`
`DATA_DIR`	data directory where all information from the container are stored (should not be changed)	---	`/opt/data`

Initial Configuration

The following environment variables are required to configure the Container at the first boot with an Wireguard interface and peer:

Name	Description	default value	example value
`INIT_INTF_NAME`	initial WireGuard Interface	---	`wg16`
`INIT_INTF_LISTEN_PORT`	port for the interface	`51820`	`51820`
`INIT_INTF_PRIVATE_KEY`	private key for the interface	---	`gGIwjTnOwUw7tTnNciJDHk5m8+BVUYNMrsx5TFkXVUA=`
`INIT_INTF_CIDR_ADDRESSES`	IPv4/IPv6 addresses on the interface	---	`10.1.1.1/32, FD00:1::1/128`
`INIT_POLICY_NAME`	policy name for the interface	`base policy`	`base policy`
`INIT_POLICY_NAT_ENABLE`	enable IPv4/IPv6 NAT	`False`	`False`
`INIT_POLICY_ALLOW_ADMIN`	allow access to WireGuard Admin Interface thought the WireGuard interface	`True`	`True`
`INIT_PEER_PUBLIC_KEY`	public key of the first peer	---	`gGIwjTnOwUw7tTnNciJDHk5m8+BVUYNMrsx5TFkXVUA=`
`INIT_PEER_PERSISTENT_KEEPALIVE`	WireGuard keepalive for peers	`30`	`60`
`INIT_PEER_ENDPOINT`	target host for the peer connection	---	`example.host.com:51820`
`INIT_PEER_CIDR_ROUTES`	routes/remote targets that are reachable via the peer	---	`10.1.1.1/32, FD00:1::1/128`

Furthermore, the following options may be required if NAT or a PSK should be used:

Name	Description	default value	example value
`INIT_POLICY_NAT_INTF`	(optional) interface name for the NAT rules (requires `INIT_POLICY_NAT_ENABLE` to `True`), required to get NAT working	---	`eth0`
`INIT_PEER_PRE_SHARED_KEY`	(optional) pre shared key for the peer	`None`	`INIT_PEER_PRE_SHARED_KEY`

How to develop

Setup Development Environment

Before starting, you need to install python 3.10 on a linux or macos machine together with the dependencies located at requirements_dev.txt (optionally within a virtualenv).

Parts of the application depends on the following packages that must be installed:

sudo apt-get install -y wireguard wireguard-tools

The repository also contains a vscode development Container, which was primarily used during the development. See https://code.visualstudio.com/docs/remote/containers for additional information.

Database and Schema Migration

The configuration database is stored in a sqlite database within the application. For schema management, aerich is used together with Tortoise ORM.

The aerich migration environment was already initialized with the following command:

cd webapp
aerich init --tortoise-orm utils.config.TORTOISE_ORM
aerich init-db

To create a new migration for the application, use the following command:

aerich migrate --name <name of migration>

To migrate an existing database, use the following command:

aerich upgrade

This command is automatically run, if an instance is started as part of the resources/runserver.bash script. The output is stored at /opt/data/aerich.log.

Run Development Server

To start a development server, run the following command:

# use cli .py
python3 cli.py run-dev-server

# start development server directly using uvicorn
uvicorn app.fast_api:create --factory --port=8000 --debug --host="0.0.0.0"

Run Unit-Tests

To run the unit-testcases, use the following command:

cd webapp
pytest

# or just rerun the last failed test cases
pytest --lf

Run E2E tests

How to run the end-to-end tests is described at test/README.md. Within the end-to-end tests, a NGINX test container is created that exposes IPv4 and IPv6 endpoints based on nginxdemos/nginx-hello. The Dockerfile for this "test-service" is available at resources/nginx-hello-ipv6.

Build and Run the Container locally

To build and start a production container, use the following commands on the repository root directory:

docker build --pull -t localhost.local/wg-container-endpoint:dev .
docker run -d -it \
    --name=wgce_dev \
    --cap-add=NET_ADMIN \
    --cap-add=NET_RAW \
    -p 8000:8000 \
    --volume wgce_data_dev:/opt/data \
    --sysctl net.ipv4.ip_forward=1 \
    --sysctl net.ipv4.conf.all.src_valid_mark=1 \
    --sysctl net.ipv6.conf.all.forwarding=1 \
    --sysctl net.ipv6.conf.all.disable_ipv6=0 \
    localhost.local/wg-container-endpoint:dev