{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"documentation/overview/","title":"Overview","text":"
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.
"},{"location":"documentation/overview/#features","title":"Features","text":"wgX.conf
) if requiredBelow are some sample YAML configurations demonstrating how to override some default values.
"},{"location":"documentation/configuration/examples/#basic","title":"Basic","text":"core:\n admin_user: test@example.com\n admin_password: password\n admin_api_token: super-s3cr3t-api-token-or-a-UUID\n import_existing: false\n create_default_peer: true\n self_provisioning_allowed: true\n\nweb:\n site_title: My WireGuard Server\n site_company_name: My Company\n listening_address: :8080\n external_url: https://my.external-domain.com\n csrf_secret: super-s3cr3t-csrf\n session_secret: super-s3cr3t-session\n request_logging: true\n\nadvanced:\n log_level: trace\n log_pretty: true\n log_json: false\n config_storage_path: /etc/wireguard\n expiry_check_interval: 5m\n\ndatabase:\n debug: true\n type: sqlite\n dsn: data/sqlite.db\n encryption_passphrase: change-this-s3cr3t-encryption-passphrase\n\nauth:\n webauthn:\n enabled: true\n
"},{"location":"documentation/configuration/examples/#ldap-authentication-and-synchronization","title":"LDAP Authentication and Synchronization","text":"# ... (basic configuration)\n\nauth:\n ldap:\n # a sample LDAP provider with user sync enabled\n - id: ldap\n provider_name: Active Directory\n url: ldap://srv-ad1.company.local:389\n bind_user: ldap_wireguard@company.local\n bind_pass: super-s3cr3t-ldap\n base_dn: DC=COMPANY,DC=LOCAL\n login_filter: (&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2))\n sync_interval: 15m\n sync_filter: (&(objectClass=organizationalPerson)(!userAccountControl:1.2.840.113556.1.4.803:=2)(mail=*))\n disable_missing: true\n field_map:\n user_identifier: sAMAccountName\n email: mail\n firstname: givenName\n lastname: sn\n phone: telephoneNumber\n department: department\n memberof: memberOf\n admin_group: CN=WireGuardAdmins,OU=Some-OU,DC=COMPANY,DC=LOCAL\n registration_enabled: true\n log_user_info: true\n
"},{"location":"documentation/configuration/examples/#openid-connect-oidc-authentication","title":"OpenID Connect (OIDC) Authentication","text":"# ... (basic configuration)\n\nauth:\n oidc:\n # A sample Entra ID provider with environment variable substitution.\n # Only users with an @outlook.com email address are allowed to register or login.\n - id: azure\n provider_name: azure\n display_name: Login with</br>Entra ID\n registration_enabled: true\n base_url: \"https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0\"\n client_id: \"${AZURE_CLIENT_ID}\"\n client_secret: \"${AZURE_CLIENT_SECRET}\"\n allowed_domains:\n - \"outlook.com\"\n extra_scopes:\n - profile\n - email\n\n # a sample provider where users with the attribute `wg_admin` set to `true` are considered as admins\n - id: oidc-with-admin-attribute\n provider_name: google\n display_name: Login with</br>Google\n base_url: https://accounts.google.com\n client_id: the-client-id-1234.apps.googleusercontent.com\n client_secret: A_CLIENT_SECRET\n extra_scopes:\n - https://www.googleapis.com/auth/userinfo.email\n - https://www.googleapis.com/auth/userinfo.profile\n field_map:\n user_identifier: sub\n email: email\n firstname: given_name\n lastname: family_name\n phone: phone_number\n department: department\n is_admin: wg_admin\n admin_mapping:\n admin_value_regex: ^true$\n registration_enabled: true\n log_user_info: true\n\n # a sample provider where users in the group `the-admin-group` are considered as admins\n - id: oidc-with-admin-group\n provider_name: google2\n display_name: Login with</br>Google2\n base_url: https://accounts.google.com\n client_id: another-client-id-1234.apps.googleusercontent.com\n client_secret: A_CLIENT_SECRET\n extra_scopes:\n - https://www.googleapis.com/auth/userinfo.email\n - https://www.googleapis.com/auth/userinfo.profile\n field_map:\n user_identifier: sub\n email: email\n firstname: given_name\n lastname: family_name\n phone: phone_number\n department: department\n user_groups: groups\n admin_mapping:\n admin_group_regex: ^the-admin-group$\n registration_enabled: true\n log_user_info: true\n
"},{"location":"documentation/configuration/examples/#plain-oauth2-authentication","title":"Plain OAuth2 Authentication","text":"# ... (basic configuration)\n\nauth:\n oauth:\n # a sample provider where users with the attribute `this-attribute-must-be-true` set to `true` or `True`\n # are considered as admins\n - id: google_plain_oauth-with-admin-attribute\n provider_name: google3\n display_name: Login with</br>Google3\n client_id: another-client-id-1234.apps.googleusercontent.com\n client_secret: A_CLIENT_SECRET\n auth_url: https://accounts.google.com/o/oauth2/v2/auth\n token_url: https://oauth2.googleapis.com/token\n user_info_url: https://openidconnect.googleapis.com/v1/userinfo\n scopes:\n - openid\n - email\n - profile\n field_map:\n user_identifier: sub\n email: email\n firstname: name\n is_admin: this-attribute-must-be-true\n admin_mapping:\n admin_value_regex: ^(True|true)$\n registration_enabled: true\n\n # a sample provider where either users with the attribute `this-attribute-must-be-true` set to `true` or \n # users in the group `admin-group-name` are considered as admins\n - id: google_plain_oauth_with_groups\n provider_name: google4\n display_name: Login with</br>Google4\n client_id: another-client-id-1234.apps.googleusercontent.com\n client_secret: A_CLIENT_SECRET\n auth_url: https://accounts.google.com/o/oauth2/v2/auth\n token_url: https://oauth2.googleapis.com/token\n user_info_url: https://openidconnect.googleapis.com/v1/userinfo\n scopes:\n - openid\n - email\n - profile\n - i-want-some-groups\n field_map:\n email: email\n firstname: name\n user_identifier: sub\n is_admin: this-attribute-must-be-true\n user_groups: groups\n admin_mapping:\n admin_value_regex: ^true$\n admin_group_regex: ^admin-group-name$\n registration_enabled: true\n log_user_info: true\n
"},{"location":"documentation/configuration/overview/","title":"Overview","text":"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 configurationcore:\n admin_user: admin@wgportal.local\n admin_password: wgportal-default\n admin_api_token: \"\"\n editable_keys: true\n create_default_peer: false\n create_default_peer_on_creation: false\n re_enable_peer_after_user_enable: true\n delete_peer_after_user_deleted: false\n self_provisioning_allowed: false\n import_existing: true\n restore_state: true\n\nadvanced:\n log_level: info\n log_pretty: false\n log_json: false\n start_listen_port: 51820\n start_cidr_v4: 10.11.12.0/24\n start_cidr_v6: fdfd:d3ad:c0de:1234::0/64\n use_ip_v6: true\n config_storage_path: \"\"\n expiry_check_interval: 15m\n rule_prio_offset: 20000\n route_table_offset: 20000\n api_admin_only: true\n limit_additional_user_peers: 0\n\ndatabase:\n debug: false\n slow_query_threshold: \"0\"\n type: sqlite\n dsn: data/sqlite.db\n encryption_passphrase: \"\"\n\nstatistics:\n use_ping_checks: true\n ping_check_workers: 10\n ping_unprivileged: false\n ping_check_interval: 1m\n data_collection_interval: 1m\n collect_interface_data: true\n collect_peer_data: true\n collect_audit_data: true\n listening_address: :8787\n\nmail:\n host: 127.0.0.1\n port: 25\n encryption: none\n cert_validation: true\n username: \"\"\n password: \"\"\n auth_type: plain\n from: Wireguard Portal <noreply@wireguard.local>\n link_only: false\n\nauth:\n oidc: []\n oauth: []\n ldap: []\n webauthn:\n enabled: true\n min_password_length: 16\n hide_login_form: false\n\nweb:\n listening_address: :8888\n external_url: http://localhost:8888\n site_company_name: WireGuard Portal\n site_title: WireGuard Portal\n session_identifier: wgPortalSession\n session_secret: very_secret\n csrf_secret: extremely_secret\n request_logging: false\n expose_host_info: false\n cert_file: \"\"\n key_File: \"\"\n\nwebhook:\n url: \"\"\n authentication: \"\"\n timeout: 10s\n
Below you will find sections like core
, advanced
, database
, statistics
, mail
, auth
, web
and webhook
. Each section describes the individual configuration keys, their default values, and a brief explanation of their purpose.
These are the primary configuration options that control fundamental WireGuard Portal behavior. More advanced options are found in the subsequent Advanced
section.
admin_user
","text":"admin@wgportal.local
admin_password
","text":"wgportal-default
admin_api_token
","text":"editable_keys
","text":"true
create_default_peer
","text":"false
create_default_peer_on_creation
","text":"false
re_enable_peer_after_user_enable
","text":"true
delete_peer_after_user_deleted
","text":"false
self_provisioning_allowed
","text":"false
import_existing
","text":"true
restore_state
","text":"true
Additional or more specialized configuration options for logging and interface creation details.
"},{"location":"documentation/configuration/overview/#log_level","title":"log_level
","text":"info
trace
, debug
, info
, warn
, error
.log_pretty
","text":"false
true
, log messages are colorized and formatted for readability (pretty-print).log_json
","text":"false
true
, log messages are structured in JSON format.start_listen_port
","text":"51820
start_cidr_v4
","text":"10.11.12.0/24
start_cidr_v6
","text":"fdfd:d3ad:c0de:1234::0/64
use_ip_v6
","text":"true
config_storage_path
","text":"wg-quick
style configuration files will be stored (if you need local filesystem configs).expiry_check_interval
","text":"15m
s
, m
, h
, d
for seconds, minutes, hours, days, see time.ParseDuration.rule_prio_offset
","text":"20000
route_table_offset
","text":"20000
api_admin_only
","text":"true
true
, the public REST API is accessible only to admin users. The API docs live at /api/v1/doc.html
.limit_additional_user_peers
","text":"0
0
means unlimited.Configuration for the underlying database used by WireGuard Portal. Supported databases include SQLite, MySQL, Microsoft SQL Server, and Postgres.
If sensitive values (like private keys) should be stored in an encrypted format, set the encryption_passphrase
option.
debug
","text":"false
true
, logs all database statements (verbose).slow_query_threshold
","text":"100ms
) above which queries are considered slow and logged as warnings. If zero, slow query logging is disabled. Format uses s
, ms
for seconds, milliseconds, see time.ParseDuration. The value must be a string.type
","text":"sqlite
sqlite
, mssql
, mysql
, postgres
.dsn
","text":"data/sqlite.db
user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local\n
encryption_passphrase
","text":"Controls how WireGuard Portal collects and reports usage statistics, including ping checks and Prometheus metrics.
"},{"location":"documentation/configuration/overview/#use_ping_checks","title":"use_ping_checks
","text":"true
ping_check_workers
","text":"10
ping_unprivileged
","text":"false
false
, ping checks run without root privileges. This is currently considered BETA.ping_check_interval
","text":"1m
s
, m
, h
, d
for seconds, minutes, hours, days, see time.ParseDuration.data_collection_interval
","text":"1m
s
, m
, h
, d
for seconds, minutes, hours, days, see time.ParseDuration.collect_interface_data
","text":"true
true
, collects interface-level data (bytes in/out) for monitoring and statistics.collect_peer_data
","text":"true
true
, collects peer-level data (bytes, last handshake, endpoint, etc.).collect_audit_data
","text":"true
true
, logs certain portal events (such as user logins) to the database.listening_address
","text":":8787
:8787
or 127.0.0.1:8787
).Options for configuring email notifications or sending peer configurations via email.
"},{"location":"documentation/configuration/overview/#host","title":"host
","text":"127.0.0.1
port
","text":"25
encryption
","text":"none
none
, tls
, starttls
.cert_validation
","text":"true
true
, validate the SMTP server certificate (relevant if encryption
= tls
).username
","text":"password
","text":"auth_type
","text":"plain
plain
, login
, crammd5
.from
","text":"Wireguard Portal <noreply@wireguard.local>
link_only
","text":"false
true
, emails only contain a link to WireGuard Portal, rather than attaching the full configuration.WireGuard Portal supports multiple authentication strategies, including OpenID Connect (oidc
), OAuth (oauth
), Passkeys (webauthn
) and LDAP (ldap
). Each can have multiple providers configured. Below are the relevant keys.
Some core authentication options are shared across all providers, while others are specific to each provider type.
"},{"location":"documentation/configuration/overview/#min_password_length","title":"min_password_length
","text":"16
hide_login_form
","text":"false
true
, the login form is hidden and only the OIDC, OAuth, LDAP, or WebAuthn providers are shown. This is useful if you want to enforce a specific authentication method. If no social login providers are configured, the login form is always shown, regardless of this setting.?all
query parameter to the login URL (e.g. https://wg.portal/#/login?all). The oidc
array contains a list of OpenID Connect providers. Below are the properties for each OIDC provider entry inside auth.oidc
:
provider_name
","text":"display_name
","text":"base_url
","text":"https://accounts.google.com
).client_id
","text":"client_secret
","text":"extra_scopes
","text":"profile
, email
).allowed_domains
","text":"field_map
","text":"Available fields: user_identifier
, email
, firstname
, lastname
, phone
, department
, is_admin
, user_groups
.
user_identifier
sub
or preferred_username
A unique identifier for the user. Often the OIDC sub
claim is used because it\u2019s guaranteed to be unique for the user within the IdP. Some providers also support preferred_username
if it\u2019s unique. email
email
The user\u2019s email address as provided by the IdP. Not always verified, depending on IdP settings. firstname
given_name
The user\u2019s first name, typically provided by the IdP in the given_name
claim. lastname
family_name
The user\u2019s last (family) name, typically provided by the IdP in the family_name
claim. phone
phone_number
The user\u2019s phone number. This may require additional scopes/permissions from the IdP to access. department
Custom claim (e.g., department
) If the IdP can provide organizational data, it may store it in a custom claim. Adjust accordingly (e.g., department
, org
, or another attribute). is_admin
Custom claim or derived role If the IdP returns a role or admin flag, you can map that to is_admin
. Often this is managed through custom claims or group membership. user_groups
groups
or another custom claim A list of group memberships for the user. Some IdPs provide groups
out of the box; others require custom claims or directory lookups. admin_mapping
","text":"is_admin
claim against a regular expression. Alternatively, a regular expression can be used to check if a user is member of a specific group listed in the user_group
claim. The regular expressions are defined in admin_value_regex
and admin_group_regex
.admin_value_regex
: A regular expression to match the is_admin
claim. By default, this expression matches the string \"true\" (^true$
).admin_group_regex
: A regular expression to match the user_groups
claim. Each entry in the user_groups
claim is checked against this regex.registration_enabled
","text":"true
, a new user will be created in WireGuard Portal if not already present.log_user_info
","text":"true
, OIDC user data is logged at the trace level upon login (for debugging).The oauth
array contains a list of plain OAuth2 providers. Below are the properties for each OAuth provider entry inside auth.oauth
:
provider_name
","text":"display_name
","text":"client_id
","text":"client_secret
","text":"auth_url
","text":"token_url
","text":"user_info_url
","text":"scopes
","text":"allowed_domains
","text":"field_map
","text":"Available fields: user_identifier
, email
, firstname
, lastname
, phone
, department
, is_admin
, user_groups
.
user_identifier
sub
or preferred_username
A unique identifier for the user. Often the OIDC sub
claim is used because it\u2019s guaranteed to be unique for the user within the IdP. Some providers also support preferred_username
if it\u2019s unique. email
email
The user\u2019s email address as provided by the IdP. Not always verified, depending on IdP settings. firstname
given_name
The user\u2019s first name, typically provided by the IdP in the given_name
claim. lastname
family_name
The user\u2019s last (family) name, typically provided by the IdP in the family_name
claim. phone
phone_number
The user\u2019s phone number. This may require additional scopes/permissions from the IdP to access. department
Custom claim (e.g., department
) If the IdP can provide organizational data, it may store it in a custom claim. Adjust accordingly (e.g., department
, org
, or another attribute). is_admin
Custom claim or derived role If the IdP returns a role or admin flag, you can map that to is_admin
. Often this is managed through custom claims or group membership. user_groups
groups
or another custom claim A list of group memberships for the user. Some IdPs provide groups
out of the box; others require custom claims or directory lookups. admin_mapping
","text":"is_admin
claim against a regular expression. Alternatively, a regular expression can be used to check if a user is member of a specific group listed in the user_group
claim. The regular expressions are defined in admin_value_regex
and admin_group_regex
.admin_value_regex
: A regular expression to match the is_admin
claim. By default, this expression matches the string \"true\" (^true$
).admin_group_regex
: A regular expression to match the user_groups
claim. Each entry in the user_groups
claim is checked against this regex.registration_enabled
","text":"true
, new users are created automatically on successful login.log_user_info
","text":"true
, logs user info at the trace level upon login.The ldap
array contains a list of LDAP authentication providers. Below are the properties for each LDAP provider entry inside auth.ldap
:
provider_name
","text":"url
","text":"ldap://srv-ad01.company.local:389
).start_tls
","text":"true
, use STARTTLS to secure the LDAP connection.cert_validation
","text":"true
, validate the LDAP server\u2019s TLS certificate.tls_certificate_path
","text":"tls_key_path
","text":"base_dn
","text":"DC=COMPANY,DC=LOCAL
).bind_user
","text":"company\\\\ldap_wireguard
or ldap_wireguard@company.local
).bind_pass
","text":"field_map
","text":"Description: Maps LDAP attributes to WireGuard Portal fields.
user_identifier
, email
, firstname
, lastname
, phone
, department
, memberof
.login_filter
","text":"{{login_identifier}}
to insert the username. For example: (&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2))\n
login_filter
must always be a valid LDAP filter. It should at most return one user. If the filter returns multiple or no users, the login will fail.admin_group
","text":"CN=WireGuardAdmins,OU=Some-OU,DC=YOURDOMAIN,DC=LOCAL\n
sync_interval
","text":"30m
) to synchronize users from LDAP. Empty or 0
disables sync. Format uses s
, m
, h
, d
for seconds, minutes, hours, days, see time.ParseDuration. Only users that match the sync_filter
are synchronized, if disable_missing
is true
, users not found in LDAP are disabled.sync_filter
","text":"(&(objectClass=organizationalPerson)(!userAccountControl:1.2.840.113556.1.4.803:=2)(mail=*))\n
disable_missing
","text":"true
, any user not found in LDAP (during sync) is disabled in WireGuard Portal.auto_re_enable
","text":"true
, users that where disabled because they were missing (see disable_missing
) will be re-enabled once they are found again.registration_enabled
","text":"true
, new user accounts are created in WireGuard Portal upon first login.log_user_info
","text":"true
, logs LDAP user data at the trace level upon login.The webauthn
section contains configuration options for WebAuthn authentication (passkeys).
enabled
","text":"true
true
, Passkey authentication is enabled. If false
, WebAuthn is disabled. Users are encouraged to use Passkeys for secure authentication instead of passwords. If a passkey is registered, the password login is still available as a fallback. Ensure that the password is strong and secure.The web section contains configuration options for the web server, including the listening address, session management, and CSRF protection. It is important to specify a valid external_url
for the web server, especially if you are using a reverse proxy. Without a valid external_url
, the login process may fail due to CSRF protection.
listening_address
","text":":8888
:8888
to bind on all interfaces or 127.0.0.1:8888
to bind only on the loopback interface). Ensure that access to WireGuard Portal is protected against unauthorized access, especially if binding to all interfaces.external_url
","text":"http://localhost:8888
site_company_name
","text":"WireGuard Portal
site_title
","text":"WireGuard Portal
session_identifier
","text":"wgPortalSession
session_secret
","text":"very_secret
csrf_secret
","text":"extremely_secret
request_logging
","text":"false
expose_host_info
","text":"false
cert_file
","text":"key_file
","text":"The webhook section allows you to configure a webhook that is called on certain events in WireGuard Portal. A JSON object is sent in a POST request to the webhook URL with the following structure:
{\n \"event\": \"update\",\n \"entity\": \"peer\",\n \"identifier\": \"the-peer-identifier\",\n \"payload\": {\n // The payload of the event, e.g. peer data.\n // Check the API documentation for the exact structure.\n }\n}\n
Further details can be found in the usage documentation.
"},{"location":"documentation/configuration/overview/#url_1","title":"url
","text":"authentication
","text":"Bearer <token>
.timeout
","text":"10s
Starting from v2, each release includes compiled binaries for supported platforms. These binary versions can be manually downloaded and installed.
"},{"location":"documentation/getting-started/binaries/#download","title":"Download","text":"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-bitWith curl
:
curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64 \n
With wget
:
wget -O wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64\n
with gh cli
:
gh release download ${WG_PORTAL_VERSION} --repo h44z/wg-portal --output wg-portal --pattern '*amd64'\n
"},{"location":"documentation/getting-started/binaries/#install","title":"Install","text":"sudo mkdir -p /opt/wg-portal\nsudo install wg-portal /opt/wg-portal/\n
"},{"location":"documentation/getting-started/binaries/#unreleased-versions-master-branch-builds","title":"Unreleased versions (master branch builds)","text":"Unreleased versions can be fetched directly from the artifacts section of the GitHub Workflow.
"},{"location":"documentation/getting-started/docker/","title":"Docker","text":""},{"location":"documentation/getting-started/docker/#image-usage","title":"Image Usage","text":"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:
---\nservices:\n wg-portal:\n image: wgportal/wg-portal:v2\n container_name: wg-portal\n restart: unless-stopped\n logging:\n options:\n max-size: \"10m\"\n max-file: \"3\"\n cap_add:\n - NET_ADMIN\n # Use host network mode for WireGuard and the UI. Ensure that access to the UI is properly secured.\n network_mode: \"host\"\n volumes:\n # left side is the host path, right side is the container path\n - /etc/wireguard:/etc/wireguard\n - ./data:/app/data\n - ./config:/app/config\n
By default, the webserver for the UI is listening on port 8888 on all available interfaces.
Volumes for /app/data
and /app/config
should be used ensure data persistence across container restarts.
WireGuard Portal supports managing WireGuard interfaces through three distinct deployment methods, providing flexibility based on your system architecture and operational preferences:
Directly on the host system: WireGuard Portal can control WireGuard interfaces natively on the host, without using containers. This setup is ideal for environments where direct access to system networking is preferred. To use this method, you need to set the network mode to host
in your docker-compose.yml file.
services:\n wg-portal:\n ...\n network_mode: \"host\"\n ...\n
If host networking is used, the WireGuard Portal UI will be accessible on all the host's IP addresses if the listening address is set to :8888
in the configuration file. To avoid this, you can bind the listening address to a specific IP address, for example, the loopback address (127.0.0.1:8888
). It is also possible to deploy firewall rules to restrict access to the WireGuard Portal UI.
Within the WireGuard Portal Docker container: WireGuard interfaces can be managed directly from within the WireGuard Portal container itself. This is the recommended approach when running WireGuard Portal via Docker, as it encapsulates all functionality in a single, portable container without requiring a separate WireGuard host or image.
services:\n wg-portal:\n image: wgportal/wg-portal:v2\n container_name: wg-portal\n ...\n cap_add:\n - NET_ADMIN\n ports:\n # host port : container port\n # WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface)\n - \"51820:51820/udp\" \n # Web UI port\n - \"8888:8888/tcp\"\n sysctls:\n - net.ipv4.conf.all.src_valid_mark=1\n volumes:\n # host path : container path\n - ./wg/data:/app/data\n - ./wg/config:/app/config\n
Via a separate Docker container: WireGuard Portal can interface with and control WireGuard running in another Docker container, such as the linuxserver/wireguard image. This method is useful in setups that already use linuxserver/wireguard
or where you want to isolate the VPN backend from the portal frontend. For this, you need to set the network mode to service:wireguard
in your docker-compose.yml file, wireguard
is the service name of your WireGuard container.
services:\n wg-portal:\n image: wgportal/wg-portal:v2\n container_name: wg-portal\n ...\n cap_add:\n - NET_ADMIN\n network_mode: \"service:wireguard\" # So we ensure to stay on the same network as the wireguard container.\n volumes:\n # host path : container path\n - ./wg/etc:/etc/wireguard\n - ./wg/data:/app/data\n - ./wg/config:/app/config\n\n wireguard:\n image: lscr.io/linuxserver/wireguard:latest\n container_name: wireguard\n restart: unless-stopped\n cap_add:\n - NET_ADMIN\n ports:\n # host port : container port\n - \"51820:51820/udp\" # WireGuard port, needs to match the port in wg-portal interface config\n - \"8888:8888/tcp\" # Noticed that the port of the web UI is exposed in the wireguard container.\n volumes:\n - ./wg/etc:/config/wg_confs # We share the configuration (wgx.conf) between wg-portal and wireguard\n sysctls:\n - net.ipv4.conf.all.src_valid_mark=1\n
As the linuxserver/wireguard
image uses wg-quick to manage the interfaces, you need to have at least the following configuration set for WireGuard Portal: core:\n # The WireGuard container uses wg-quick to manage the WireGuard interfaces - this conflicts with WireGuard Portal during startup.\n # To avoid this, we need to set the restore_state option to false so that wg-quick can create the interfaces.\n restore_state: false\n # Usually, there are no existing interfaces in the WireGuard container, so we can set this to false.\n import_existing: false\nadvanced:\n # WireGuard Portal needs to export the WireGuard configuration as wg-quick config files so that the WireGuard container can use them.\n config_storage_path: /etc/wireguard/\n
All images are hosted on Docker Hub at https://hub.docker.com/r/wgportal/wg-portal or in the GitHub Container Registry.
Version 2 is the current stable release. Version 1 has moved to legacy status and is no longer recommended.
There are three types of tags in the repository:
"},{"location":"documentation/getting-started/docker/#semantic-versioned-tags","title":"Semantic versioned tags","text":"For example, 2.0.0-rc.1
or v2.0.0-rc.1
.
These are official releases of WireGuard Portal. For production deployments of WireGuard Portal, we strongly recommend using one of these versioned tags instead of the latest or canary tags.
There are different types of these tags:
v2
or 2
. These tags always refer to the latest image for WireGuard Portal version 2.v2.x
or 2.0
. These tags always refer to the latest image for WireGuard Portal version 2.x.v2.0.0
or 2.0.0
. These tags denote a very specific release. They correspond to the GitHub tags that we make, and you can see the release notes for them here: https://github.com/h44z/wg-portal/releases. Once these tags for a specific version show up in the Docker repository, they will never change. latest
tag","text":"The lastest tag is the latest stable release of WireGuard Portal. For version 2, this is the same as the v2
tag.
master
tag","text":"This is the most recent build to the main branch! It changes a lot and is very unstable.
We recommend that you don't use it except for development purposes or to test the latest features.
"},{"location":"documentation/getting-started/docker/#configuration","title":"Configuration","text":"You can configure WireGuard Portal using a YAML configuration file. The filepath of the YAML configuration file defaults to /app/config/config.yaml
. It is possible to override the configuration filepath using the environment variable WG_PORTAL_CONFIG.
By default, WireGuard Portal uses an SQLite database. The database is stored in /app/data/sqlite.db
.
You should mount those directories as a volume:
/app/data
/app/config
A detailed description of the configuration options can be found here.
If you want to access configuration files in wg-quick format, you can mount the /etc/wireguard
directory inside the container to a location of your choice. Also enable the config_storage_path
option in the configuration file:
advanced:\n config_storage_path: /etc/wireguard\n
"},{"location":"documentation/getting-started/helm/","title":"Helm","text":""},{"location":"documentation/getting-started/helm/#installing-the-chart","title":"Installing the Chart","text":"To install the chart with the release name wg-portal
:
helm install wg-portal oci://ghcr.io/h44z/charts/wg-portal\n
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.
"},{"location":"documentation/getting-started/helm/#values","title":"Values","text":"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 10
The 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 false
Whether 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 8888
Web 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 false
Specifies whether an ingress resource should be created ingress.className string \"\"
Ingress class name ingress.annotations object {}
Ingress annotations ingress.tls bool false
Ingress TLS configuration. Enable certificate resource or add ingress annotation to create required secret certificate.enabled bool false
Specifies 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 false
Specifies 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 true
Specifies whether a service account should be created serviceAccount.annotations object {}
Service account annotations serviceAccount.automount bool false
Automatically 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 false
Enable 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 1m
Interval 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 false
Enable 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."},{"location":"documentation/getting-started/reverse-proxy/","title":"Reverse Proxy (HTTPS)","text":""},{"location":"documentation/getting-started/reverse-proxy/#reverse-proxy-for-https","title":"Reverse Proxy for HTTPS","text":"For production deployments, always serve the WireGuard Portal over HTTPS. You have two options to secure your connection:
"},{"location":"documentation/getting-started/reverse-proxy/#reverse-proxy","title":"Reverse Proxy","text":"Let a front\u2010end 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:\n reverse-proxy:\n image: traefik:v3.3\n restart: unless-stopped\n command:\n #- '--log.level=DEBUG'\n - '--providers.docker.endpoint=unix:///var/run/docker.sock'\n - '--providers.docker.exposedbydefault=false'\n - '--entrypoints.web.address=:80'\n - '--entrypoints.websecure.address=:443'\n - '--entrypoints.websecure.http3'\n - '--certificatesresolvers.letsencryptresolver.acme.httpchallenge=true'\n - '--certificatesresolvers.letsencryptresolver.acme.httpchallenge.entrypoint=web'\n - '--certificatesresolvers.letsencryptresolver.acme.email=your.email@domain.com'\n - '--certificatesresolvers.letsencryptresolver.acme.storage=/letsencrypt/acme.json'\n #- '--certificatesresolvers.letsencryptresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory' # just for testing\n ports:\n - 80:80 # for HTTP\n - 443:443/tcp # for HTTPS\n - 443:443/udp # for HTTP/3\n volumes:\n - acme-certs:/letsencrypt\n - /var/run/docker.sock:/var/run/docker.sock:ro\n labels:\n - 'traefik.enable=true'\n # HTTP Catchall for redirecting HTTP -> HTTPS\n - 'traefik.http.routers.dashboard-catchall.rule=Host(`wg.domain.com`) && PathPrefix(`/`)'\n - 'traefik.http.routers.dashboard-catchall.entrypoints=web'\n - 'traefik.http.routers.dashboard-catchall.middlewares=redirect-to-https'\n - 'traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https'\n\n wg-portal:\n image: wgportal/wg-portal:v2\n container_name: wg-portal\n restart: unless-stopped\n logging:\n options:\n max-size: \"10m\"\n max-file: \"3\"\n cap_add:\n - NET_ADMIN\n ports:\n # host port : container port\n # WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface)\n - \"51820:51820/udp\"\n # Web UI port (only available on localhost, Traefik will handle the HTTPS)\n - \"127.0.0.1:8888:8888/tcp\"\n sysctls:\n - net.ipv4.conf.all.src_valid_mark=1\n volumes:\n # host path : container path\n - ./wg/data:/app/data\n - ./wg/config:/app/config\n labels:\n - 'traefik.enable=true'\n - 'traefik.http.routers.wgportal.rule=Host(`wg.domain.com`)'\n - 'traefik.http.routers.wgportal.entrypoints=websecure'\n - 'traefik.http.routers.wgportal.tls.certresolver=letsencryptresolver'\n - 'traefik.http.routers.wgportal.service=wgportal'\n - 'traefik.http.services.wgportal.loadbalancer.server.port=8888'\n\nvolumes:\n acme-certs:\n
The WireGuard Portal configuration must be updated accordingly so that the correct external URL is set for the web interface:
web:\n external_url: https://wg.domain.com\n
"},{"location":"documentation/getting-started/reverse-proxy/#built-in-tls","title":"Built-in TLS","text":"If you prefer to let WireGuard Portal handle TLS itself, you can use the built-in TLS support. In your config.yaml
, under the web
section, point to your certificate and key files:
web:\n cert_file: /path/to/your/fullchain.pem\n key_file: /path/to/your/privkey.pem\n
The web server will then use these files to serve HTTPS traffic directly instead of HTTP.
"},{"location":"documentation/getting-started/sources/","title":"Sources","text":"To build the application from source files, use the Makefile provided in the repository.
"},{"location":"documentation/getting-started/sources/#requirements","title":"Requirements","text":">=1.24.0
node>=18, npm>=9
# Get source code\ngit clone https://github.com/h44z/wg-portal -b ${WG_PORTAL_VERSION:-master} --depth 1\ncd wg-portal\n# Build the frontend\nmake frontend\n# Build the backend\nmake build\n
"},{"location":"documentation/getting-started/sources/#install","title":"Install","text":"Compiled binary will be available in ./dist
directory.
For installation instructions, check the Binaries section.
"},{"location":"documentation/monitoring/prometheus/","title":"Monitoring","text":"By default, WG-Portal exposes Prometheus metrics on port 8787
if interface/peer statistic data collection is enabled.
wireguard_interface_received_bytes_total
gauge Bytes received through the interface. wireguard_interface_sent_bytes_total
gauge Bytes sent through the interface. wireguard_peer_last_handshake_seconds
gauge Seconds from the last handshake with the peer. wireguard_peer_received_bytes_total
gauge Bytes received from the peer. wireguard_peer_sent_bytes_total
gauge Bytes sent to the peer. wireguard_peer_up
gauge Peer connection state (boolean: 1/0)."},{"location":"documentation/monitoring/prometheus/#prometheus-config","title":"Prometheus Config","text":"Add the following scrape job to your Prometheus config file:
# prometheus.yaml\nscrape_configs:\n - job_name: wg-portal\n scrape_interval: 60s\n static_configs:\n - targets:\n - localhost:8787 # Change localhost to IP Address or hostname with WG-Portal\n
"},{"location":"documentation/monitoring/prometheus/#grafana-dashboard","title":"Grafana Dashboard","text":"You may import dashboard.json
into your Grafana instance.
Major upgrades between different versions may require special procedures, which are described in the following sections.
"},{"location":"documentation/upgrade/v1/#upgrade-from-v1-to-v2","title":"Upgrade from v1 to v2","text":"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\n
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'\n
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:\n wg-portal:\n image: wgportal/wg-portal:v2\n # ... other settings\n restart: no\n command: [\"-migrateFrom=/app/data/old_wg_portal.db\"]\n
"},{"location":"documentation/usage/general/","title":"General","text":"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.
"},{"location":"documentation/usage/general/#basic-concepts","title":"Basic Concepts","text":"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
or Client
after importing the interface. 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 section for more information on securing the web UI.
So the default URL to access the web UI is:
http://localhost:8888\n
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!
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.
The interface view provides an overview of the WireGuard interfaces and peers configured in WireGuard Portal.
The most important elements are:
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. When someone logs in via LDAP, their specific provider is remembered, so there's no risk of cross-provider conflicts. Details on the log-in process can be found in the Security documentation.
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.
"},{"location":"documentation/usage/ldap/#ldap-synchronization","title":"LDAP Synchronization","text":"WireGuard Portal can automatically synchronize users from LDAP to the database. To enable 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.
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:\n ldap:\n - id: ldap\n # ... other settings\n sync_filter: (mail=*)\n
"},{"location":"documentation/usage/ldap/#disable-missing-users","title":"Disable Missing Users","text":"If you set the disable_missing
property to true
, any user that is not found in LDAP during synchronization will be disabled in WireGuard Portal. All peers associated with that user will also be disabled.
If you want a user and its peers to be automatically re-enabled once they are found in LDAP again, set the auto_re_enable
property to true
. This will only re-enable the user if they where disabled by the synchronization process. Manually disabled users will not be re-enabled.
This section describes the security features available to administrators for hardening WireGuard Portal and protecting its data.
"},{"location":"documentation/usage/security/#authentication","title":"Authentication","text":"WireGuard Portal supports multiple authentication methods, including:
Users can have two roles which limit their permissions in WireGuard Portal:
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.
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.
"},{"location":"documentation/usage/security/#oauth-and-oidc-authentication","title":"OAuth and OIDC Authentication","text":"WireGuard Portal supports OAuth and OIDC authentication. You can use any OAuth or OIDC provider that supports the authorization code flow, such as Google, GitHub, or Keycloak.
For OAuth 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 OAuth authentication to WireGuard Portal, create a Client-ID and Client-Secret in your OAuth 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.
You can limit the login to specific domains by setting the allowed_domains
property for OAuth 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:\n oidc:\n - provider_name: \"oidc1\"\n # ... other settings\n allowed_domains:\n - \"outlook.com\"\n
"},{"location":"documentation/usage/security/#limit-login-to-existing-users","title":"Limit Login to Existing Users","text":"You can limit the login to existing users only by setting the registration_enabled
property to false
for OAuth or OIDC providers. If registration is enabled, new users will be created in the database when they log in for the first time.
You can map users to admin roles based on their attributes in the OAuth or OIDC provider. To do this, set the admin_mapping
property for the provider. Administrative access can either be mapped by a specific attribute or by group membership.
Attribute specific mapping can be achieved by setting the admin_value_regex
and the is_admin
property. The admin_value_regex
property is a regular expression that is matched against the value of the is_admin
attribute. The user is granted admin access if the regex matches the attribute value.
Example:
auth:\n oidc:\n - provider_name: \"oidc1\"\n # ... other settings\n field_map:\n is_admin: \"wg_admin_prop\"\n admin_mapping:\n admin_value_regex: \"^true$\"\n
The example above will grant admin access to users with the wg_admin_prop
attribute set to true
. Group membership mapping can be achieved by setting the admin_group_regex
and user_groups
property. The admin_group_regex
property is a regular expression that is matched against the group names of the user. The user is granted admin access if the regex matches any of the group names.
Example:
auth:\n oidc:\n - provider_name: \"oidc1\"\n # ... other settings\n field_map:\n user_groups: \"groups\"\n admin_mapping:\n admin_group_regex: \"^the-admin-group$\"\n
The example above will grant admin access to users who are members of the the-admin-group
group."},{"location":"documentation/usage/security/#ldap-authentication","title":"LDAP Authentication","text":"WireGuard Portal supports LDAP authentication. You can use any LDAP server that supports the LDAP protocol, such as Active Directory or OpenLDAP. Multiple LDAP servers can be configured in the auth
section of the configuration file. WireGuard Portal remembers the authentication provider of the user and therefore avoids conflicts between multiple LDAP providers.
To configure LDAP authentication, create a new ldap
authentication provider in the auth
section of the configuration file.
You can limit the login to specific users by setting the login_filter
property for LDAP provider. This filter uses the LDAP search filter syntax. The username can be inserted into the query by placing the {{login_identifier}}
placeholder in the filter. This placeholder will then be replaced with the username entered by the user during login.
For example, if you want to allow only users with the objectClass
attribute set to organizationalPerson
to log in, set the property as follows:
auth:\n ldap:\n - provider_name: \"ldap1\"\n # ... other settings\n login_filter: \"(&(objectClass=organizationalPerson)(uid={{login_identifier}}))\"\n
The login_filter
should always be designed to return at most one user.
You can limit the login to existing users only by setting the registration_enabled
property to false
for LDAP providers. If registration is enabled, new users will be created in the database when they log in for the first time.
You can map users to admin roles based on their group membership in the LDAP server. To do this, set the admin_group
and memberof
property for the provider. The admin_group
property defines the distinguished name of the group that is allowed to log in as admin. All groups that are listed in the memberof
attribute of the user will be checked against this group. If one of the groups matches, the user is granted admin 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.
"},{"location":"documentation/usage/security/#https","title":"HTTPS","text":"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.
"},{"location":"documentation/usage/webhooks/","title":"Webhooks","text":"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.
"},{"location":"documentation/usage/webhooks/#configuration","title":"Configuration","text":"All available configuration options for webhooks can be found in the configuration overview.
A basic webhook configuration looks like this:
webhook:\n url: https://your-service.example.com/webhook\n
"},{"location":"documentation/usage/webhooks/#security","title":"Security","text":"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:\n url: https://your-service.example.com/webhook\n secret: \"Basic dXNlcm5hbWU6cGFzc3dvcmQ=\"\n
You should also make sure that your webhook endpoint is secured with HTTPS to prevent eavesdropping and tampering.
"},{"location":"documentation/usage/webhooks/#available-events","title":"Available Events","text":"WireGuard Portal supports various events that can trigger webhooks. The following events are available:
create
: Triggered when a new entity is created.update
: Triggered when an existing entity is updated.delete
: Triggered when an entity is deleted.connect
: Triggered when a user connects to the VPN.disconnect
: Triggered when a user disconnects from the VPN.The following entity types can trigger webhooks:
user
: When a WireGuard Portal user is created, updated, or deleted.peer
: When a peer is created, updated, or deleted. This entity can also trigger connect
and disconnect
events.interface
: When a device is created, updated, or deleted.All webhook events send a JSON payload containing relevant data. The structure of the payload depends on the event type and entity involved. A common shell structure for webhook payloads is as follows:
{\n \"event\": \"create\",\n \"entity\": \"user\",\n \"identifier\": \"the-user-identifier\",\n \"payload\": {\n // The payload of the event, e.g. peer data.\n // Check the API documentation for the exact structure.\n }\n}\n
"},{"location":"documentation/usage/webhooks/#example-payload","title":"Example Payload","text":"The following payload is an example of a webhook event when a peer connects to the VPN:
{\n \"event\": \"connect\",\n \"entity\": \"peer\",\n \"identifier\": \"Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=\",\n \"payload\": {\n \"PeerId\": \"Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=\",\n \"IsConnected\": true,\n \"IsPingable\": false,\n \"LastPing\": null,\n \"BytesReceived\": 1860,\n \"BytesTransmitted\": 10824,\n \"LastHandshake\": \"2025-06-26T23:04:33.325216659+02:00\",\n \"Endpoint\": \"10.55.66.77:33874\",\n \"LastSessionStart\": \"2025-06-26T22:50:40.10221606+02:00\"\n }\n}\n
"}]}