Examples
Below are some sample YAML configurations demonstrating how to override some default values.
Basic
core:
+ Examples - WireGuard Portal Examples
Below are some sample YAML configurations demonstrating how to override some default values.
Basic
core:
admin_user: test@example.com
admin_password: password
admin_api_token: super-s3cr3t-api-token-or-a-UUID
diff --git a/master/documentation/configuration/overview/index.html b/master/documentation/configuration/overview/index.html
index 51b3cd3..6a0ed69 100644
--- a/master/documentation/configuration/overview/index.html
+++ b/master/documentation/configuration/overview/index.html
@@ -1,4 +1,4 @@
- Overview - WireGuard Portal Overview
This page provides an overview of all available configuration options for WireGuard Portal.
You can supply these configurations in a YAML file when starting the Portal. The path of the configuration file defaults to config/config.yaml (or config/config.yml) in the working directory of the executable.
It is possible to override the configuration filepath using the environment variable WG_PORTAL_CONFIG. For example: WG_PORTAL_CONFIG=/etc/wg-portal/config.yaml ./wg-portal.
Also, environment variable substitution in the config file is supported. Refer to the syntax.
Configuration examples are available on the Examples page.
Default configuration
core:
+ Overview - WireGuard Portal Overview
This page provides an overview of all available configuration options for WireGuard Portal.
You can supply these configurations in a YAML file when starting the Portal. The path of the configuration file defaults to config/config.yaml (or config/config.yml) in the working directory of the executable.
It is possible to override the configuration filepath using the environment variable WG_PORTAL_CONFIG. For example: WG_PORTAL_CONFIG=/etc/wg-portal/config.yaml ./wg-portal.
Also, environment variable substitution in the config file is supported. Refer to the syntax.
Configuration examples are available on the Examples page.
Default configuration
core:
admin_user: admin@wgportal.local
admin_password: wgportal-default
admin_api_token: ""
diff --git a/master/documentation/getting-started/binaries/index.html b/master/documentation/getting-started/binaries/index.html
index 9cf6f2e..5440a88 100644
--- a/master/documentation/getting-started/binaries/index.html
+++ b/master/documentation/getting-started/binaries/index.html
@@ -1,4 +1,4 @@
- Binaries - WireGuard Portal Binaries
Starting from v2, each release includes compiled binaries for supported platforms. These binary versions can be manually downloaded and installed.
Download
Make sure that you download the correct binary for your architecture. The available binaries are:
wg-portal_linux_amd64 - Linux x86_64wg-portal_linux_arm64 - Linux ARM 64-bitwg-portal_linux_arm_v7 - Linux ARM 32-bit
Released versions
To download a specific version, replace ${WG_PORTAL_VERSION} with the desired version (or set an environment variable). All official release versions can be found on the GitHub Releases Page.
With curl:
curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
+ Binaries - WireGuard Portal Binaries
Starting from v2, each release includes compiled binaries for supported platforms. These binary versions can be manually downloaded and installed.
Download
Make sure that you download the correct binary for your architecture. The available binaries are:
wg-portal_linux_amd64 - Linux x86_64wg-portal_linux_arm64 - Linux ARM 64-bitwg-portal_linux_arm_v7 - Linux ARM 32-bit
Released versions
To download a specific version, replace ${WG_PORTAL_VERSION} with the desired version (or set an environment variable). All official release versions can be found on the GitHub Releases Page.
With curl:
curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
With wget:
wget -O wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
with gh cli:
gh release download ${WG_PORTAL_VERSION} --repo h44z/wg-portal --output wg-portal --pattern '*amd64'
The downloaded file will be named wg-portal and can be moved to a directory of your choice, see Install for more information.
Unreleased versions (master branch builds)
Unreleased versions can be fetched directly from the artifacts section of the GitHub Workflow.
Install
The following command can be used to install the downloaded binary (wg-portal) to /opt/wg-portal/wg-portal. It ensures that the binary is executable.
sudo mkdir -p /opt/wg-portal
diff --git a/master/documentation/getting-started/docker/index.html b/master/documentation/getting-started/docker/index.html
index 1c800a8..56ce6f4 100644
--- a/master/documentation/getting-started/docker/index.html
+++ b/master/documentation/getting-started/docker/index.html
@@ -1,4 +1,4 @@
- Docker - WireGuard Portal Docker
Image Usage
The WireGuard Portal Docker image is available on both Docker Hub and GitHub Container Registry. It is built on the official Alpine Linux base image and comes pre-packaged with all necessary WireGuard dependencies.
This container allows you to establish WireGuard VPN connections without relying on a host system that supports WireGuard or using the linuxserver/wireguard Docker image.
The recommended method for deploying WireGuard Portal is via Docker Compose for ease of configuration and management.
A sample docker-compose.yml (managing WireGuard interfaces directly on the host) is provided below:
---
+ Docker - WireGuard Portal Docker
Image Usage
The WireGuard Portal Docker image is available on both Docker Hub and GitHub Container Registry. It is built on the official Alpine Linux base image and comes pre-packaged with all necessary WireGuard dependencies.
This container allows you to establish WireGuard VPN connections without relying on a host system that supports WireGuard or using the linuxserver/wireguard Docker image.
The recommended method for deploying WireGuard Portal is via Docker Compose for ease of configuration and management.
A sample docker-compose.yml (managing WireGuard interfaces directly on the host) is provided below:
---
services:
wg-portal:
image: wgportal/wg-portal:v2
diff --git a/master/documentation/getting-started/helm/index.html b/master/documentation/getting-started/helm/index.html
index 4caf98a..539657b 100644
--- a/master/documentation/getting-started/helm/index.html
+++ b/master/documentation/getting-started/helm/index.html
@@ -1,2 +1,2 @@
- Helm - WireGuard Portal Helm
Installing the Chart
To install the chart with the release name wg-portal:
helm install wg-portal oci://ghcr.io/h44z/charts/wg-portal
+ Helm - WireGuard Portal Helm
Installing the Chart
To install the chart with the release name wg-portal:
helm install wg-portal oci://ghcr.io/h44z/charts/wg-portal
This command deploy wg-portal on the Kubernetes cluster in the default configuration. The Values section lists the parameters that can be configured during installation.
Values
Key Type Default Description nameOverride string ""Partially override resource names (adds suffix) fullnameOverride string ""Fully override resource names extraDeploy list []Array of extra objects to deploy with the release config.advanced tpl/object {}Advanced configuration options. config.auth tpl/object {}Auth configuration options. config.core tpl/object {}Core configuration options.
If external admins in auth are defined and there are no admin_user and admin_password defined here, the default admin account will be disabled. config.database tpl/object {}Database configuration options config.mail tpl/object {}Mail configuration options config.statistics tpl/object {}Statistics configuration options config.web tpl/object {}Web configuration options.
listening_address will be set automatically from service.web.port. external_url is required to enable ingress and certificate resources. revisionHistoryLimit string 10The number of old ReplicaSets to retain to allow rollback. workloadType string "Deployment"Workload type - Deployment or StatefulSet strategy object {"type":"RollingUpdate"}Update strategy for the workload Valid values are: RollingUpdate or Recreate for Deployment, RollingUpdate or OnDelete for StatefulSet image.repository string "ghcr.io/h44z/wg-portal"Image repository image.pullPolicy string "IfNotPresent"Image pull policy image.tag string ""Overrides the image tag whose default is the chart appVersion imagePullSecrets list []Image pull secrets podAnnotations tpl/object {}Extra annotations to add to the pod podLabels object {}Extra labels to add to the pod podSecurityContext object {}Pod Security Context securityContext.capabilities.add list ["NET_ADMIN"]Add capabilities to the container initContainers tpl/list []Pod init containers sidecarContainers tpl/list []Pod sidecar containers dnsPolicy string "ClusterFirst"Set DNS policy for the pod. Valid values are ClusterFirstWithHostNet, ClusterFirst, Default or None. restartPolicy string "Always"Restart policy for all containers within the pod. Valid values are Always, OnFailure or Never. hostNetwork string false.Use the host's network namespace. resources object {}Resources requests and limits command list []Overwrite pod command args list []Additional pod arguments env tpl/list []Additional environment variables envFrom tpl/list []Additional environment variables from a secret or configMap livenessProbe object {}Liveness probe configuration readinessProbe object {}Readiness probe configuration startupProbe object {}Startup probe configuration volumes tpl/list []Additional volumes volumeMounts tpl/list []Additional volumeMounts nodeSelector object {"kubernetes.io/os":"linux"}Node Selector configuration tolerations list []Tolerations configuration affinity object {}Affinity configuration service.mixed.enabled bool falseWhether to create a single service for the web and wireguard interfaces service.mixed.type string "LoadBalancer"Service type service.web.annotations object {}Annotations for the web service service.web.type string "ClusterIP"Web service type service.web.port int 8888Web service port Used for the web interface listener service.web.appProtocol string "http"Web service appProtocol. Will be auto set to https if certificate is enabled. service.wireguard.annotations object {}Annotations for the WireGuard service service.wireguard.type string "LoadBalancer"Wireguard service type service.wireguard.ports list [51820]Wireguard service ports. Exposes the WireGuard ports for created interfaces. Lowerest port is selected as start port for the first interface. Increment next port by 1 for each additional interface. service.metrics.port int 8787 ingress.enabled bool falseSpecifies whether an ingress resource should be created ingress.className string ""Ingress class name ingress.annotations object {}Ingress annotations ingress.tls bool falseIngress TLS configuration. Enable certificate resource or add ingress annotation to create required secret certificate.enabled bool falseSpecifies whether a certificate resource should be created. If enabled, certificate will be used for the web. certificate.issuer.name string ""Certificate issuer name certificate.issuer.kind string ""Certificate issuer kind (ClusterIssuer or Issuer) certificate.issuer.group string "cert-manager.io"Certificate issuer group certificate.duration string ""Optional. Documentation certificate.renewBefore string ""Optional. Documentation certificate.commonName string ""Optional. Documentation certificate.emailAddresses list []Optional. Documentation certificate.ipAddresses list []Optional. Documentation certificate.keystores object {}Optional. Documentation certificate.privateKey object {}Optional. Documentation certificate.secretTemplate object {}Optional. Documentation certificate.subject object {}Optional. Documentation certificate.uris list []Optional. Documentation certificate.usages list []Optional. Documentation persistence.enabled bool falseSpecifies whether an persistent volume should be created persistence.annotations object {}Persistent Volume Claim annotations persistence.storageClass string ""Persistent Volume storage class. If undefined (the default) cluster's default provisioner will be used. persistence.accessMode string "ReadWriteOnce"Persistent Volume Access Mode persistence.size string "1Gi"Persistent Volume size persistence.volumeName string ""Persistent Volume Name (optional) serviceAccount.create bool trueSpecifies whether a service account should be created serviceAccount.annotations object {}Service account annotations serviceAccount.automount bool falseAutomatically mount a ServiceAccount's API credentials serviceAccount.name string ""The name of the service account to use. If not set and create is true, a name is generated using the fullname template monitoring.enabled bool falseEnable Prometheus monitoring. monitoring.apiVersion string "monitoring.coreos.com/v1"API version of the Prometheus resource. Use azmonitoring.coreos.com/v1 for Azure Managed Prometheus. monitoring.kind string "PodMonitor"Kind of the Prometheus resource. Could be PodMonitor or ServiceMonitor. monitoring.labels object {}Resource labels. monitoring.annotations object {}Resource annotations. monitoring.interval string 1mInterval at which metrics should be scraped. If not specified config.statistics.data_collection_interval interval is used. monitoring.metricRelabelings list []Relabelings to samples before ingestion. monitoring.relabelings list []Relabelings to samples before scraping. monitoring.scrapeTimeout string ""Timeout after which the scrape is ended If not specified, the Prometheus global scrape interval is used. monitoring.jobLabel string ""The label to use to retrieve the job name from. monitoring.podTargetLabels object {}Transfers labels on the Kubernetes Pod onto the target. monitoring.dashboard.enabled bool falseEnable Grafana dashboard. monitoring.dashboard.annotations object {}Annotations for the dashboard ConfigMap. monitoring.dashboard.labels object {}Additional labels for the dashboard ConfigMap. monitoring.dashboard.namespace string ""Dashboard ConfigMap namespace Overrides the namespace for the dashboard ConfigMap.
\ No newline at end of file
diff --git a/master/documentation/getting-started/reverse-proxy/index.html b/master/documentation/getting-started/reverse-proxy/index.html
index 2e1d3eb..1e8555f 100644
--- a/master/documentation/getting-started/reverse-proxy/index.html
+++ b/master/documentation/getting-started/reverse-proxy/index.html
@@ -1,4 +1,4 @@
- Reverse Proxy (HTTPS) - WireGuard Portal Reverse Proxy (HTTPS)
Reverse Proxy for HTTPS
For production deployments, always serve the WireGuard Portal over HTTPS. You have two options to secure your connection:
Reverse Proxy
Let a front‐end proxy handle HTTPS for you. This also frees you from managing certificates manually and is therefore the preferred option. You can use Nginx, Traefik, Caddy or any other proxy.
Below is an example using a Docker Compose stack with Traefik. It exposes the WireGuard Portal on https://wg.domain.com and redirects initial HTTP traffic to HTTPS.
services:
+ Reverse Proxy (HTTPS) - WireGuard Portal Reverse Proxy (HTTPS)
Reverse Proxy for HTTPS
For production deployments, always serve the WireGuard Portal over HTTPS. You have two options to secure your connection:
Reverse Proxy
Let a front‐end proxy handle HTTPS for you. This also frees you from managing certificates manually and is therefore the preferred option. You can use Nginx, Traefik, Caddy or any other proxy.
Below is an example using a Docker Compose stack with Traefik. It exposes the WireGuard Portal on https://wg.domain.com and redirects initial HTTP traffic to HTTPS.
services:
reverse-proxy:
image: traefik:v3.3
restart: unless-stopped
diff --git a/master/documentation/getting-started/sources/index.html b/master/documentation/getting-started/sources/index.html
index 4b4ac25..be5c495 100644
--- a/master/documentation/getting-started/sources/index.html
+++ b/master/documentation/getting-started/sources/index.html
@@ -1,4 +1,4 @@
- Sources - WireGuard Portal Sources
To build the application from source files, use the Makefile provided in the repository.
Requirements
- Git
- Make
- Go:
>=1.24.0 - Node.js with npm:
node>=18, npm>=9
Build
# Get source code
+ Sources - WireGuard Portal Sources
To build the application from source files, use the Makefile provided in the repository.
Requirements
- Git
- Make
- Go:
>=1.25.0 - Node.js with npm:
node>=18, npm>=9
Build
# Get source code
git clone https://github.com/h44z/wg-portal -b ${WG_PORTAL_VERSION:-master} --depth 1
cd wg-portal
# Build the frontend
diff --git a/master/documentation/monitoring/prometheus/index.html b/master/documentation/monitoring/prometheus/index.html
index 520ff87..62a659e 100644
--- a/master/documentation/monitoring/prometheus/index.html
+++ b/master/documentation/monitoring/prometheus/index.html
@@ -1,4 +1,4 @@
- Monitoring - WireGuard Portal By default, WG-Portal exposes Prometheus metrics on port 8787 if interface/peer statistic data collection is enabled.
Exposed Metrics
Metric Type Description wireguard_interface_received_bytes_totalgauge Bytes received through the interface. wireguard_interface_sent_bytes_totalgauge Bytes sent through the interface. wireguard_peer_last_handshake_secondsgauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_totalgauge Bytes received from the peer. wireguard_peer_sent_bytes_totalgauge Bytes sent to the peer. wireguard_peer_upgauge Peer connection state (boolean: 1/0).
Prometheus Config
Add the following scrape job to your Prometheus config file:
# prometheus.yaml
+ Monitoring - WireGuard Portal By default, WG-Portal exposes Prometheus metrics on port 8787 if interface/peer statistic data collection is enabled.
Exposed Metrics
Metric Type Description wireguard_interface_received_bytes_totalgauge Bytes received through the interface. wireguard_interface_sent_bytes_totalgauge Bytes sent through the interface. wireguard_peer_last_handshake_secondsgauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_totalgauge Bytes received from the peer. wireguard_peer_sent_bytes_totalgauge Bytes sent to the peer. wireguard_peer_upgauge Peer connection state (boolean: 1/0).
Prometheus Config
Add the following scrape job to your Prometheus config file:
# prometheus.yaml
scrape_configs:
- job_name: wg-portal
scrape_interval: 60s
diff --git a/master/documentation/overview/index.html b/master/documentation/overview/index.html
index b082869..6efbac6 100644
--- a/master/documentation/overview/index.html
+++ b/master/documentation/overview/index.html
@@ -1 +1 @@
- Overview - WireGuard Portal Overview
WireGuard Portal is a simple, web-based configuration portal for WireGuard server management. The portal uses the WireGuard wgctrl library to manage existing VPN interfaces. This allows for the seamless activation or deactivation of new users without disturbing existing VPN connections.
The configuration portal supports using a database (SQLite, MySQL, MsSQL, or Postgres), OAuth or LDAP (Active Directory or OpenLDAP) as a user source for authentication and profile data.
Features
- Self-hosted - the whole application is a single binary
- Responsive multi-language web UI with dark-mode written in Vue.js
- Automatically selects IP from the network pool assigned to the client
- QR-Code for convenient mobile client configuration
- Sends email to the client with QR-code and client config
- Enable / Disable clients seamlessly
- Generation of wg-quick configuration file (
wgX.conf) if required - User authentication (database, OAuth, or LDAP), Passkey support
- IPv6 ready
- Docker ready
- Can be used with existing WireGuard setups
- Support for multiple WireGuard interfaces
- Supports multiple WireGuard backends (wgctrl, MikroTik, or pfSense)
- Peer Expiry Feature
- Handles route and DNS settings like wg-quick does
- Exposes Prometheus metrics for monitoring and alerting
- REST API for management and client deployment
- Webhook for custom actions on peer, interface, or user updates
\ No newline at end of file
+ Overview - WireGuard Portal Overview
WireGuard Portal is a simple, web-based configuration portal for WireGuard server management. The portal uses the WireGuard wgctrl library to manage existing VPN interfaces. This allows for the seamless activation or deactivation of new users without disturbing existing VPN connections.
The configuration portal supports using a database (SQLite, MySQL, MsSQL, or Postgres), OAuth or LDAP (Active Directory or OpenLDAP) as a user source for authentication and profile data.
Features
- Self-hosted - the whole application is a single binary
- Responsive multi-language web UI with dark-mode written in Vue.js
- Automatically selects IP from the network pool assigned to the client
- QR-Code for convenient mobile client configuration
- Sends email to the client with QR-code and client config
- Enable / Disable clients seamlessly
- Generation of wg-quick configuration file (
wgX.conf) if required - User authentication (database, OAuth, or LDAP), Passkey support
- IPv6 ready
- Docker ready
- Can be used with existing WireGuard setups
- Support for multiple WireGuard interfaces
- Supports multiple WireGuard backends (wgctrl, MikroTik, or pfSense)
- Peer Expiry Feature
- Handles route and DNS settings like wg-quick does
- Exposes Prometheus metrics for monitoring and alerting
- REST API for management and client deployment
- Webhook for custom actions on peer, interface, or user updates
\ No newline at end of file
diff --git a/master/documentation/rest-api/api-doc/index.html b/master/documentation/rest-api/api-doc/index.html
index 356b622..ddf36b9 100644
--- a/master/documentation/rest-api/api-doc/index.html
+++ b/master/documentation/rest-api/api-doc/index.html
@@ -1,5 +1,5 @@
- REST API - WireGuard Portal REST API
REST API
Upgrade
Major upgrades between different versions may require special procedures, which are described in the following sections.
Upgrade from v1 to v2
Before upgrading from V1, make sure that you have a backup of your currently working configuration files and database!
To start the upgrade process, start the wg-portal binary with the -migrateFrom parameter. The configuration (config.yaml) for WireGuard Portal must be updated and valid before starting the upgrade.
To upgrade from a previous SQLite database, start wg-portal like:
./wg-portal-amd64 -migrateFrom=old_wg_portal.db
+ Upgrade - WireGuard Portal Upgrade
Major upgrades between different versions may require special procedures, which are described in the following sections.
Upgrade from v1 to v2
Before upgrading from V1, make sure that you have a backup of your currently working configuration files and database!
To start the upgrade process, start the wg-portal binary with the -migrateFrom parameter. The configuration (config.yaml) for WireGuard Portal must be updated and valid before starting the upgrade.
To upgrade from a previous SQLite database, start wg-portal like:
./wg-portal-amd64 -migrateFrom=old_wg_portal.db
You can also specify the database type using the parameter -migrateFromType. Supported database types: mysql, mssql, postgres or sqlite.
For example:
./wg-portal-amd64 -migrateFromType=mysql -migrateFrom='user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local'
The upgrade will transform the old, existing database and store the values in the new database specified in the config.yaml configuration file. Ensure that the new database does not contain any data!
If you are using Docker, you can adapt the docker-compose.yml file to start the upgrade process:
services:
wg-portal:
diff --git a/master/documentation/usage/authentication/index.html b/master/documentation/usage/authentication/index.html
index d3b785b..6d9ab78 100644
--- a/master/documentation/usage/authentication/index.html
+++ b/master/documentation/usage/authentication/index.html
@@ -1,4 +1,4 @@
- Authentication - WireGuard Portal Authentication
WireGuard Portal supports multiple authentication mechanisms to manage user access. This includes
- Local user accounts
- LDAP authentication
- OAuth2 and OIDC authentication
- Passkey authentication (WebAuthn)
Users can have two roles which limit their permissions in WireGuard Portal:
- User: Can manage their own account and peers.
- Admin: Can manage all users and peers, including the ability to manage WireGuard interfaces.
In general, each user is identified by a unique identifier. If the same user identifier exists across multiple authentication sources, WireGuard Portal automatically merges those accounts into a single user record. When a user is associated with multiple authentication sources, their information in WireGuard Portal is updated based on the most recently logged-in source. For more details, see User Synchronization documentation.
Password Authentication
WireGuard Portal supports username and password authentication for both local and LDAP-backed accounts. Local users are stored in the database, while LDAP users are authenticated against an external LDAP server.
On initial startup, WireGuard Portal automatically creates a local admin account with the password wgportal-default.
This password must be changed immediately after the first login.
The minimum password length for all local users can be configured in the auth section of the configuration file. The default value is 16 characters, see min_password_length. The minimum password length is also enforced for the default admin user.
Passkey (WebAuthn) Authentication
Besides the standard authentication mechanisms, WireGuard Portal supports Passkey authentication. This feature is enabled by default and can be configured in the webauthn section of the configuration file.
Users can register multiple Passkeys to their account. These Passkeys can be used to log in to the web UI as long as the user is not locked.
Passkey authentication does not disable password authentication. The password can still be used to log in (e.g., as a fallback).
To register a Passkey, open the settings page (1) in the web UI and click on the "Register Passkey" (2) button.
OAuth2 and OIDC Authentication
WireGuard Portal supports OAuth2 and OIDC authentication. You can use any OAuth2 or OIDC provider that supports the authorization code flow, such as Google, GitHub, or Keycloak.
For OAuth2 or OIDC to work, you need to configure the external_url property in the web section of the configuration file. If you are planning to expose the portal to the internet, make sure that the external_url is configured to use HTTPS.
To add OIDC or OAuth2 authentication to WireGuard Portal, create a Client-ID and Client-Secret in your OAuth2 provider and configure a new authentication provider in the auth section of the configuration file. Make sure that each configured provider has a unique provider_name property set. Samples can be seen here.
Limiting Login to Specific Domains
You can limit the login to specific domains by setting the allowed_domains property for OAuth2 or OIDC providers. This property is a comma-separated list of domains that are allowed to log in. The user's email address is checked against this list. For example, if you want to allow only users with an email address ending in outlook.com to log in, set the property as follows:
auth:
+ Authentication - WireGuard Portal Authentication
WireGuard Portal supports multiple authentication mechanisms to manage user access. This includes
- Local user accounts
- LDAP authentication
- OAuth2 and OIDC authentication
- Passkey authentication (WebAuthn)
Users can have two roles which limit their permissions in WireGuard Portal:
- User: Can manage their own account and peers.
- Admin: Can manage all users and peers, including the ability to manage WireGuard interfaces.
In general, each user is identified by a unique identifier. If the same user identifier exists across multiple authentication sources, WireGuard Portal automatically merges those accounts into a single user record. When a user is associated with multiple authentication sources, their information in WireGuard Portal is updated based on the most recently logged-in source. For more details, see User Synchronization documentation.
Password Authentication
WireGuard Portal supports username and password authentication for both local and LDAP-backed accounts. Local users are stored in the database, while LDAP users are authenticated against an external LDAP server.
On initial startup, WireGuard Portal automatically creates a local admin account with the password wgportal-default.
This password must be changed immediately after the first login.
The minimum password length for all local users can be configured in the auth section of the configuration file. The default value is 16 characters, see min_password_length. The minimum password length is also enforced for the default admin user.
Passkey (WebAuthn) Authentication
Besides the standard authentication mechanisms, WireGuard Portal supports Passkey authentication. This feature is enabled by default and can be configured in the webauthn section of the configuration file.
Users can register multiple Passkeys to their account. These Passkeys can be used to log in to the web UI as long as the user is not locked.
Passkey authentication does not disable password authentication. The password can still be used to log in (e.g., as a fallback).
To register a Passkey, open the settings page (1) in the web UI and click on the "Register Passkey" (2) button.
OAuth2 and OIDC Authentication
WireGuard Portal supports OAuth2 and OIDC authentication. You can use any OAuth2 or OIDC provider that supports the authorization code flow, such as Google, GitHub, or Keycloak.
For OAuth2 or OIDC to work, you need to configure the external_url property in the web section of the configuration file. If you are planning to expose the portal to the internet, make sure that the external_url is configured to use HTTPS.
To add OIDC or OAuth2 authentication to WireGuard Portal, create a Client-ID and Client-Secret in your OAuth2 provider and configure a new authentication provider in the auth section of the configuration file. Make sure that each configured provider has a unique provider_name property set. Samples can be seen here.
Limiting Login to Specific Domains
You can limit the login to specific domains by setting the allowed_domains property for OAuth2 or OIDC providers. This property is a comma-separated list of domains that are allowed to log in. The user's email address is checked against this list. For example, if you want to allow only users with an email address ending in outlook.com to log in, set the property as follows:
auth:
oidc:
- provider_name: "oidc1"
# ... other settings
diff --git a/master/documentation/usage/backends/index.html b/master/documentation/usage/backends/index.html
index f2453e2..d196e72 100644
--- a/master/documentation/usage/backends/index.html
+++ b/master/documentation/usage/backends/index.html
@@ -1,4 +1,4 @@
- Backends - WireGuard Portal Backends
WireGuard Portal can manage WireGuard interfaces and peers on different backends. Each backend represents a system where interfaces actually live. You can register multiple backends and choose which one to use per interface. A global default backend determines where newly created interfaces go (unless you explicitly choose another in the UI).
Supported backends: - Local (default): Manages interfaces on the host running WireGuard Portal (Linux WireGuard via wgctrl). Use this when the portal should directly configure wg devices on the same server. - MikroTik RouterOS (beta): Manages interfaces and peers on MikroTik devices via the RouterOS REST API. Use this to control WG interfaces on RouterOS v7+. - pfSense (alpha): Manages interfaces and peers on pfSense firewalls via the pfSense REST API.
How backend selection works: - The default backend is configured at backend.default (local or the id of a defined MikroTik backend). New interfaces created in the UI will use this backend by default. - Each interface stores its backend. You can select a different backend when creating a new interface.
Configuring MikroTik backends (RouterOS v7+)
The MikroTik backend is currently marked beta. While basic functionality is implemented, some advanced features are not yet implemented or contain bugs. Please test carefully before using in production.
The MikroTik backend uses the REST API under a base URL ending with /rest. You can register one or more MikroTik devices as backends for a single WireGuard Portal instance.
Prerequisites on MikroTik:
- RouterOS v7 with WireGuard support.
- REST API enabled and reachable over HTTP(S). A typical base URL is https://
:8729/rest or https:///rest depending on your service setup. - A dedicated RouterOS user with the following group permissions:
- api (for logging in via REST API)
- rest-api (for logging in via REST API)
- read (to read interface and peer data)
- write (to create/update interfaces and peers)
- test (to perform ping checks)
- sensitive (to read private keys)
- TLS certificate on the device is recommended. If you use a self-signed certificate during testing, set
api_verify_tls: false in wg-portal (not recommended for production).
Example WireGuard Portal configuration (config/config.yaml):
backend:
+ Backends - WireGuard Portal Backends
WireGuard Portal can manage WireGuard interfaces and peers on different backends. Each backend represents a system where interfaces actually live. You can register multiple backends and choose which one to use per interface. A global default backend determines where newly created interfaces go (unless you explicitly choose another in the UI).
Supported backends: - Local (default): Manages interfaces on the host running WireGuard Portal (Linux WireGuard via wgctrl). Use this when the portal should directly configure wg devices on the same server. - MikroTik RouterOS (beta): Manages interfaces and peers on MikroTik devices via the RouterOS REST API. Use this to control WG interfaces on RouterOS v7+. - pfSense (alpha): Manages interfaces and peers on pfSense firewalls via the pfSense REST API.
How backend selection works: - The default backend is configured at backend.default (local or the id of a defined MikroTik backend). New interfaces created in the UI will use this backend by default. - Each interface stores its backend. You can select a different backend when creating a new interface.
Configuring MikroTik backends (RouterOS v7+)
The MikroTik backend is currently marked beta. While basic functionality is implemented, some advanced features are not yet implemented or contain bugs. Please test carefully before using in production.
The MikroTik backend uses the REST API under a base URL ending with /rest. You can register one or more MikroTik devices as backends for a single WireGuard Portal instance.
Prerequisites on MikroTik:
- RouterOS v7 with WireGuard support.
- REST API enabled and reachable over HTTP(S). A typical base URL is https://
:8729/rest or https:///rest depending on your service setup. - A dedicated RouterOS user with the following group permissions:
- api (for logging in via REST API)
- rest-api (for logging in via REST API)
- read (to read interface and peer data)
- write (to create/update interfaces and peers)
- test (to perform ping checks)
- sensitive (to read private keys)
- TLS certificate on the device is recommended. If you use a self-signed certificate during testing, set
api_verify_tls: false in wg-portal (not recommended for production).
Example WireGuard Portal configuration (config/config.yaml):
backend:
# default backend decides where new interfaces are created
default: mikrotik-prod
diff --git a/master/documentation/usage/general/index.html b/master/documentation/usage/general/index.html
index 26947ea..448a7da 100644
--- a/master/documentation/usage/general/index.html
+++ b/master/documentation/usage/general/index.html
@@ -1,2 +1,2 @@
- General - WireGuard Portal General
This documentation section describes the general usage of WireGuard Portal. If you are looking for specific setup instructions, please refer to the Getting Started and Configuration sections, for example, using a Docker deployment.
Basic Concepts
WireGuard Portal is a web-based configuration portal for WireGuard server management. It allows managing multiple WireGuard interfaces and users from a single web UI. WireGuard Interfaces can be categorized into three types:
- Server: A WireGuard server interface that to which multiple peers can connect. In this mode, it is possible to specify default settings for all peers, such as the IP address range, DNS servers, and MTU size.
- Client: A WireGuard client interface that can be used to connect to a WireGuard server. Usually, such an interface has exactly one peer.
- Unknown: This is the default type for imported interfaces. It is encouraged to change the type to either
Server or Client after importing the interface.
Accessing the Web UI
The web UI should be accessed via the URL specified in the external_url property of the configuration file. By default, WireGuard Portal listens on port 8888 for HTTP connections. Check the Security or Authentication sections for more information on securing the web UI.
So the default URL to access the web UI is:
http://localhost:8888
+ General - WireGuard Portal General
This documentation section describes the general usage of WireGuard Portal. If you are looking for specific setup instructions, please refer to the Getting Started and Configuration sections, for example, using a Docker deployment.
Basic Concepts
WireGuard Portal is a web-based configuration portal for WireGuard server management. It allows managing multiple WireGuard interfaces and users from a single web UI. WireGuard Interfaces can be categorized into three types:
- Server: A WireGuard server interface that to which multiple peers can connect. In this mode, it is possible to specify default settings for all peers, such as the IP address range, DNS servers, and MTU size.
- Client: A WireGuard client interface that can be used to connect to a WireGuard server. Usually, such an interface has exactly one peer.
- Unknown: This is the default type for imported interfaces. It is encouraged to change the type to either
Server or Client after importing the interface.
Accessing the Web UI
The web UI should be accessed via the URL specified in the external_url property of the configuration file. By default, WireGuard Portal listens on port 8888 for HTTP connections. Check the Security or Authentication sections for more information on securing the web UI.
So the default URL to access the web UI is:
http://localhost:8888
A freshly set-up WireGuard Portal instance will have a default admin user with the username admin@wgportal.local and the password wgportal-default. You can and should override the default credentials in the configuration file. Make sure to change the default password immediately after the first login!
Basic UI Description
As seen in the screenshot above, the web UI is divided into several sections which are accessible via the navigation bar on the top of the screen.
- Home: The landing page of WireGuard Portal. It provides a staring point for the user to access the different sections of the web UI. It also provides quick links to WireGuard Client downloads or official documentation.
- Interfaces: This section allows you to manage the WireGuard interfaces. You can add, edit, or delete interfaces, as well as view their status and statistics. Peers for each interface can be managed here as well.
- Users: This section allows you to manage the users of WireGuard Portal. You can add, edit, or delete users, as well as view their status and statistics.
- Key Generator: This section allows you to generate WireGuard keys locally on your browser. The generated keys are never sent to the server. This is useful if you want to generate keys for a new peer without having to store the private keys in the database.
- Profile / Settings: This section allows you to access your own profile page, settings, and audit logs.
Interface View
The interface view provides an overview of the WireGuard interfaces and peers configured in WireGuard Portal.
The most important elements are:
- Interface Selector: This dropdown allows you to select the WireGuard interface you want to manage. All further actions will be performed on the selected interface.
- Create new Interface: This button allows you to create a new WireGuard interface.
- Interface Overview: This section provides an overview of the selected WireGuard interface. It shows the interface type, number of peers, and other important information.
- List of Peers: This section provides a list of all peers associated with the selected WireGuard interface. You can view, add, edit, or delete peers from this list.
- Add new Peer: This button allows you to add a new peer to the selected WireGuard interface.
- Add multiple Peers: This button allows you to add multiple peers to the selected WireGuard interface. This is useful if you want to add a large number of peers at once.
\ No newline at end of file
diff --git a/master/documentation/usage/mail-templates/index.html b/master/documentation/usage/mail-templates/index.html
index dbf3c01..662d227 100644
--- a/master/documentation/usage/mail-templates/index.html
+++ b/master/documentation/usage/mail-templates/index.html
@@ -1,4 +1,4 @@
- Mail Templates - WireGuard Portal Mail Templates
WireGuard Portal sends emails when you share a configuration with a user. By default, the application uses embedded templates. You can fully customize these emails by pointing the Portal to a folder containing your own templates. If the folder is empty on startup, the default embedded templates are written there to get you started.
Configuration
To enable custom templates, set the mail.templates_path option in the application configuration file or the WG_PORTAL_MAIL_TEMPLATES_PATH environment variable to a valid folder path.
For example:
mail:
+ Mail Templates - WireGuard Portal Mail Templates
WireGuard Portal sends emails when you share a configuration with a user. By default, the application uses embedded templates. You can fully customize these emails by pointing the Portal to a folder containing your own templates. If the folder is empty on startup, the default embedded templates are written there to get you started.
Configuration
To enable custom templates, set the mail.templates_path option in the application configuration file or the WG_PORTAL_MAIL_TEMPLATES_PATH environment variable to a valid folder path.
For example:
mail:
# ... other mail options ...
# Path where custom email templates (.gotpl and .gohtml) are stored.
# If the directory is empty on startup, the default embedded templates
diff --git a/master/documentation/usage/security/index.html b/master/documentation/usage/security/index.html
index 1d33b30..4d77bfc 100644
--- a/master/documentation/usage/security/index.html
+++ b/master/documentation/usage/security/index.html
@@ -1 +1 @@
- Security - WireGuard Portal Security
This section describes the security features available to administrators for hardening WireGuard Portal and protecting its data.
Database Encryption
WireGuard Portal supports multiple database backends. To reduce the risk of data exposure, sensitive information stored in the database can be encrypted. To enable encryption, set the encryption_passphrase in the database configuration section.
Important: Once encryption is enabled, it cannot be disabled, and the passphrase cannot be changed! Only new or updated records will be encrypted; existing data remains in plaintext until it’s next modified.
UI and API Access
WireGuard Portal provides a web UI and a REST API for user interaction. It is important to secure these interfaces to prevent unauthorized access and data breaches.
HTTPS
It is recommended to use HTTPS for all communication with the portal to prevent eavesdropping.
Event though, WireGuard Portal supports HTTPS out of the box, it is recommended to use a reverse proxy like Nginx or Traefik to handle SSL termination and other security features. A detailed explanation is available in the Reverse Proxy section.
Secure Authentication
To prevent unauthorized access, WireGuard Portal supports integrating with secure authentication providers such as LDAP, OAuth2, or Passkeys, see Authentication for more details. When possible, use centralized authentication and enforce multi-factor authentication (MFA) at the provider level for enhanced account security. For local accounts, administrators should enforce strong password requirements.
\ No newline at end of file
+ Security - WireGuard Portal Security
This section describes the security features available to administrators for hardening WireGuard Portal and protecting its data.
Database Encryption
WireGuard Portal supports multiple database backends. To reduce the risk of data exposure, sensitive information stored in the database can be encrypted. To enable encryption, set the encryption_passphrase in the database configuration section.
Important: Once encryption is enabled, it cannot be disabled, and the passphrase cannot be changed! Only new or updated records will be encrypted; existing data remains in plaintext until it’s next modified.
UI and API Access
WireGuard Portal provides a web UI and a REST API for user interaction. It is important to secure these interfaces to prevent unauthorized access and data breaches.
HTTPS
It is recommended to use HTTPS for all communication with the portal to prevent eavesdropping.
Event though, WireGuard Portal supports HTTPS out of the box, it is recommended to use a reverse proxy like Nginx or Traefik to handle SSL termination and other security features. A detailed explanation is available in the Reverse Proxy section.
Secure Authentication
To prevent unauthorized access, WireGuard Portal supports integrating with secure authentication providers such as LDAP, OAuth2, or Passkeys, see Authentication for more details. When possible, use centralized authentication and enforce multi-factor authentication (MFA) at the provider level for enhanced account security. For local accounts, administrators should enforce strong password requirements.
\ No newline at end of file
diff --git a/master/documentation/usage/user-sync/index.html b/master/documentation/usage/user-sync/index.html
index 748de8e..6fb5441 100644
--- a/master/documentation/usage/user-sync/index.html
+++ b/master/documentation/usage/user-sync/index.html
@@ -1,4 +1,4 @@
- User Management - WireGuard Portal User Management
For all external authentication providers (LDAP, OIDC, OAuth2), WireGuard Portal can automatically create a local user record upon the user's first successful login. This behavior is controlled by the registration_enabled setting in each authentication provider's configuration.
User information from external authentication sources is merged into the corresponding local WireGuard Portal user record whenever the user logs in. Additionally, WireGuard Portal supports periodic synchronization of user data from an LDAP directory.
To prevent overwriting local changes, WireGuard Portal allows you to set a per-user flag that disables synchronization of external attributes. When this flag is set, the user in WireGuard Portal will not be updated automatically during log-ins or LDAP synchronization.
LDAP Synchronization
WireGuard Portal lets you hook up any LDAP server such as Active Directory or OpenLDAP for both authentication and user sync. You can even register multiple LDAP servers side-by-side. Details on the log-in process can be found in the LDAP Authentication section.
If you enable LDAP synchronization, all users within the LDAP directory will be created automatically in the WireGuard Portal database if they do not exist. If a user is disabled or deleted in LDAP, the user will be disabled in WireGuard Portal as well. The synchronization process can be fine-tuned by multiple parameters, which are described below.
Synchronization Parameters
To enable the LDAP sycnhronization this feature, set the sync_interval property in the LDAP provider configuration to a value greater than "0". The value is a string representing a duration, such as "15m" for 15 minutes or "1h" for 1 hour (check the exact format definition for details). The synchronization process will run in the background and synchronize users from LDAP to the database at the specified interval. Also make sure that the sync_filter property is a well-formed LDAP filter, or synchronization will fail.
Limiting Synchronization to Specific Users
Use the sync_filter property in your LDAP provider block to restrict which users get synchronized. It accepts any valid LDAP search filter, only entries matching that filter will be pulled into the portal's database.
For example, to import only users with a mail attribute:
auth:
+ User Management - WireGuard Portal User Management
For all external authentication providers (LDAP, OIDC, OAuth2), WireGuard Portal can automatically create a local user record upon the user's first successful login. This behavior is controlled by the registration_enabled setting in each authentication provider's configuration.
User information from external authentication sources is merged into the corresponding local WireGuard Portal user record whenever the user logs in. Additionally, WireGuard Portal supports periodic synchronization of user data from an LDAP directory.
To prevent overwriting local changes, WireGuard Portal allows you to set a per-user flag that disables synchronization of external attributes. When this flag is set, the user in WireGuard Portal will not be updated automatically during log-ins or LDAP synchronization.
LDAP Synchronization
WireGuard Portal lets you hook up any LDAP server such as Active Directory or OpenLDAP for both authentication and user sync. You can even register multiple LDAP servers side-by-side. Details on the log-in process can be found in the LDAP Authentication section.
If you enable LDAP synchronization, all users within the LDAP directory will be created automatically in the WireGuard Portal database if they do not exist. If a user is disabled or deleted in LDAP, the user will be disabled in WireGuard Portal as well. The synchronization process can be fine-tuned by multiple parameters, which are described below.
Synchronization Parameters
To enable the LDAP sycnhronization this feature, set the sync_interval property in the LDAP provider configuration to a value greater than "0". The value is a string representing a duration, such as "15m" for 15 minutes or "1h" for 1 hour (check the exact format definition for details). The synchronization process will run in the background and synchronize users from LDAP to the database at the specified interval. Also make sure that the sync_filter property is a well-formed LDAP filter, or synchronization will fail.
Limiting Synchronization to Specific Users
Use the sync_filter property in your LDAP provider block to restrict which users get synchronized. It accepts any valid LDAP search filter, only entries matching that filter will be pulled into the portal's database.
For example, to import only users with a mail attribute:
auth:
ldap:
- id: ldap
# ... other settings
diff --git a/master/documentation/usage/webhooks/index.html b/master/documentation/usage/webhooks/index.html
index 0d8f7d8..fd60607 100644
--- a/master/documentation/usage/webhooks/index.html
+++ b/master/documentation/usage/webhooks/index.html
@@ -1,4 +1,4 @@
- Webhooks - WireGuard Portal Webhooks
Webhooks allow WireGuard Portal to notify external services about events such as user creation, device changes, or configuration updates. This enables integration with other systems and automation workflows.
When webhooks are configured and a specified event occurs, WireGuard Portal sends an HTTP POST request to the configured webhook URL. The payload contains event-specific data in JSON format.
Configuration
All available configuration options for webhooks can be found in the configuration overview.
A basic webhook configuration looks like this:
webhook:
+ Webhooks - WireGuard Portal Webhooks
Webhooks allow WireGuard Portal to notify external services about events such as user creation, device changes, or configuration updates. This enables integration with other systems and automation workflows.
When webhooks are configured and a specified event occurs, WireGuard Portal sends an HTTP POST request to the configured webhook URL. The payload contains event-specific data in JSON format.
Configuration
All available configuration options for webhooks can be found in the configuration overview.
A basic webhook configuration looks like this:
webhook:
url: https://your-service.example.com/webhook
Security
Webhooks can be secured by using a shared secret. This secret is included in the Authorization header of the webhook request, allowing your service to verify the authenticity of the request. You can set the shared secret in the webhook configuration:
webhook:
url: https://your-service.example.com/webhook
diff --git a/master/index.html b/master/index.html
index dcbe8ce..ac633b1 100644
--- a/master/index.html
+++ b/master/index.html
@@ -1,4 +1,4 @@
- WireGuard Portal - WireGuard Portal