WireGuard Portal

A simple, web based configuration portal for WireGuard. The portal uses the WireGuard wgctrl library to manage existing VPN interfaces. This allows for seamless activation or deactivation of new users, without disturbing existing VPN connections.

The configuration portal currently supports using SQLite and MySQL as a user source for authentication and profile data. It also supports LDAP (Active Directory or OpenLDAP) as authentication provider.

Features

• Self-hosted and web based
• Automatically select IP from the network pool assigned to client
• QR-Code for convenient mobile client configuration
• Sent email to client with QR-code and client config
• Enable / Disable clients seamlessly
• Generation of wgX.conf after any modification
• IPv6 ready
• User authentication (SQLite/MySQL and LDAP)
• Dockerized
• Responsive template
• One single binary
• Can be used with existing WireGuard setups
• Support for multiple WireGuard interfaces
• REST API for management and client deployment
• Peer Expiry Feature

Setup

Make sure that your host system has at least one WireGuard interface (for example wg0) available. If you did not start up a WireGuard interface yet, take a look at wg-quick in order to get started.

Docker

The easiest way to run WireGuard Portal is to use the Docker image provided.

HINT: the latest tag always refers to the master branch and might contain unstable or incompatible code!

Docker Compose snippet with some sample configuration values:

version: '3.6'
services:
  wg-portal:
    image: h44z/wg-portal:latest
    container_name: wg-portal
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    network_mode: "host"
    volumes:
      - /etc/wireguard:/etc/wireguard
      - ./data:/app/data
    ports:
      - '8123:8123'
    environment:
      # WireGuard Settings
      - WG_DEVICES=wg0
      - WG_DEFAULT_DEVICE=wg0
      - WG_CONFIG_PATH=/etc/wireguard
      # Core Settings
      - EXTERNAL_URL=https://vpn.company.com
      - WEBSITE_TITLE=WireGuard VPN
      - COMPANY_NAME=Your Company Name
      - [email protected]
      - ADMIN_PASS=supersecret
      # Mail Settings
      - MAIL_FROM=WireGuard VPN <[email protected]>
      - EMAIL_HOST=10.10.10.10
      - EMAIL_PORT=25
      # LDAP Settings
      - LDAP_ENABLED=true
      - LDAP_URL=ldap://srv-ad01.company.local:389
      - LDAP_BASEDN=DC=COMPANY,DC=LOCAL
      - [email protected]
      - LDAP_PASSWORD=supersecretldappassword
      - LDAP_ADMIN_GROUP=CN=WireGuardAdmins,OU=Users,DC=COMPANY,DC=LOCAL

Please note that mapping /etc/wireguard to /etc/wireguard inside the docker, will erase your host's current configuration. If needed, please make sure to back up your files from /etc/wireguard. For a full list of configuration options take a look at the source file internal/server/configuration.go.

Standalone

For a standalone application, use the Makefile provided in the repository to build the application. Go version 1.16 or higher has to be installed to build WireGuard Portal.

# show all possible make commands
make

# build wg-portal for current system architecture
make build

The compiled binary will be located in the dist folder. A detailed description for using this software with a raspberry pi can be found in the README-RASPBERRYPI.md.

To build the Docker image, Docker (> 20.x) with buildx is required. If you want to build cross-platform images, you need to install qemu. On arch linux for example install: docker-buildx qemu-user-static qemu-user-static-binfmt.

Once the Docker setup is completed, create a new buildx builder:

docker buildx create --name wgportalbuilder --platform linux/arm/v7,linux/arm64,linux/amd64
docker buildx use wgportalbuilder
docker buildx inspect --bootstrap

Now you can compile the Docker image:

# multi platform build, can only be exported to tar archives
docker buildx build --platform linux/arm/v7,linux/arm64,linux/amd64 --output type=local,dest=docker_images \
  --build-arg BUILD_IDENTIFIER=dev --build-arg BUILD_VERSION=0.1 -t h44z/wg-portal .
  

# image for current platform only (same as docker build)
docker buildx build --load \
  --build-arg BUILD_IDENTIFIER=dev --build-arg BUILD_VERSION=0.1 -t h44z/wg-portal .

Configuration

You can configure WireGuard Portal using either environment variables or a yaml configuration file. The filepath of the yaml configuration file defaults to config.yml in the working directory of the executable. It is possible to override the configuration filepath using the environment variable CONFIG_FILE. For example: CONFIG_FILE=/home/test/config.yml ./wg-portal-amd64.

Configuration Options

The following configuration options are available:

Sample yaml configuration

config.yml:

core:
  listeningAddress: :8123
  externalUrl: https://wg-test.test.com
  adminUser: [email protected]
  adminPass: test
  editableKeys: true
  createDefaultPeer: false
  ldapEnabled: true
  mailFrom: WireGuard VPN <[email protected]>
ldap:
  url: ldap://10.10.10.10:389
  dn: DC=test,DC=test
  startTLS: false
  user: [email protected]
  pass: test
  adminGroup: CN=WireGuardAdmins,CN=Users,DC=test,DC=test
database:
  typ: sqlite
  database: data/wg_portal.db
email:
  host: smtp.gmail.com
  port: 587
  tls: true
  user: [email protected]
  pass: topsecret
wg:
  devices:
    - wg0
    - wg1
  defaultDevice: wg0
  configDirectory: /etc/wireguard
  manageIPAddresses: true

RESTful API

WireGuard Portal offers a RESTful API to interact with. The API is documented using OpenAPI 2.0, the Swagger UI can be found under the URL http://<your wg-portal ip/domain>/swagger/index.html?displayOperationId=true.

The API's unittesting may serve as an example how to make use of the API with python3 & pyswagger.

What is out of scope

• Creating or removing WireGuard (wgX) interfaces.
• Generation or application of any iptables or nftables rules.
• Setting up or changing IP-addresses of the WireGuard interface on operating systems other than linux.
• Importing private keys of an existing WireGuard setup.

Application stack

• Gin, HTTP web framework written in Go
• go-template, data-driven templates for generating textual output
• Bootstrap, for the HTML templates
• JQuery, for some nice JavaScript effects ;)

License

• MIT License. MIT or https://opensource.org/licenses/MIT

This project was inspired by wg-gen-web.