From 0037938f9e19df8382c2f2aa4f162730818ea8de Mon Sep 17 00:00:00 2001 From: Christoph Haas Date: Sun, 10 Aug 2025 14:12:12 +0200 Subject: [PATCH] update docs --- README.md | 1 + docs/documentation/configuration/overview.md | 63 ++++++++++++++++++++ docs/documentation/usage/backends.md | 57 ++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 122 insertions(+) create mode 100644 docs/documentation/usage/backends.md diff --git a/README.md b/README.md index 018b748..035c69f 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ The configuration portal supports using a database (SQLite, MySQL, MsSQL, or Pos * Docker ready * Can be used with existing WireGuard setups * Support for multiple WireGuard interfaces +* Supports multiple WireGuard backends (wgctrl or MikroTik [BETA]) * Peer Expiry Feature * Handles route and DNS settings like wg-quick does * Exposes Prometheus metrics for monitoring and alerting diff --git a/docs/documentation/configuration/overview.md b/docs/documentation/configuration/overview.md index dd20d79..1268582 100644 --- a/docs/documentation/configuration/overview.md +++ b/docs/documentation/configuration/overview.md @@ -24,6 +24,9 @@ core: self_provisioning_allowed: false import_existing: true restore_state: true + +backend: + default: local advanced: log_level: info @@ -102,6 +105,7 @@ webhook: Below you will find sections like [`core`](#core), +[`backend`](#backend), [`advanced`](#advanced), [`database`](#database), [`statistics`](#statistics), @@ -165,6 +169,65 @@ More advanced options are found in the subsequent `Advanced` section. --- +## Backend + +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. + +### `default` +- **Default:** `local` +- **Description:** The default backend to use for managing WireGuard interfaces. + Valid options are: `local`, or other backend id's configured in the `mikrotik` section. + +### Mikrotik + +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`: + +#### `id` +- **Default:** *(empty)* +- **Description:** A unique identifier for this backend. + This value can be referenced by `backend.default` to use this backend as default. + The identifier must be unique across all backends and must not use the reserved keyword `local`. + +#### `display_name` +- **Default:** *(empty)* +- **Description:** A human-friendly display name for this backend. If omitted, the `id` will be used as the display name. + +#### `api_url` +- **Default:** *(empty)* +- **Description:** Base URL of the MikroTik REST API, including scheme and path, e.g., `https://10.10.10.10:8729/rest`. + +#### `api_user` +- **Default:** *(empty)* +- **Description:** Username for authenticating against the MikroTik API. + Ensure that the user has sufficient permissions to manage WireGuard interfaces and peers. + +#### `api_password` +- **Default:** *(empty)* +- **Description:** Password for the specified API user. + +#### `api_verify_tls` +- **Default:** `false` +- **Description:** Whether to verify the TLS certificate of the MikroTik API endpoint. Set to `false` to allow self-signed certificates (not recommended for production). + +#### `api_timeout` +- **Default:** `30s` +- **Description:** Timeout for API requests to the MikroTik device. Uses Go duration format (e.g., `10s`, `1m`). If omitted, a default of 30 seconds is used. + +#### `concurrency` +- **Default:** `5` +- **Description:** Maximum number of concurrent API requests the backend will issue when enumerating interfaces and their details. If `0` or negative, a sane default of `5` is used. + +#### `debug` +- **Default:** `false` +- **Description:** Enable verbose debug logging for the MikroTik backend. + +For more details on configuring the MikroTik backend, see the [Backends](../usage/backends.md) documentation. + +--- + ## Advanced Additional or more specialized configuration options for logging and interface creation details. diff --git a/docs/documentation/usage/backends.md b/docs/documentation/usage/backends.md new file mode 100644 index 0000000..e891d95 --- /dev/null +++ b/docs/documentation/usage/backends.md @@ -0,0 +1,57 @@ +# Backends + +WireGuard Portal can manage WireGuard interfaces and peers on different backends. +Each backend represents a system where interfaces actually live. +You can register multiple backends and choose which one to use per interface. +A global default backend determines where newly created interfaces go (unless you explicitly choose another in the UI). + +**Supported backends:** +- **Local** (default): Manages interfaces on the host running WireGuard Portal (Linux WireGuard via wgctrl). Use this when the portal should directly configure wg devices on the same server. +- **MikroTik** RouterOS (_beta_): Manages interfaces and peers on MikroTik devices via the RouterOS REST API. Use this to control WG interfaces on RouterOS v7+. + +How backend selection works: +- The default backend is configured at `backend.default` (_local_ or the id of a defined MikroTik backend). + New interfaces created in the UI will use this backend by default. +- Each interface stores its backend. You can select a different backend when creating a new interface. + +## Configuring MikroTik backends (RouterOS v7+) + +> :warning: 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](https://help.mikrotik.com/docs/spaces/ROS/pages/47579162/REST+API) under a base URL ending with /rest. +You can register one or more MikroTik devices as backends for a single WireGuard Portal instance. + +### Prerequisites on MikroTik: +- RouterOS v7 with WireGuard support. +- REST API enabled and reachable over HTTP(S). A typical base URL is https://:8729/rest or https:///rest depending on your service setup. +- A dedicated RouterOS user with the following group permissions: + - **api** (for logging in via REST API) + - **rest-api** (for logging in via REST API) + - **read** (to read interface and peer data) + - **write** (to create/update interfaces and peers) + - **test** (to perform ping checks) + - **sensitive** (to read private keys) +- TLS certificate on the device is recommended. If you use a self-signed certificate during testing, set `api_verify_tls`: _false_ in wg-portal (not recommended for production). + +Example WireGuard Portal configuration (config/config.yaml): + +```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 +``` + +### Known limitations: +- The MikroTik backend is still in beta. Some features may not work as expected. +- Not all WireGuard Portal features are supported yet (e.g., no support for interface hooks) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f7b5169..7184e3c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,7 @@ nav: - Examples: documentation/configuration/examples.md - Usage: - General: documentation/usage/general.md + - Backends: documentation/usage/backends.md - LDAP: documentation/usage/ldap.md - Security: documentation/usage/security.md - Webhooks: documentation/usage/webhooks.md