From 37f997316ffeec46bc7f530ad22b64685f9a498f Mon Sep 17 00:00:00 2001 From: Per-Arne Date: Mon, 13 Apr 2020 23:23:33 +0200 Subject: [PATCH] Improved documentation --- README.md | 82 ++++++++++++--------------- docs/guides/docker_configuration.md | 13 +++++ docs/guides/import_existing_server.md | 61 ++++++++++++++++++++ docs/guides/reverse_proxy.md | 2 + 4 files changed, 112 insertions(+), 46 deletions(-) create mode 100644 docs/guides/docker_configuration.md create mode 100644 docs/guides/import_existing_server.md create mode 100644 docs/guides/reverse_proxy.md diff --git a/README.md b/README.md index 368c293..ff09029 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,45 @@ # wg-manager -The wg-manager provides a easy-to-use graphical interface to setup and manage WireGuard server(s). -The following features is implemented: -* Create/Delete/Modify Server -* Create/Delete/Modify Users -* QRCode export -* Text export -* Start/Stop server -* User bandwidth usage statistics +The wg-manager provides an easy-to-use graphical web interface to import, setup, and manage WireGuard server(s). -The interface runs in docker and requires the host to have installed wireguard, either as a dkms module, or by using newer kernels (5.6+) +The features of wg-manager includes: + +**Server** +* Create/Delete/Modify +* Start/Stop/Restart server +* Import existing + +**Peer** +* Create/Delete/Modify +* Bandwidth usage statistics +* Export by QRCode, Text + +**General** +* Modify Admin User # Dependencies -* wireguard-dkms or Linux kernel >= 5.6 -* python 3.6+ +* Linux >= 5.6 *(Alternatively: wireguard-dkms)* -# Installation (Docker) +# Common Installation Steps 1. Enable ip forwarding with `sysctl -w net.ipv4.ip_forward=1` -1.1. To make the forwarding persistent add `net.ipv4.ip_forward = 1` to `/etc/sysctl.d/99-sysctl.conf` -2. It is recommended to have a firewall protecting your services -## Docker -```bash -docker run -d \ ---cap-add NET_ADMIN \ ---name wireguard-manager \ ---net host \ --p "51800-51900:51800-51900/udp" \ --v wireguard-manager:/config \ --e PORT="8888" \ --e ADMIN_USERNAME="admin" \ --e ADMIN_PASSWORD="admin" \ -perara/wireguard-manager -``` + * To make the forwarding persistent add `net.ipv4.ip_forward = 1` to `/etc/sysctl.d/99-sysctl.conf` +2. It is recommended to have a firewall protecting your servers -## Docker-compose +## Notes +* A few people has experienced issues with running the dockerized method using bridged networking. To fix this, you can use `network_mode: host`. Note that you can no longer reverse-proxy the web interface from reverse proxies such as [jwilder/nginx-proxy](https://hub.docker.com/r/jwilder/nginx-proxy/). + +## Method #1: Docker-compose ```yaml wireguard: container_name: wireguard-manager image: perara/wireguard-manager cap_add: - NET_ADMIN + #network_mode: host # Alternatively ports: - 51800:51900/udp - 8888:8888 volumes: - - ./ops/wireguard/_data:/config + - ./wg-manager:/config environment: HOST: 0.0.0.0 PORT: 8888 @@ -51,11 +47,20 @@ perara/wireguard-manager ADMIN_USERNAME: admin WEB_CONCURRENCY: 1 ``` +or [plain docker here](./docs/guides/docker_configuration.md) -# Install (OS) -- [Installation on Debian/Ubuntu](./docs/install_debian.md) (TODO) +# Method #2: Bare Metal +- [Installation on Debian/Ubuntu](./docs/install_debian.md) - [Installation on Raspberry PI 4](./docs/install_rpi.md) +### Guides +- [Importing Existing configuration](./docs/guides/import_existing_server.md) +- [Reverse Proxy](./docs/guides/reverse_proxy.md) + +# Usage +When docker container/server has started, go to http://localhost:8888 + + # Environment variables | Environment | Description | Recommended | |------------------|--------------------------------------------------------------------------|-------------| @@ -68,21 +73,6 @@ perara/wireguard-manager | ADMIN_USERNAME | Default admin username on database creation | admin | | ADMIN_PASSWORD | Default admin password on database creation | admin | - -# Usage -When docker container is started, go to http://localhost:80 - -### Importing existing configuration -1. Click the Import configuration button in the right pane -2. Select all relevant server and client files. There is a few cases here: - 1. If you only provide a server configuration. Everything will load fine, but you cannot export peer.configurations - 2. If you provide both client and server configurations. Everything should work ok - 3. Client should have [Interface] and [Peer] defined. Currently only supporting clients with 1 peer section. - -# Reverse Proxy -Use jwilder/nginx-proxy or similar. - - # Showcase ![Illustration](docs/images/0.png) diff --git a/docs/guides/docker_configuration.md b/docs/guides/docker_configuration.md new file mode 100644 index 0000000..467856e --- /dev/null +++ b/docs/guides/docker_configuration.md @@ -0,0 +1,13 @@ +# Docker Configuration +```bash +docker run -d \ +--cap-add NET_ADMIN \ +--name wireguard-manager \ +--net host \ +-p "51800-51900:51800-51900/udp" \ +-v wireguard-manager:/config \ +-e PORT="8888" \ +-e ADMIN_USERNAME="admin" \ +-e ADMIN_PASSWORD="admin" \ +perara/wireguard-manager +``` diff --git a/docs/guides/import_existing_server.md b/docs/guides/import_existing_server.md new file mode 100644 index 0000000..b86e627 --- /dev/null +++ b/docs/guides/import_existing_server.md @@ -0,0 +1,61 @@ +# Importing existing configuration +It is not unusual to have existing WireGuard configurations in production, and for this reason, we support to import these in full or partial form. + +It is possible to: +1. Import server configuration only + * Peer export will not work due to impartial information, such as missing private-key +2. Import peer configuration only, + * Server configuration will only be partial. e.g private-key must be manually entered +3. Import server **and** peer configuration. + * Given compliant configuration (see assumptions), everything should be fully imported. + +## Configuration assumptions +There are a few assumptions made for the configuration to be successfully imported. +1. Generally, any file that **does not contain** **Endpoint** key in the Peer sections are servers. The import will fail +if multiple files is without Endpoint +2. All files that **have Endpoint defined** are considered peers of the server +3. All files should be imported at the **same time** + +### Server +The format of the server should look similar to this: +``` +[Interface] +Address = 10.0.92.1/24 +PrivateKey = 0MHXsC4zJrDZA5MpZZKQiS/j5srAvSC9bJx7Igtq1FE= +ListenPort = 56944 +PostUp = +PostDown = + +[Peer] +PublicKey = XNRPEweV3guSis3YRHDBldizn6xivv+2Tug0G/BM6gE= +AllowedIPs = 10.0.92.2/32 + +[Peer] +PublicKey = XNRPEweV3guSis3YRHDBldizn6xivv+2Tug0G/BM6gE= +AllowedIPs = 10.0.92.3/32 +``` + +### Peer +``` +[Interface] +Address = 10.0.92.2/24 +PrivateKey = aN08xqUVOEAoc74e2yzvN/yOtXJgtISru7mjrPFhlUY +DNS="8.8.8.8" + +[Peer] +PublicKey = gybMBZBfwsmsXBl8bG2ZobGiG77aGdxOoyQsjTzrKkY= +AllowedIPs = 0.0.0.0/0 +Endpoint = my-address.com:5455 + + +[Peer] +PublicKey = gybMBZBfwsmsXBl8bG2ZobGiG77aGdxOoyQsjTzrKkY= +AllowedIPs = 0.0.0.0/0 +Endpoint = my-address.com:5455 +``` +Note that we do **not** support importing peers with multiple peer sections. + +## How to +1. Click the **Import Configuration** button in the right pane +2. Select all relevant server and client files and submit. +3. If successfully, the server configuration should now be filled and a indicator on how many peers added is shown at the bottom of the form. diff --git a/docs/guides/reverse_proxy.md b/docs/guides/reverse_proxy.md new file mode 100644 index 0000000..95c7fdd --- /dev/null +++ b/docs/guides/reverse_proxy.md @@ -0,0 +1,2 @@ +# Reverse Proxy +Use jwilder/nginx-proxy or similar.