WireGuard Portal

https://wgportal.org/latest/documentation/
Admin
WireGuard Portal is a self-hosted, web-based configuration portal for managing WireGuard servers,...
Tokens:18,430
Snippets:230
Trust Score:6.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Enable and Start wg-portal Service

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Enable the wg-portal service to start on boot and start it immediately.

```bash
sudo systemctl enable --now wg-portal.service

```

--------------------------------

### Install Downloaded Binary

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Install the downloaded wg-portal binary to /opt/wg-portal and ensure it is executable.

```bash
sudo mkdir -p /opt/wg-portal
sudo install wg-portal /opt/wg-portal/

```

--------------------------------

### Build wg-portal from Source

Source: https://wgportal.org/latest/documentation/getting-started/sources

Clone the repository and build the frontend and backend. Ensure you have Git, Make, Go (>=1.25.0), and Node.js with npm (>=18, >=9) installed.

```bash
# Get source code
git clone https://github.com/h44z/wg-portal -b ${WG_PORTAL_VERSION:-master} --depth 1
cd wg-portal
# Build the frontend
make frontend
# Build the backend
make build
```

--------------------------------

### Minimal Deny-by-Group Example for OAuth2

Source: https://wgportal.org/latest/documentation/usage/authentication

This example demonstrates a minimal configuration to deny login unless the user is part of the 'vpn-users' group, using OAuth2 authentication.

```yaml
auth:
  oauth:
    - provider_name: "oauth1"
      # ... other settings
      allowed_user_groups:
        - "vpn-users"
      field_map:
        user_groups: "groups"

```

--------------------------------

### Migrate from SQLite Database

Source: https://wgportal.org/latest/documentation/upgrade/v1

Start the wg-portal binary with the -migrateFrom parameter to initiate the upgrade process from an old SQLite database. Ensure the config.yaml is updated and valid beforehand.

```bash
./wg-portal-amd64 -migrateFrom=old_wg_portal.db
```

--------------------------------

### Configure pfSense Backend

Source: https://wgportal.org/latest/documentation/usage/backends

Example configuration for a pfSense backend in WireGuard Portal. This backend manages interfaces on pfSense firewalls via the REST API.

```yaml
backend:
  # default backend decides where new interfaces are created
  default: pfsense1

  pfsense:
    - id: pfsense1                 # unique id, not "local"
      display_name: Main pfSense   # optional nice name
      api_url: https://pfsense.example.com  # no trailing /api/v2
      api_key: your-api-key
      api_verify_tls: true
      api_timeout: 30s
      concurrency: 5
      debug: false

```

--------------------------------

### Install wg-portal Helm Chart

Source: https://wgportal.org/latest/documentation/getting-started/helm

Use this command to install the wg-portal on your Kubernetes cluster with the release name 'wg-portal'. The default configuration will be applied.

```bash
helm install wg-portal oci://ghcr.io/h44z/charts/wg-portal

```

--------------------------------

### Database DSN Example

Source: https://wgportal.org/latest/documentation/configuration/overview

Example of a Data Source Name (DSN) for connecting to a MySQL database. Ensure the format matches your database provider's requirements.

```sql
user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local

```

--------------------------------

### Configure MikroTik Backend

Source: https://wgportal.org/latest/documentation/usage/backends

Example configuration for a MikroTik backend in WireGuard Portal. This backend manages interfaces on MikroTik RouterOS devices via the REST API.

```yaml
backend:
  # default backend decides where new interfaces are created
  default: mikrotik-prod

  mikrotik:
    - id: mikrotik-prod              # unique id, not "local"
      display_name: RouterOS RB5009  # optional nice name
      api_url: https://10.10.10.10/rest
      api_user: wgportal
      api_password: a-super-secret-password
      api_verify_tls: true         # set to false only if using self-signed during testing
      api_timeout: 30s             # maximum request duration
      concurrency: 5               # limit parallel REST calls to device
      debug: false                 # verbose logging for this backend

```

--------------------------------

### OpenID Connect (OIDC) Authentication

Source: https://wgportal.org/latest/documentation/configuration/examples

This section is intended for OpenID Connect (OIDC) authentication configuration, but no specific code example is provided in the source.

--------------------------------

### Docker Compose Upgrade Configuration

Source: https://wgportal.org/latest/documentation/upgrade/v1

Adapt your docker-compose.yml file to start the upgrade process by specifying the v2 image and the -migrateFrom command-line argument for the old database file within the container.

```yaml
services:
  wg-portal:
    image: wgportal/wg-portal:v2
    # ... other settings
    restart: no
    command: ["-migrateFrom=/app/data/old_wg_portal.db"]
```

--------------------------------

### LDAP Sync Filter Example

Source: https://wgportal.org/latest/documentation/configuration/overview

This filter selects which users are synchronized from LDAP into WireGuard Portal. It includes common criteria for active user accounts with an email address.

```text
(&(objectClass=organizationalPerson)(!userAccountControl:1.2.840.113556.1.4.803:=2)(mail=*))
```

--------------------------------

### LDAP Login Filter Example

Source: https://wgportal.org/latest/documentation/configuration/overview

Use this filter to restrict which users can log in. The `{{login_identifier}}` placeholder is replaced with the username provided during login. Ensure the filter returns at most one user.

```text
(&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2))
```

--------------------------------

### Create wg-portal systemd Service Unit File

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Create and configure the wg-portal systemd service unit file using 'systemctl edit'. Adjust variables as needed.

```systemd
[Unit]
Description=WireGuard Portal
ConditionPathExists=/opt/wg-portal/wg-portal
After=network.target

[Service]
Type=simple
User=root
Group=root
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW

Restart=on-failure
RestartSec=10

WorkingDirectory=/opt/wg-portal
Environment=WG_PORTAL_CONFIG=/opt/wg-portal/config.yml
ExecStart=/opt/wg-portal/wg-portal

[Install]
WantedBy=multi-user.target

```

--------------------------------

### Enable wg-quick Configuration Storage

Source: https://wgportal.org/latest/documentation/getting-started/docker

Configure WireGuard Portal to store wg-quick configuration files by setting the `config_storage_path` option in the YAML configuration. This requires mounting the `/etc/wireguard` directory as a volume.

```yaml
advanced:
  config_storage_path: /etc/wireguard

```

--------------------------------

### Download Released Binary with wget

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Use wget to download a specific released version of the wg-portal binary for Linux amd64 architecture.

```bash
wget -O wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64

```

--------------------------------

### Migrate from Other Database Types

Source: https://wgportal.org/latest/documentation/upgrade/v1

Specify the database type using -migrateFromType and provide the connection string for databases like MySQL, MSSQL, or PostgreSQL. The upgrade process transforms the old database and stores values in the new database defined in config.yaml. Ensure the new database is empty.

```bash
./wg-portal-amd64 -migrateFromType=mysql -migrateFrom='user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local'
```

--------------------------------

### Download Released Binary with gh cli

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Use the GitHub CLI to download a specific released version of the wg-portal binary, filtering for amd64 architecture.

```bash
gh release download ${WG_PORTAL_VERSION} --repo h44z/wg-portal --output wg-portal --pattern '*amd64'

```

--------------------------------

### Google Authentication with Admin Mapping by Attribute

Source: https://wgportal.org/latest/documentation/configuration/examples

Set up Google authentication where users with a 'wg_admin' attribute set to 'true' are designated as administrators. User information logging is enabled.

```yaml
auth:
  oidc:
    - provider_name: google
      display_name: Login with</br>Google
      base_url: https://accounts.google.com
      client_id: the-client-id-1234.apps.googleusercontent.com
      client_secret: A_CLIENT_SECRET
      extra_scopes:
        - https://www.googleapis.com/auth/userinfo.email
        - https://www.googleapis.com/auth/userinfo.profile
      field_map:
        user_identifier: sub
        email: email
        firstname: given_name
        lastname: family_name
        phone: phone_number
        department: department
        is_admin: wg_admin
      admin_mapping:
        admin_value_regex: ^true$
      registration_enabled: true
      log_user_info: true
```

--------------------------------

### Basic Configuration

Source: https://wgportal.org/latest/documentation/configuration/examples

This snippet shows fundamental settings for the WireGuard portal, covering core, backend, web, advanced, database, and authentication parameters.

```yaml
core:
  admin_user: test@example.com
  admin_password: password
  admin_api_token: super-s3cr3t-api-token-or-a-UUID
  import_existing: false
  create_default_peer_on_login: true
  self_provisioning_allowed: true

backend:
  # default backend decides where new interfaces are created
  default: mikrotik

  # A prefix for resolvconf. Usually it is "tun.". If you are using systemd, the prefix should be empty.
  local_resolvconf_prefix: "tun."

  mikrotik:
    - id: mikrotik                   # unique id, not "local"
      display_name: RouterOS RB5009  # optional nice name
      api_url: https://10.10.10.10/rest
      api_user: wgportal
      api_password: a-super-secret-password
      api_verify_tls: false        # set to false only if using self-signed during testing
      api_timeout: 30s             # maximum request duration
      concurrency: 5               # limit parallel REST calls to device
      debug: false                 # verbose logging for this backend
      ignored_interfaces:          # ignore these interfaces during import
      - wgTest1
      - wgTest2

web:
  site_title: My WireGuard Server
  site_company_name: My Company
  listening_address: ":8080"
  external_url: https://my.external-domain.com
  csrf_secret: super-s3cr3t-csrf
  session_secret: super-s3cr3t-session
  request_logging: true

advanced:
  log_level: trace
  log_pretty: true
  log_json: false
  config_storage_path: /etc/wireguard
  expiry_check_interval: 5m

database:
  debug: true
  type: sqlite
  dsn: data/sqlite.db
  encryption_passphrase: change-this-s3cr3t-encryption-passphrase

auth:
  webauthn:
    enabled: true

```

--------------------------------

### WireGuard Portal Configuration for wg-quick

Source: https://wgportal.org/latest/documentation/getting-started/docker

Configure WireGuard Portal to work with the linuxserver/wireguard image by setting 'restore_state' to false and 'import_existing' to false, and specifying the 'config_storage_path'.

```yaml
core:
  # The WireGuard container uses wg-quick to manage the WireGuard interfaces - this conflicts with WireGuard Portal during startup.
  # To avoid this, we need to set the restore_state option to false so that wg-quick can create the interfaces.
  restore_state: false
  # Usually, there are no existing interfaces in the WireGuard container, so we can set this to false.
  import_existing: false
advanced:
  # WireGuard Portal needs to export the WireGuard configuration as wg-quick config files so that the WireGuard container can use them.
  config_storage_path: /etc/wireguard/
```

--------------------------------

### Basic Webhook Configuration

Source: https://wgportal.org/latest/documentation/usage/webhooks

A minimal configuration to enable webhooks. Ensure the URL points to your external service endpoint.

```yaml
webhook:
  url: https://your-service.example.com/webhook

```

--------------------------------

### Download Released Binary with curl

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Use curl to download a specific released version of the wg-portal binary for Linux amd64 architecture.

```bash
curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64 

```

--------------------------------

### Docker Compose Configuration for WireGuard Portal

Source: https://wgportal.org/latest/documentation/getting-started/docker

Use this Docker Compose configuration to deploy the WireGuard Portal. It sets up the container, manages logging, grants necessary capabilities, and configures network and volume settings for WireGuard interfaces and persistent data.

```yaml
---
services:
  wg-portal:
    image: wgportal/wg-portal:v2
    container_name: wg-portal
    restart: unless-stopped
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    cap_add:
      - NET_ADMIN
    # Use host network mode for WireGuard and the UI. Ensure that access to the UI is properly secured.
    network_mode: "host"
    volumes:
      # left side is the host path, right side is the container path
      - /etc/wireguard:/etc/wireguard
      - ./data:/app/data
      - ./config:/app/config

```

--------------------------------

### WireGuard Portal Configuration with Base Path

Source: https://wgportal.org/latest/documentation/getting-started/reverse-proxy

Configure the WireGuard Portal to be available at a specific base path when using a reverse proxy.

```yaml
web:
  external_url: https://wg.domain.com
  base_path: /subpath

```

--------------------------------

### Default WireGuard Portal Configuration

Source: https://wgportal.org/latest/documentation/configuration/overview

This is the default configuration structure for WireGuard Portal, presented in YAML format. It outlines all available settings across various sections like core, backend, and advanced.

```yaml
core:
  admin_user: admin@wgportal.local
  admin_password: wgportal-default
  admin_api_token: ""
  disable_admin_user: false
  editable_keys: true
  create_default_peer: false
  create_default_peer_on_creation: false
  re_enable_peer_after_user_enable: true
  delete_peer_after_user_deleted: false
  self_provisioning_allowed: true
  import_existing: true
  restore_state: true

backend:
  default: local
  rekey_timeout_interval: 125s
  local_resolvconf_prefix: tun.

advanced:
  log_level: info
  log_pretty: false
  log_json: false
  start_listen_port: 51820
  start_cidr_v4: 10.11.12.0/24
  start_cidr_v6: fdfd:d3ad:c0de:1234::0/64
  use_ip_v6: true
  config_storage_path: ""
  expiry_check_interval: 15m
  rule_prio_offset: 20000
  route_table_offset: 20000
  api_admin_only: true
  limit_additional_user_peers: 0

database:
  debug: false
  slow_query_threshold: "0"
  type: sqlite
  dsn: data/sqlite.db
  encryption_passphrase: ""

statistics:
  use_ping_checks: true
  ping_check_workers: 10
  ping_unprivileged: false
  ping_check_interval: 1m
  data_collection_interval: 1m
  collect_interface_data: true
  collect_peer_data: true
  collect_audit_data: true
  listening_address: ":8787"

mail:
  host: 127.0.0.1
  port: 25
  encryption: none
  cert_validation: true
  username: ""
  password: ""
  auth_type: plain
  from: Wireguard Portal <noreply@wireguard.local>
  link_only: false
  allow_peer_email: false
  templates_path: ""

auth:
  oidc: []
  oauth: []
  ldap: []
  webauthn:
    enabled: true
  min_password_length: 16
  hide_login_form: false

web:
  listening_address: ":8888"
  external_url: http://localhost:8888
  base_path: ""
  site_company_name: WireGuard Portal
  site_title: WireGuard Portal
  session_identifier: wgPortalSession
  session_secret: very_secret
  csrf_secret: extremely_secret
  request_logging: false
  expose_host_info: false
  cert_file: ""
  key_File: ""
  frontend_filepath: ""

webhook:
  url: ""
  authentication: ""
  timeout: 10s

```

--------------------------------

### Google Authentication with Admin Mapping by Group

Source: https://wgportal.org/latest/documentation/configuration/examples

Configure Google authentication where users belonging to the 'the-admin-group' or 'vpn-users' group are considered administrators. User information logging is enabled.

```yaml
auth:
  oidc:
    - provider_name: google2
      display_name: Login with</br>Google2
      base_url: https://accounts.google.com
      client_id: another-client-id-1234.apps.googleusercontent.com
      client_secret: A_CLIENT_SECRET
      extra_scopes:
        - https://www.googleapis.com/auth/userinfo.email
        - https://www.googleapis.com/auth/userinfo.profile
      allowed_user_groups:
        - the-admin-group
        - vpn-users
      field_map:
        user_identifier: sub
        email: email
        firstname: given_name
        lastname: family_name
        phone: phone_number
        department: department
        user_groups: groups
      admin_mapping:
        admin_group_regex: ^the-admin-group$
      registration_enabled: true
      log_user_info: true
```

--------------------------------

### Plain OAuth2 Google Authentication with Admin Mapping by Attribute

Source: https://wgportal.org/latest/documentation/configuration/examples

Set up plain OAuth2 for Google, designating users with the 'this-attribute-must-be-true' attribute as administrators. Requires specific auth, token, and user info URLs.

```yaml
auth:
  oauth:
    - provider_name: google3
      display_name: Login with</br>Google3
      client_id: another-client-id-1234.apps.googleusercontent.com
      client_secret: A_CLIENT_SECRET
      auth_url: https://accounts.google.com/o/oauth2/v2/auth
      token_url: https://oauth2.googleapis.com/token
      user_info_url: https://openidconnect.googleapis.com/v1/userinfo
      scopes:
        - openid
        - email
        - profile
      field_map:
        user_identifier: sub
        email: email
        firstname: name
        is_admin: this-attribute-must-be-true
      admin_mapping:
        admin_value_regex: ^(True|true)$
      registration_enabled: true
```

--------------------------------

### Configure systemd-networkd to Manage Foreign Routing Policy

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Configure systemd-networkd to prevent it from removing routing policies created by wg-portal upon restart.

```bash
sudo mkdir --parents /etc/systemd/networkd.conf.d/
sudo tee --append /etc/systemd/networkd.conf.d/foreign-routing.conf <<EOF
[Network]
ManageForeignRoutingPolicyRules=no
EOF
sudo systemctl restart systemd-networkd.service
sudo systemctl status systemd-networkd.service

```

--------------------------------

### WireGuard Portal Configuration for External URL

Source: https://wgportal.org/latest/documentation/getting-started/reverse-proxy

Configure the WireGuard Portal's web interface to use the external URL provided by the reverse proxy.

```yaml
web:
  external_url: https://wg.domain.com

```

--------------------------------

### Deploy WireGuard Portal within its Container

Source: https://wgportal.org/latest/documentation/getting-started/docker

Recommended Docker deployment for WireGuard Portal, managing interfaces within the container. Requires NET_ADMIN capability and specific port mappings.

```yaml
services:
  wg-portal:
    image: wgportal/wg-portal:v2
    container_name: wg-portal
    ...
    cap_add:
      - NET_ADMIN
    ports:
      # host port : container port
      # WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface)
      - "51820:51820/udp"
      # Web UI port
      - "8888:8888/tcp"
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    volumes:
      # host path : container path
      - ./wg/data:/app/data
      - ./wg/config:/app/config
```

--------------------------------

### WireGuard Portal Built-in TLS Configuration

Source: https://wgportal.org/latest/documentation/getting-started/reverse-proxy

Configure the WireGuard Portal to handle TLS directly by specifying the paths to your certificate and key files.

```yaml
web:
  cert_file: /path/to/your/fullchain.pem
  key_file:  /path/to/your/privkey.pem

```

--------------------------------

### Set Network Mode to Host

Source: https://wgportal.org/latest/documentation/getting-started/docker

Configure WireGuard Portal to control WireGuard interfaces natively on the host system by setting the network mode to 'host' in your docker-compose.yml.

```yaml
services:
  wg-portal:
    ...
    network_mode: "host"
    ...
```

--------------------------------

### Deploy WireGuard Portal with a Separate WireGuard Container

Source: https://wgportal.org/latest/documentation/getting-started/docker

Configure WireGuard Portal to interface with WireGuard running in another Docker container using 'service:wireguard' network mode. Requires shared volumes for configuration.

```yaml
services:
  wg-portal:
    image: wgportal/wg-portal:v2
    container_name: wg-portal
    ...
    cap_add:
      - NET_ADMIN
    network_mode: "service:wireguard" # So we ensure to stay on the same network as the wireguard container.
    volumes:
      # host path : container path
      - ./wg/etc:/etc/wireguard
      - ./wg/data:/app/data
      - ./wg/config:/app/config

  wireguard:
    image: lscr.io/linuxserver/wireguard:latest
    container_name: wireguard
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    ports:
      # host port : container port
      - "51820:51820/udp" # WireGuard port, needs to match the port in wg-portal interface config
      - "8888:8888/tcp" # Noticed that the port of the web UI is exposed in the wireguard container.
    volumes:
      - ./wg/etc:/config/wg_confs # We share the configuration (wgx.conf) between wg-portal and wireguard
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
```

--------------------------------

### Prometheus Scrape Job Configuration

Source: https://wgportal.org/latest/documentation/monitoring/prometheus

Add this scrape job to your Prometheus configuration file to collect metrics from WG-Portal. Ensure the target address is correctly set to your WG-Portal instance.

```yaml
# prometheus.yaml
scrape_configs:
  - job_name: wg-portal
    scrape_interval: 60s
    static_configs:
      - targets:
          - localhost:8787 # Change localhost to IP Address or hostname with WG-Portal

```

--------------------------------

### Configure Custom Mail Templates Path

Source: https://wgportal.org/latest/documentation/usage/mail-templates

Set the `mail.templates_path` option in your application configuration or use the `WG_PORTAL_MAIL_TEMPLATES_PATH` environment variable to specify the directory for custom email templates.

```yaml
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
  # will be written there so you can modify them.
  # Leave empty to use embedded templates only.
  templates_path: "/opt/wg-portal/mail-templates"

```

--------------------------------

### Access WireGuard Portal Web UI

Source: https://wgportal.org/latest/documentation/usage/general

The default URL to access the WireGuard Portal web UI. Ensure to check the configuration file for the correct external URL and port.

```text
http://localhost:8888
```

--------------------------------

### OAuth2/OIDC Callback URL Format

Source: https://wgportal.org/latest/documentation/usage/authentication

This is the format for the callback/redirect URL when registering an OAuth2 or OIDC application with your provider. Ensure `<external_url>` and `<provider_name>` are correctly substituted.

```text
<external_url>/api/v0/auth/login/<provider_name>/callback

```

--------------------------------

### Plain OAuth2 Google Authentication with Combined Admin Mapping

Source: https://wgportal.org/latest/documentation/configuration/examples

Configure plain OAuth2 for Google, granting admin status to users based on either the 'this-attribute-must-be-true' attribute or membership in the 'admin-group-name' group. User information logging is enabled.

```yaml
auth:
  oauth:
    - provider_name: google4
      display_name: Login with</br>Google4
      client_id: another-client-id-1234.apps.googleusercontent.com
      client_secret: A_CLIENT_SECRET
      auth_url: https://accounts.google.com/o/oauth2/v2/auth
      token_url: https://oauth2.googleapis.com/token
      user_info_url: https://openidconnect.googleapis.com/v1/userinfo
      scopes:
        - openid
        - email
        - profile
        - i-want-some-groups
      allowed_user_groups:
        - admin-group-name
        - vpn-users
      field_map:
        email: email
        firstname: name
        user_identifier: sub
        is_admin: this-attribute-must-be-true
        user_groups: groups
      admin_mapping:
        admin_value_regex: ^true$
        admin_group_regex: ^admin-group-name$
      registration_enabled: true
      log_user_info: true
```

--------------------------------

### LDAP Authentication and Synchronization

Source: https://wgportal.org/latest/documentation/configuration/examples

This snippet configures LDAP authentication and synchronization for the WireGuard portal. It includes settings for connecting to an LDAP server, filtering users, and mapping LDAP fields to portal user attributes.

```yaml
# ... (basic configuration)

auth:
  ldap:
    # a sample LDAP provider with user sync enabled
    - provider_name: ldap
      url: ldap://srv-ad1.company.local:389
      bind_user: ldap_wireguard@company.local
      bind_pass: super-s3cr3t-ldap
      base_dn: DC=COMPANY,DC=LOCAL
      login_filter: "(&(objectClass=organizationalPerson)(mail={{login_identifier}})(!userAccountControl:1.2.840.113556.1.4.803:=2))"
      sync_interval: 15m
      sync_filter: "(&(objectClass=organizationalPerson)(!userAccountControl:1.2.840.113556.1.4.803:=2)(mail=*))"
      disable_missing: true
      field_map:
        user_identifier: sAMAccountName
        email: mail
        firstname: givenName
        lastname: sn
        phone: telephoneNumber
        department: department
        memberof: memberOf
      admin_group: CN=WireGuardAdmins,OU=Some-OU,DC=COMPANY,DC=LOCAL
      registration_enabled: true
      # Restrict interface access based on LDAP filters
      interface_filter:
        wg0: "(memberOf=CN=VPNUsers,OU=Groups,DC=COMPANY,DC=LOCAL)"
      log_user_info: true

```

--------------------------------

### LDAP Interface-specific Provisioning Filters

Source: https://wgportal.org/latest/documentation/usage/authentication

Restrict users from provisioning peers for specific WireGuard interfaces using `interface_filter`. This map defines LDAP filters for each interface.

```yaml
auth:
  ldap:
    - provider_name: "ldap1"
      # ... other settings
      interface_filter:
        wg0: "(memberOf=CN=VPNUsers,OU=Groups,DC=COMPANY,DC=LOCAL)"
        wg1: "(department=IT)"
```

--------------------------------

### Webhook Configuration with Secret

Source: https://wgportal.org/latest/documentation/usage/webhooks

Secure your webhooks by including a shared secret. This allows your service to verify the authenticity of incoming requests.

```yaml
webhook:
  url: https://your-service.example.com/webhook
  secret: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="

```

--------------------------------

### Reload systemd Daemon

Source: https://wgportal.org/latest/documentation/getting-started/binaries

Reload the systemd daemon to apply changes after creating or modifying a service unit file.

```bash
sudo systemctl daemon-reload

```

--------------------------------

### Peer Connect Event Payload

Source: https://wgportal.org/latest/documentation/usage/webhooks

This JSON payload represents a webhook event triggered when a peer successfully connects to the VPN. It includes details about the event, the entity involved, and specific metrics related to the connection.

```json
{
  "event": "connect",
  "entity": "peer_metric",
  "identifier": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
  "payload": {
    "Status": {
      "UpdatedAt": "2025-06-27T22:20:08.734900034+02:00",
      "IsConnected": true,
      "IsPingable": false,
      "BytesReceived": 212,
      "BytesTransmitted": 2884,
      "Endpoint": "10.55.66.77:58756",
      "LastHandshake": "2025-06-27T22:19:46.580842776+02:00",
      "LastSessionStart": "2025-06-27T22:19:46.580842776+02:00"
    },
    "Peer": {
      "CreatedBy": "admin@wgportal.local",
      "UpdatedBy": "admin@wgportal.local",
      "CreatedAt": "2025-06-26T21:43:49.251839574+02:00",
      "UpdatedAt": "2025-06-27T22:18:39.67763985+02:00",
      "Endpoint": "10.55.66.1:51820",
      "EndpointPublicKey": "eiVibpi3C2PUPcx2kwA5s09OgHx7AEaKMd33k0LQ5mM=",
      "AllowedIPsStr": "10.11.12.0/24,fdfd:d3ad:c0de:1234::/64",
      "ExtraAllowedIPsStr": "",
      "PresharedKey": "p9DDeLUSLOdQcjS8ZsBAiqUzwDIUvTyzavRZFuzhvyE=",
      "PersistentKeepalive": 16,
      "DisplayName": "Peer Fb5TaziA",
      "Identifier": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
      "UserIdentifier": "admin@wgportal.local",
      "InterfaceIdentifier": "wgTesting",
      "AutomaticallyCreated": false,
      "PrivateKey": "QBFNBe+7J49ergH0ze2TGUJMFrL/2bOL50Z2cgluYW8=",
      "PublicKey": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
      "InterfaceType": "client",
      "Addresses": [
        "10.11.12.10/32",
        "fdfd:d3ad:c0de:1234::a/128"
      ],
      "CheckAliveAddress": "",
      "DnsStr": "",
      "DnsSearchStr": "",
      "Mtu": 1420
    }
  }
}
```

--------------------------------

### LDAP Interface Filter Configuration

Source: https://wgportal.org/latest/documentation/configuration/overview

Map WireGuard interface identifiers to LDAP filters to control user access to specific interfaces. Only users matching the filter for an interface can provision peers for it.

```yaml
interface_filter:
  wg0: "(memberOf=CN=VPNUsers,OU=Groups,DC=COMPANY,DC=LOCAL)"
  wg1: "(description=special-access)"
```

--------------------------------

### OIDC Admin Mapping by Attribute Value

Source: https://wgportal.org/latest/documentation/usage/authentication

Map users to admin roles based on a specific attribute value in OIDC. The `admin_value_regex` is matched against the value of the `is_admin` attribute.

```yaml
auth:
  oidc:
    - provider_name: "oidc1"
      # ... other settings
      field_map:
        is_admin: "wg_admin_prop"
      admin_mapping:
        admin_value_regex: "^true$"
```

--------------------------------

### Docker Compose with Traefik for Reverse Proxy

Source: https://wgportal.org/latest/documentation/getting-started/reverse-proxy

This Docker Compose configuration sets up Traefik as a reverse proxy to handle HTTPS for the WireGuard Portal, including HTTP to HTTPS redirection and automatic certificate management.

```yaml
services:
  reverse-proxy:
    image: traefik:v3.3
    restart: unless-stopped
    command:
      #- '--log.level=DEBUG'
      - '--providers.docker.endpoint=unix:///var/run/docker.sock'
      - '--providers.docker.exposedbydefault=false'
      - '--entrypoints.web.address=:80'
      - '--entrypoints.websecure.address=:443'
      - '--entrypoints.websecure.http3'
      - '--certificatesresolvers.letsencryptresolver.acme.httpchallenge=true'
      - '--certificatesresolvers.letsencryptresolver.acme.httpchallenge.entrypoint=web'
      - '--certificatesresolvers.letsencryptresolver.acme.email=your.email@domain.com'
      - '--certificatesresolvers.letsencryptresolver.acme.storage=/letsencrypt/acme.json'
      #- '--certificatesresolvers.letsencryptresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory'  # just for testing
    ports:
      - 80:80 # for HTTP
      - 443:443/tcp  # for HTTPS
      - 443:443/udp  # for HTTP/3
    volumes:
      - acme-certs:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      - 'traefik.enable=true'
      # HTTP Catchall for redirecting HTTP -> HTTPS
      - 'traefik.http.routers.dashboard-catchall.rule=Host(`wg.domain.com`) && PathPrefix(`/`)
      - 'traefik.http.routers.dashboard-catchall.entrypoints=web'
      - 'traefik.http.routers.dashboard-catchall.middlewares=redirect-to-https'
      - 'traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https'

  wg-portal:
    image: wgportal/wg-portal:v2
    container_name: wg-portal
    restart: unless-stopped
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    cap_add:
      - NET_ADMIN
    ports:
      # host port : container port
      # WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface)
      - "51820:51820/udp"
      # Web UI port (only available on localhost, Traefik will handle the HTTPS)
      - "127.0.0.1:8888:8888/tcp"
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    volumes:
      # host path : container path
      - ./wg/data:/app/data
      - ./wg/config:/app/config
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.wgportal.rule=Host(`wg.domain.com`)
      - 'traefik.http.routers.wgportal.entrypoints=websecure'
      - 'traefik.http.routers.wgportal.tls.certresolver=letsencryptresolver'
      - 'traefik.http.routers.wgportal.service=wgportal'
      - 'traefik.http.services.wgportal.loadbalancer.server.port=8888'

volumes:
  acme-certs:

```
Tokens:
Raw