2025-05-04 11:00:12 +02:00
# WireGuard Portal v2
2020-11-10 22:23:05 +01:00
2025-01-23 08:06:55 +01:00
[](https://github.com/h44z/wg-portal/actions/workflows/docker-publish.yml)
2020-11-16 23:13:15 +01:00
[](https://opensource.org/licenses/MIT)
2025-01-23 08:06:55 +01:00
2021-02-26 23:13:11 +01:00
[](https://goreportcard.com/report/github.com/h44z/wg-portal)
2020-11-16 23:13:15 +01:00
2023-10-26 12:42:18 +02:00
[](https://hub.docker.com/r/wgportal/wg-portal/)
2020-11-16 23:13:15 +01:00
2025-01-23 08:06:55 +01:00
## Introduction
<!-- Text from this line # is included in docs/documentation/overview.md -->
**WireGuard Portal** is a simple, web-based configuration portal for [WireGuard ](https://wireguard.com ) server management.
2022-03-15 22:46:00 +01:00
The portal uses the WireGuard [wgctrl ](https://github.com/WireGuard/wgctrl-go ) library to manage existing VPN
2025-01-23 08:06:55 +01:00
interfaces. This allows for the seamless activation or deactivation of new users without disturbing existing VPN
2020-11-16 23:13:15 +01:00
connections.
2025-05-04 11:00:12 +02:00
The configuration portal supports using a database (SQLite, MySQL, MsSQL, or Postgres), OAuth or LDAP
2025-01-23 08:06:55 +01:00
(Active Directory or OpenLDAP) as a user source for authentication and profile data.
2020-11-16 23:13:15 +01:00
## Features
2025-01-23 08:06:55 +01:00
* Self-hosted - the whole application is a single binary
2025-10-04 14:17:29 +02:00
* Responsive multi-language web UI with dark-mode written in Vue.js
2025-01-23 08:06:55 +01:00
* Automatically selects IP from the network pool assigned to the client
* QR-Code for convenient mobile client configuration
* Sends email to the client with QR-code and client config
* Enable / Disable clients seamlessly
* Generation of wg-quick configuration file (`wgX.conf` ) if required
2025-05-16 14:58:05 +02:00
* User authentication (database, OAuth, or LDAP), Passkey support
2025-01-23 08:06:55 +01:00
* IPv6 ready
* Docker ready
* Can be used with existing WireGuard setups
* Support for multiple WireGuard interfaces
Add Pfsense backend (ALPHA) (#585)
* Add pfSense backend domain types and configuration
This adds the necessary domain types and configuration structures
for the pfSense backend support. Includes PfsenseInterfaceExtras and
PfsensePeerExtras structs, and the BackendPfsense configuration
with API URL, key, and timeout settings.
* Add low-level pfSense REST API client
Implements the HTTP client for interacting with the pfSense REST API.
Handles authentication via X-API-Key header, request/response parsing,
and error handling. Uses the pfSense REST API v2 endpoints as documented
at https://pfrest.org/.
* Implement pfSense WireGuard controller
This implements the InterfaceController interface for pfSense firewalls.
Handles WireGuard tunnel and peer management through the pfSense REST API.
Includes proper filtering of peers by interface (since API filtering doesn't
work) and parsing of the allowedips array structure with address/mask fields.
* Register pfSense controllers and update configuration
Registers the pfSense backend controllers in the controller manager
and adds example configuration to config.yml.sample. Also updates
README to mention pfSense backend support.
* Fix peer filtering and allowedips parsing for pfSense backend
The pfSense REST API doesn't support filtering peers by interface
via query parameters, so all peers are returned regardless of the
filter. This caused peers from all interfaces to be randomly assigned
to a single interface in wg-portal.
Additionally, the API returns allowedips as an array of objects with
"address" and "mask" fields instead of a comma-separated string,
which caused parsing failures.
Changes:
- Remove API filter from GetPeers() since it doesn't work
- Add client-side filtering by checking the "tun" field in peer responses
- Update convertWireGuardPeer() to parse allowedips array structure
- Add parseAddressArray() helper for parsing address objects
- Attempt to fetch interface addresses from /tunnel/{id}/address endpoint
(endpoint may not be available in all pfSense versions)
- Add debug logging for peer filtering and address loading operations
Note: Interface addresses may still be empty if the address endpoint
is not available. Public Endpoint and Default DNS Servers are typically
configured manually in wg-portal as the pfSense API doesn't provide
this information.
* Extract endpoint, DNS, and peer names from pfSense peer data
The pfSense API provides endpoint, port, and description (descr) fields
in peer responses that can be used to populate interface defaults and
peer display names.
Changes:
- Extract endpoint and port from peers and combine them properly
- Fix peer name/description extraction to check "descr" field first
(pfSense API uses "descr" instead of "description" or "comment")
- Add extractPfsenseDefaultsFromPeers() helper to extract common
endpoint and DNS from peers during interface import
- Set PeerDefEndpoint and PeerDefDnsStr from peer data for pfSense
backends during interface import
- Use most common endpoint/DNS values when multiple peers are present
* Fix interface display name to use descr field from pfSense API
The pfSense API uses "descr" field for tunnel descriptions, not
"description" or "comment". Updated convertWireGuardInterface()
to check "descr" first so that tunnel descriptions (e.g., "HQ VPN")
are displayed in the UI instead of just the tunnel name (e.g., "tun_wg0").
* Remove calls to non-working tunnel and peer detail endpoints
The pfSense REST API endpoints /api/v2/vpn/wireguard/tunnel/{id}
and /api/v2/vpn/wireguard/tunnel/{id}/address don't work and were
causing log spam. Removed these calls and use only the data from
the tunnel/peer list responses.
Also removed the peer detail endpoint call that was added for
statistics collection, as it likely doesn't work either.
* Fix unused variable compilation error
Removed unused deviceId variable that was causing build failure.
* Optimize tunnel address fetching to use /tunnel?id endpoint
Instead of using the separate /tunnel/address endpoint, now query
the specific tunnel endpoint /tunnel?id={id} which includes the
addresses array in the response. This avoids unnecessary API calls
and simplifies the code.
- GetInterface() now queries /tunnel?id={id} after getting tunnel ID
- loadInterfaceData() queries /tunnel?id={id} as fallback if addresses missing
- extractAddresses() properly parses addresses array from tunnel response
- Removed /tunnel/address endpoint calls
Signed-off-by: rwjack <jack@foss.family>
* Fix URL encoding issue in tunnel endpoint queries
Use Filters in PfsenseRequestOptions instead of passing query strings
directly in the path. This prevents the ? character from being encoded
as %3F, which was causing 404 errors.
- GetInterface() now uses Filters map for id parameter
- loadInterfaceData() now uses Filters map for id parameter
Signed-off-by: rwjack <jack@foss.family>
* update backend docs for pfsense
---------
Signed-off-by: rwjack <jack@foss.family>
2025-12-09 22:33:12 +01:00
* Supports multiple WireGuard backends (wgctrl, MikroTik, or pfSense)
2025-01-23 08:06:55 +01:00
* Peer Expiry Feature
* Handles route and DNS settings like wg-quick does
2025-02-27 22:32:11 +01:00
* Exposes Prometheus metrics for monitoring and alerting
2025-01-23 08:06:55 +01:00
* REST API for management and client deployment
2025-05-04 11:00:12 +02:00
* Webhook for custom actions on peer, interface, or user updates
2025-01-23 08:06:55 +01:00
<!-- Text to this line # is included in docs/documentation/overview.md -->
## Documentation
For the complete documentation visit [wgportal.org ](https://wgportal.org ).
2022-11-11 17:10:41 +01:00
2020-11-16 23:13:15 +01:00
## What is out of scope
2023-08-04 13:34:18 +02:00
2025-01-23 08:06:55 +01:00
* Automatic generation or application of any `iptables` or `nftables` rules.
* Support for operating systems other than linux.
* Automatic import of private keys of an existing WireGuard setup.
2022-03-15 22:46:00 +01:00
2020-11-16 23:13:15 +01:00
## Application stack
2025-01-23 08:06:55 +01:00
* [wgctrl-go ](https://github.com/WireGuard/wgctrl-go ) and [netlink ](https://github.com/vishvananda/netlink ) for interface handling
* [Bootstrap ](https://getbootstrap.com/ ), for the HTML templates
2025-02-27 22:32:11 +01:00
* [Vue.js ](https://vuejs.org/ ), for the frontend
2020-11-16 23:13:15 +01:00
## License
2025-01-23 08:06:55 +01:00
* MIT License. [MIT ](LICENSE.txt ) or < https: // opensource . org / licenses / MIT >
2025-05-04 11:00:12 +02:00
2025-10-04 14:17:29 +02:00
## Contributors and Sponsors
Thanks so much for all your contributions! They’
< a href = "https://github.com/h44z/wg-portal/graphs/contributors" >
< img src = "https://contrib.rocks/image?repo=h44z/wg-portal" / >
< / a >
Want to support the project? You can buy me a coffee or join as a contributor - every bit of support helps!
[Become a sponsor! ](https://github.com/sponsors/h44z )
2025-05-04 11:00:12 +02:00
> [!IMPORTANT]
> Since the project was accepted by the Docker-Sponsored Open Source Program, the Docker image location has moved to [wgportal/wg-portal](https://hub.docker.com/r/wgportal/wg-portal).
> Please update the Docker image from **h44z/wg-portal** to **wgportal/wg-portal**.
