diff --git a/master/documentation/usage/mail-templates/index.html b/master/documentation/usage/mail-templates/index.html index b80287cf..5873d6b1 100644 --- a/master/documentation/usage/mail-templates/index.html +++ b/master/documentation/usage/mail-templates/index.html @@ -5,4 +5,4 @@ # will be written there so you can modify them. # Leave empty to use embedded templates only. templates_path: "/opt/wg-portal/mail-templates" -

Template files and names

The system expects the following template names. Place files with these names in your templates_path to override the defaults. You do not need to override all templates, only the ones you want to customize should be present.

Both text and HTML templates are standard Go templates and receive the following data fields, depending on the email type:

Tip: You can inspect the embedded templates in the repository under internal/app/mail/tpl_files/ for reference. When the directory at templates_path is empty, these files are copied to your folder so you can edit them in place.

\ No newline at end of file +

Template files and names

The system expects the following template names. Place files with these names in your templates_path to override the defaults. You do not need to override all templates, only the ones you want to customize should be present.

Both text and HTML templates are standard Go templates and receive the following data fields, depending on the email type:

Tip: You can inspect the embedded templates in the repository under internal/app/mail/tpl_files/ for reference. When the directory at templates_path is empty, these files are copied to your folder so you can edit them in place.

\ No newline at end of file diff --git a/master/search/search_index.json b/master/search/search_index.json index b83a9bc6..d03d211b 100644 --- a/master/search/search_index.json +++ b/master/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"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":""},{"location":"documentation/configuration/examples/","title":"Examples","text":"

Below 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_on_login: true\n  self_provisioning_allowed: true\n\nbackend:\n  # default backend decides where new interfaces are created\n  default: mikrotik\n\n  # A prefix for resolvconf. Usually it is \"tun.\". If you are using systemd, the prefix should be empty.\n  local_resolvconf_prefix: \"tun.\"\n\n  mikrotik:\n    - id: mikrotik                   # unique id, not \"local\"\n      display_name: RouterOS RB5009  # optional nice name\n      api_url: https://10.10.10.10/rest\n      api_user: wgportal\n      api_password: a-super-secret-password\n      api_verify_tls: false        # set to false only if using self-signed during testing\n      api_timeout: 30s             # maximum request duration\n      concurrency: 5               # limit parallel REST calls to device\n      debug: false                 # verbose logging for this backend\n      ignored_interfaces:          # ignore these interfaces during import\n      - wgTest1\n      - wgTest2\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    - provider_name: ldap\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      # Restrict interface access based on LDAP filters\n      interface_filter:\n        wg0: \"(memberOf=CN=VPNUsers,OU=Groups,DC=COMPANY,DC=LOCAL)\"\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    - 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    - 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    - 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      allowed_user_groups:\n        - the-admin-group\n        - vpn-users\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    - 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    - 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      allowed_user_groups:\n        - admin-group-name\n        - vpn-users\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

For more information, check out the usage documentation (e.g. General Configuration or Backends Configuration).

"},{"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 configuration 
core:\n  admin_user: admin@wgportal.local\n  admin_password: wgportal-default\n  admin_api_token: \"\"\n  disable_admin_user: false\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\nbackend:\n  default: local\n  rekey_timeout_interval: 125s\n  local_resolvconf_prefix: tun.\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  startup_timeout: 5m\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  allow_peer_email: false\n  templates_path: \"\"\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  base_path: \"\"\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  frontend_filepath: \"\"\n\nwebhook:\n  url: \"\"\n  authentication: \"\"\n  timeout: 10s\n

Below you will find sections like core, backend, 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.

"},{"location":"documentation/configuration/overview/#core","title":"Core","text":"

These are the primary configuration options that control fundamental WireGuard Portal behavior. More advanced options are found in the subsequent Advanced section.

"},{"location":"documentation/configuration/overview/#admin_user","title":"admin_user","text":""},{"location":"documentation/configuration/overview/#admin_password","title":"admin_password","text":""},{"location":"documentation/configuration/overview/#disable_admin_user","title":"disable_admin_user","text":""},{"location":"documentation/configuration/overview/#admin_api_token","title":"admin_api_token","text":""},{"location":"documentation/configuration/overview/#editable_keys","title":"editable_keys","text":""},{"location":"documentation/configuration/overview/#create_default_peer-deprecated","title":"create_default_peer (deprecated)","text":""},{"location":"documentation/configuration/overview/#create_default_peer_on_creation-deprecated","title":"create_default_peer_on_creation (deprecated)","text":""},{"location":"documentation/configuration/overview/#create_default_peer_on_login","title":"create_default_peer_on_login","text":""},{"location":"documentation/configuration/overview/#create_default_peer_on_user_creation","title":"create_default_peer_on_user_creation","text":""},{"location":"documentation/configuration/overview/#create_default_peer_on_interface_creation","title":"create_default_peer_on_interface_creation","text":""},{"location":"documentation/configuration/overview/#re_enable_peer_after_user_enable","title":"re_enable_peer_after_user_enable","text":""},{"location":"documentation/configuration/overview/#delete_peer_after_user_deleted","title":"delete_peer_after_user_deleted","text":""},{"location":"documentation/configuration/overview/#self_provisioning_allowed","title":"self_provisioning_allowed","text":""},{"location":"documentation/configuration/overview/#import_existing","title":"import_existing","text":""},{"location":"documentation/configuration/overview/#restore_state","title":"restore_state","text":""},{"location":"documentation/configuration/overview/#backend","title":"Backend","text":"

Configuration options for the WireGuard backend, which manages the WireGuard interfaces and peers. The current MikroTik backend is in BETA and may not support all features.

"},{"location":"documentation/configuration/overview/#default","title":"default","text":""},{"location":"documentation/configuration/overview/#rekey_timeout_interval","title":"rekey_timeout_interval","text":""},{"location":"documentation/configuration/overview/#local_resolvconf_prefix","title":"local_resolvconf_prefix","text":""},{"location":"documentation/configuration/overview/#ignored_local_interfaces","title":"ignored_local_interfaces","text":""},{"location":"documentation/configuration/overview/#mikrotik","title":"Mikrotik","text":"

The mikrotik array contains a list of MikroTik backend definitions. Each entry describes how to connect to a MikroTik RouterOS instance that hosts WireGuard interfaces.

Below are the properties for each entry inside backend.mikrotik:

"},{"location":"documentation/configuration/overview/#id","title":"id","text":""},{"location":"documentation/configuration/overview/#display_name","title":"display_name","text":""},{"location":"documentation/configuration/overview/#api_url","title":"api_url","text":""},{"location":"documentation/configuration/overview/#api_user","title":"api_user","text":""},{"location":"documentation/configuration/overview/#api_password","title":"api_password","text":""},{"location":"documentation/configuration/overview/#api_verify_tls","title":"api_verify_tls","text":""},{"location":"documentation/configuration/overview/#api_timeout","title":"api_timeout","text":""},{"location":"documentation/configuration/overview/#concurrency","title":"concurrency","text":""},{"location":"documentation/configuration/overview/#ignored_interfaces","title":"ignored_interfaces","text":""},{"location":"documentation/configuration/overview/#debug","title":"debug","text":"

For more details on configuring the MikroTik backend, see the Backends documentation.

"},{"location":"documentation/configuration/overview/#advanced","title":"Advanced","text":"

Additional or more specialized configuration options for logging and interface creation details.

"},{"location":"documentation/configuration/overview/#log_level","title":"log_level","text":""},{"location":"documentation/configuration/overview/#log_pretty","title":"log_pretty","text":""},{"location":"documentation/configuration/overview/#log_json","title":"log_json","text":""},{"location":"documentation/configuration/overview/#start_listen_port","title":"start_listen_port","text":""},{"location":"documentation/configuration/overview/#start_cidr_v4","title":"start_cidr_v4","text":""},{"location":"documentation/configuration/overview/#start_cidr_v6","title":"start_cidr_v6","text":""},{"location":"documentation/configuration/overview/#use_ip_v6","title":"use_ip_v6","text":""},{"location":"documentation/configuration/overview/#config_storage_path","title":"config_storage_path","text":""},{"location":"documentation/configuration/overview/#expiry_check_interval","title":"expiry_check_interval","text":""},{"location":"documentation/configuration/overview/#rule_prio_offset","title":"rule_prio_offset","text":""},{"location":"documentation/configuration/overview/#route_table_offset","title":"route_table_offset","text":""},{"location":"documentation/configuration/overview/#api_admin_only","title":"api_admin_only","text":""},{"location":"documentation/configuration/overview/#limit_additional_user_peers","title":"limit_additional_user_peers","text":""},{"location":"documentation/configuration/overview/#startup_timeout","title":"startup_timeout","text":""},{"location":"documentation/configuration/overview/#database","title":"Database","text":"

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.

"},{"location":"documentation/configuration/overview/#debug_1","title":"debug","text":""},{"location":"documentation/configuration/overview/#slow_query_threshold","title":"slow_query_threshold","text":""},{"location":"documentation/configuration/overview/#type","title":"type","text":""},{"location":"documentation/configuration/overview/#dsn","title":"dsn","text":""},{"location":"documentation/configuration/overview/#encryption_passphrase","title":"encryption_passphrase","text":""},{"location":"documentation/configuration/overview/#statistics","title":"Statistics","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":""},{"location":"documentation/configuration/overview/#ping_check_workers","title":"ping_check_workers","text":""},{"location":"documentation/configuration/overview/#ping_unprivileged","title":"ping_unprivileged","text":""},{"location":"documentation/configuration/overview/#ping_check_interval","title":"ping_check_interval","text":""},{"location":"documentation/configuration/overview/#data_collection_interval","title":"data_collection_interval","text":""},{"location":"documentation/configuration/overview/#collect_interface_data","title":"collect_interface_data","text":""},{"location":"documentation/configuration/overview/#collect_peer_data","title":"collect_peer_data","text":""},{"location":"documentation/configuration/overview/#collect_audit_data","title":"collect_audit_data","text":""},{"location":"documentation/configuration/overview/#listening_address","title":"listening_address","text":""},{"location":"documentation/configuration/overview/#mail","title":"Mail","text":"

Options for configuring email notifications or sending peer configurations via email. By default, emails will only be sent to peers that have a valid user record linked. To send emails to all peers that have a valid email-address as user-identifier, set allow_peer_email to true.

"},{"location":"documentation/configuration/overview/#host","title":"host","text":""},{"location":"documentation/configuration/overview/#port","title":"port","text":""},{"location":"documentation/configuration/overview/#encryption","title":"encryption","text":""},{"location":"documentation/configuration/overview/#cert_validation","title":"cert_validation","text":""},{"location":"documentation/configuration/overview/#username","title":"username","text":""},{"location":"documentation/configuration/overview/#password","title":"password","text":""},{"location":"documentation/configuration/overview/#auth_type","title":"auth_type","text":""},{"location":"documentation/configuration/overview/#from","title":"from","text":""},{"location":"documentation/configuration/overview/#link_only","title":"link_only","text":""},{"location":"documentation/configuration/overview/#allow_peer_email","title":"allow_peer_email","text":""},{"location":"documentation/configuration/overview/#templates_path","title":"templates_path","text":""},{"location":"documentation/configuration/overview/#auth","title":"Auth","text":"

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":""},{"location":"documentation/configuration/overview/#hide_login_form","title":"hide_login_form","text":""},{"location":"documentation/configuration/overview/#oidc","title":"OIDC","text":"

The oidc array contains a list of OpenID Connect providers. Below are the properties for each OIDC provider entry inside auth.oidc:

"},{"location":"documentation/configuration/overview/#provider_name","title":"provider_name","text":""},{"location":"documentation/configuration/overview/#display_name_1","title":"display_name","text":""},{"location":"documentation/configuration/overview/#base_url","title":"base_url","text":""},{"location":"documentation/configuration/overview/#client_id","title":"client_id","text":""},{"location":"documentation/configuration/overview/#client_secret","title":"client_secret","text":""},{"location":"documentation/configuration/overview/#extra_scopes","title":"extra_scopes","text":""},{"location":"documentation/configuration/overview/#allowed_domains","title":"allowed_domains","text":""},{"location":"documentation/configuration/overview/#allowed_user_groups","title":"allowed_user_groups","text":""},{"location":"documentation/configuration/overview/#field_map","title":"field_map","text":""},{"location":"documentation/configuration/overview/#admin_mapping","title":"admin_mapping","text":""},{"location":"documentation/configuration/overview/#registration_enabled","title":"registration_enabled","text":""},{"location":"documentation/configuration/overview/#log_user_info","title":"log_user_info","text":""},{"location":"documentation/configuration/overview/#log_sensitive_info","title":"log_sensitive_info","text":""},{"location":"documentation/configuration/overview/#use_pkce","title":"use_pkce","text":""},{"location":"documentation/configuration/overview/#pkce_method","title":"pkce_method","text":""},{"location":"documentation/configuration/overview/#logout_idp_session","title":"logout_idp_session","text":""},{"location":"documentation/configuration/overview/#oauth","title":"OAuth","text":"

The oauth array contains a list of plain OAuth2 providers. Below are the properties for each OAuth provider entry inside auth.oauth:

"},{"location":"documentation/configuration/overview/#provider_name_1","title":"provider_name","text":""},{"location":"documentation/configuration/overview/#display_name_2","title":"display_name","text":""},{"location":"documentation/configuration/overview/#client_id_1","title":"client_id","text":""},{"location":"documentation/configuration/overview/#client_secret_1","title":"client_secret","text":""},{"location":"documentation/configuration/overview/#auth_url","title":"auth_url","text":""},{"location":"documentation/configuration/overview/#token_url","title":"token_url","text":""},{"location":"documentation/configuration/overview/#user_info_url","title":"user_info_url","text":""},{"location":"documentation/configuration/overview/#scopes","title":"scopes","text":""},{"location":"documentation/configuration/overview/#allowed_domains_1","title":"allowed_domains","text":""},{"location":"documentation/configuration/overview/#allowed_user_groups_1","title":"allowed_user_groups","text":""},{"location":"documentation/configuration/overview/#field_map_1","title":"field_map","text":""},{"location":"documentation/configuration/overview/#admin_mapping_1","title":"admin_mapping","text":""},{"location":"documentation/configuration/overview/#registration_enabled_1","title":"registration_enabled","text":""},{"location":"documentation/configuration/overview/#log_user_info_1","title":"log_user_info","text":""},{"location":"documentation/configuration/overview/#log_sensitive_info_1","title":"log_sensitive_info","text":""},{"location":"documentation/configuration/overview/#use_pkce_1","title":"use_pkce","text":""},{"location":"documentation/configuration/overview/#pkce_method_1","title":"pkce_method","text":""},{"location":"documentation/configuration/overview/#ldap","title":"LDAP","text":"

The ldap array contains a list of LDAP authentication providers. Below are the properties for each LDAP provider entry inside auth.ldap:

"},{"location":"documentation/configuration/overview/#provider_name_2","title":"provider_name","text":""},{"location":"documentation/configuration/overview/#url","title":"url","text":""},{"location":"documentation/configuration/overview/#start_tls","title":"start_tls","text":""},{"location":"documentation/configuration/overview/#cert_validation_1","title":"cert_validation","text":""},{"location":"documentation/configuration/overview/#tls_certificate_path","title":"tls_certificate_path","text":""},{"location":"documentation/configuration/overview/#tls_key_path","title":"tls_key_path","text":""},{"location":"documentation/configuration/overview/#base_dn","title":"base_dn","text":""},{"location":"documentation/configuration/overview/#bind_user","title":"bind_user","text":""},{"location":"documentation/configuration/overview/#bind_pass","title":"bind_pass","text":""},{"location":"documentation/configuration/overview/#field_map_2","title":"field_map","text":""},{"location":"documentation/configuration/overview/#login_filter","title":"login_filter","text":""},{"location":"documentation/configuration/overview/#interface_filter","title":"interface_filter","text":""},{"location":"documentation/configuration/overview/#admin_group","title":"admin_group","text":""},{"location":"documentation/configuration/overview/#sync_interval","title":"sync_interval","text":""},{"location":"documentation/configuration/overview/#sync_filter","title":"sync_filter","text":""},{"location":"documentation/configuration/overview/#sync_log_user_info","title":"sync_log_user_info","text":""},{"location":"documentation/configuration/overview/#disable_missing","title":"disable_missing","text":""},{"location":"documentation/configuration/overview/#auto_re_enable","title":"auto_re_enable","text":""},{"location":"documentation/configuration/overview/#registration_enabled_2","title":"registration_enabled","text":""},{"location":"documentation/configuration/overview/#log_user_info_2","title":"log_user_info","text":""},{"location":"documentation/configuration/overview/#webauthn-passkeys","title":"WebAuthn (Passkeys)","text":"

The webauthn section contains configuration options for WebAuthn authentication (passkeys).

"},{"location":"documentation/configuration/overview/#enabled","title":"enabled","text":""},{"location":"documentation/configuration/overview/#web","title":"Web","text":"

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.

"},{"location":"documentation/configuration/overview/#listening_address_1","title":"listening_address","text":""},{"location":"documentation/configuration/overview/#external_url","title":"external_url","text":""},{"location":"documentation/configuration/overview/#base_path","title":"base_path","text":""},{"location":"documentation/configuration/overview/#site_company_name","title":"site_company_name","text":""},{"location":"documentation/configuration/overview/#site_title","title":"site_title","text":""},{"location":"documentation/configuration/overview/#session_identifier","title":"session_identifier","text":""},{"location":"documentation/configuration/overview/#session_secret","title":"session_secret","text":""},{"location":"documentation/configuration/overview/#csrf_secret","title":"csrf_secret","text":""},{"location":"documentation/configuration/overview/#request_logging","title":"request_logging","text":""},{"location":"documentation/configuration/overview/#expose_host_info","title":"expose_host_info","text":""},{"location":"documentation/configuration/overview/#cert_file","title":"cert_file","text":""},{"location":"documentation/configuration/overview/#key_file","title":"key_file","text":""},{"location":"documentation/configuration/overview/#frontend_filepath","title":"frontend_filepath","text":""},{"location":"documentation/configuration/overview/#webhook","title":"Webhook","text":"

The webhook section allows you to configure a webhook that is called on certain events in WireGuard Portal. Further details can be found in the usage documentation.

"},{"location":"documentation/configuration/overview/#url_1","title":"url","text":""},{"location":"documentation/configuration/overview/#authentication","title":"authentication","text":""},{"location":"documentation/configuration/overview/#timeout","title":"timeout","text":""},{"location":"documentation/getting-started/binaries/","title":"Binaries","text":"

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:

"},{"location":"documentation/getting-started/binaries/#released-versions","title":"Released versions","text":"

To download a specific version, replace ${WG_PORTAL_VERSION} with the desired version (or set an environment variable). All official release versions can be found on the GitHub Releases Page.

With curl:

curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64 \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

The downloaded file will be named wg-portal and can be moved to a directory of your choice, see Install for more information.

"},{"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/binaries/#install","title":"Install","text":"

The following command can be used to install the downloaded binary (wg-portal) to /opt/wg-portal/wg-portal. It ensures that the binary is executable.

sudo mkdir -p /opt/wg-portal\nsudo install wg-portal /opt/wg-portal/\n

To handle tasks such as restarting the service or configuring automatic startup, it is recommended to use a process manager like systemd. Refer to Systemd Service Setup for instructions.

"},{"location":"documentation/getting-started/binaries/#systemd-integration","title":"Systemd Integration","text":"

Note: To run WireGuard Portal as systemd service, you need to download the binary for your architecture beforehand.

The following examples assume that you downloaded the binary to /opt/wg-portal/wg-portal. The configuration file is expected to be located at /opt/wg-portal/config.yml.

"},{"location":"documentation/getting-started/binaries/#limit-systemd-networkd-management-scope","title":"Limit Systemd-Networkd Management Scope","text":"

If you are using systemd-networkd to manage the rest of your network configuration, you will need to ensure it doesn't remove routing policy created by wg-portal when it restarts:

sudo mkdir --parents /etc/systemd/networkd.conf.d/\nsudo tee --append /etc/systemd/networkd.conf.d/foreign-routing.conf <<EOF\n[Network]\nManageForeignRoutingPolicyRules=no\nEOF\nsudo systemctl restart systemd-networkd.service\nsudo systemctl status systemd-networkd.service\n
"},{"location":"documentation/getting-started/binaries/#wireguard-portal-service-setup","title":"Wireguard Portal Service Setup","text":"

To run WireGuard Portal as a systemd service, you can create a service unit file. The easiest way to do this is by using systemctl edit:

sudo systemctl edit --force --full wg-portal.service\n

Paste the following content into the editor and adjust the variables to your needs:

[Unit]\nDescription=WireGuard Portal\nConditionPathExists=/opt/wg-portal/wg-portal\nAfter=network.target\n\n[Service]\nType=simple\nUser=root\nGroup=root\nAmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW\n\nRestart=on-failure\nRestartSec=10\n\nWorkingDirectory=/opt/wg-portal\nEnvironment=WG_PORTAL_CONFIG=/opt/wg-portal/config.yml\nExecStart=/opt/wg-portal/wg-portal\n\n[Install]\nWantedBy=multi-user.target\n

Alternatively, you can create or modify the file manually in /etc/systemd/system/wg-portal.service. For systemd to pick up the changes, you need to reload the daemon:

sudo systemctl daemon-reload\n

After creating the service file, you can enable and start the service:

sudo systemctl enable --now wg-portal.service\n

To check status and log output, use: sudo systemctl status wg-portal.service or sudo journalctl -u wg-portal.service.

"},{"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.

"},{"location":"documentation/getting-started/docker/#wireguard-interface-handling","title":"WireGuard Interface Handling","text":"

WireGuard Portal supports managing WireGuard interfaces through three distinct deployment methods, providing flexibility based on your system architecture and operational preferences:

If the host is running systemd-networkd, routes managed by WireGuard Portal may be removed whenever systemd-networkd restarts, as it will clean up routes it considers \"foreign\". To prevent this, add the following to your host's network configuration (e.g. /etc/systemd/networkd.conf or a drop-in file): 

[Network]\nManageForeignRoutingPolicyRules=no\nManageForeignRoutes=no\n
After editing, reload the configuration with sudo systemctl restart systemd-networkd. For more information refer to the systemd-networkd documentation.

"},{"location":"documentation/getting-started/docker/#image-versioning","title":"Image Versioning","text":"

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:

"},{"location":"documentation/getting-started/docker/#the-latest-tag","title":"The 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.

"},{"location":"documentation/getting-started/docker/#the-master-tag","title":"The 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:

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 replicas int 1 The replicas for the workload. 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.web.extraSelectorLabels object {} Extra labels to append to the selector labels. 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.wireguard.extraSelectorLabels object {} Extra labels to append to the selector labels. service.metrics.port int 8787 ingress.enabled bool false Specifies whether an ingress resource should be created ingress.className string \"\" Ingress class name ingress.pathType string \"ImplementationSpecific\" Ingress pathType value. Valid values are ImplementationSpecific, Exact or Prefix. 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

If you want to serve the web interface on a different base-path, you can also set the web.base_path option:

web:\n  external_url: https://wg.domain.com\n  base_path: /subpath\n

The WireGuard Portal will then be available at https://wg.domain.com/subpath.

"},{"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":""},{"location":"documentation/getting-started/sources/#build","title":"Build","text":"
# 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.

"},{"location":"documentation/monitoring/prometheus/#exposed-metrics","title":"Exposed Metrics","text":"Metric Type Description 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.

"},{"location":"documentation/rest-api/api-doc/","title":"REST API","text":""},{"location":"documentation/upgrade/v1/","title":"Upgrade","text":"

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/authentication/","title":"Authentication","text":"

WireGuard Portal supports multiple authentication mechanisms to manage user access. This includes

Users can have two roles which limit their permissions in WireGuard Portal:

In general, each user is identified by a unique identifier. If the same user identifier exists across multiple authentication sources, WireGuard Portal automatically merges those accounts into a single user record. When a user is associated with multiple authentication sources, their information in WireGuard Portal is updated based on the most recently logged-in source. For more details, see User Synchronization documentation.

"},{"location":"documentation/usage/authentication/#password-authentication","title":"Password Authentication","text":"

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.

"},{"location":"documentation/usage/authentication/#passkey-webauthn-authentication","title":"Passkey (WebAuthn) Authentication","text":"

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/authentication/#oauth2-and-oidc-authentication","title":"OAuth2 and OIDC Authentication","text":"

WireGuard Portal supports OAuth2 and OIDC authentication. You can use any OAuth2 or OIDC provider that supports the authorization code flow, such as Google, GitHub, or Keycloak.

For OAuth2 or OIDC to work, you need to configure the external_url property in the web section of the configuration file. If you are planning to expose the portal to the internet, make sure that the external_url is configured to use HTTPS.

To add OIDC or OAuth2 authentication to WireGuard Portal, create a Client-ID and Client-Secret in your OAuth2 provider and configure a new authentication provider in the auth section of the configuration file. Make sure that each configured provider has a unique provider_name property set. Samples can be seen here.

When registering the OAuth2 or OIDC application with your provider, configure the callback/redirect URL as follows:

<external_url>/api/v0/auth/login/<provider_name>/callback\n

Replace <external_url> with the value configured in external_url and <provider_name> with the exact provider_name from the matching OAuth2 or OIDC provider configuration.

"},{"location":"documentation/usage/authentication/#limiting-login-to-specific-domains","title":"Limiting Login to Specific Domains","text":"

You can limit the login to specific domains by setting the allowed_domains property for OAuth2 or OIDC providers. This property is a comma-separated list of domains that are allowed to log in. The user's email address is checked against this list. For example, if you want to allow only users with an email address ending in outlook.com to log in, set the property as follows:

auth:\n  oidc:\n    - provider_name: \"oidc1\"\n      # ... other settings\n      allowed_domains:\n        - \"outlook.com\"\n
"},{"location":"documentation/usage/authentication/#limiting-login-to-specific-user-groups","title":"Limiting Login to Specific User Groups","text":"

You can limit the login to specific user groups by setting the allowed_user_groups property for OAuth2 or OIDC providers. If this property is not empty, the user's user_groups claim must contain at least one matching group.

To use this feature, ensure your group claim is mapped via field_map.user_groups.

auth:\n  oidc:\n    - provider_name: \"oidc1\"\n      # ... other settings\n      allowed_user_groups:\n        - \"wg-users\"\n        - \"wg-admins\"\n      field_map:\n        user_groups: \"groups\"\n

If allowed_user_groups is configured and the authenticated user has no matching group in user_groups, login is denied.

Minimal deny-by-group example:

auth:\n  oauth:\n    - provider_name: \"oauth1\"\n      # ... other settings\n      allowed_user_groups:\n        - \"vpn-users\"\n      field_map:\n        user_groups: \"groups\"\n
"},{"location":"documentation/usage/authentication/#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 OAuth2 or OIDC providers. If registration is enabled, new users will be created in the database when they log in for the first time.

"},{"location":"documentation/usage/authentication/#admin-mapping","title":"Admin Mapping","text":"

You can map users to admin roles based on their attributes in the OAuth2 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/authentication/#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.

"},{"location":"documentation/usage/authentication/#limiting-login-to-specific-users","title":"Limiting Login to Specific Users","text":"

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.

"},{"location":"documentation/usage/authentication/#limit-login-to-existing-users_1","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 LDAP providers. If registration is enabled, new users will be created in the database when they log in for the first time.

"},{"location":"documentation/usage/authentication/#admin-mapping_1","title":"Admin Mapping","text":"

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.

"},{"location":"documentation/usage/authentication/#interface-specific-provisioning-filters","title":"Interface-specific Provisioning Filters","text":"

You can restrict which users are allowed to provision peers for specific WireGuard interfaces by setting the interface_filter property. This property is a map where each key corresponds to a WireGuard interface identifier, and the value is an LDAP filter. A user will only be able to see and provision peers for an interface if they match the specified LDAP filter for that interface.

Example: 

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

This feature works by materializing the list of authorized users for each interface during the periodic LDAP synchronization. Even if a user bypasses the UI, the backend will enforce these restrictions at the service layer.

"},{"location":"documentation/usage/authentication/#user-synchronization","title":"User Synchronization","text":""},{"location":"documentation/usage/backends/","title":"Backends","text":"

WireGuard Portal can manage WireGuard interfaces and peers on different backends. Each backend represents a system where interfaces actually live. You can register multiple backends and choose which one to use per interface. A global default backend determines where newly created interfaces go (unless you explicitly choose another in the UI).

Supported backends: - Local (default): Manages interfaces on the host running WireGuard Portal (Linux WireGuard via wgctrl). Use this when the portal should directly configure wg devices on the same server. - MikroTik RouterOS (beta): Manages interfaces and peers on MikroTik devices via the RouterOS REST API. Use this to control WG interfaces on RouterOS v7+. - pfSense (alpha): Manages interfaces and peers on pfSense firewalls via the pfSense REST API.

How backend selection works: - The default backend is configured at backend.default (local or the id of a defined MikroTik backend). New interfaces created in the UI will use this backend by default. - Each interface stores its backend. You can select a different backend when creating a new interface.

"},{"location":"documentation/usage/backends/#configuring-mikrotik-backends-routeros-v7","title":"Configuring MikroTik backends (RouterOS v7+)","text":"

The MikroTik backend is currently marked beta. While basic functionality is implemented, some advanced features are not yet implemented or contain bugs. Please test carefully before using in production.

The MikroTik backend uses the REST API under a base URL ending with /rest. You can register one or more MikroTik devices as backends for a single WireGuard Portal instance.

"},{"location":"documentation/usage/backends/#prerequisites-on-mikrotik","title":"Prerequisites on MikroTik:","text":"