mirror of
https://github.com/towalink/wgfrontend.git
synced 2025-04-19 00:45:15 +00:00
162 lines
5.3 KiB
Markdown
162 lines
5.3 KiB
Markdown
# wgfrontend
|
|
|
|
A simple web frontend for configuring peers within a WireGuard configuration file to thus administer road warrior clients.
|
|
|
|
There are already a lot of user interfaces for administering WireGuard configuration files available. However, many of them have a bunch of dependencies, require root privileges to operate, or are a hassle to set up. "wgfrontend" provides a user interface that can be easily installed by just installing a package from Python's package repository PyPi (i.e. using pip).
|
|
|
|
This little tool is independent of the Towalink site connectivity solution (see https://towalink.readthedocs.io).
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- Web frontend for adding, modifying, and deleting WireGuard peers
|
|
- Config files for WireGuard peers can be downloaded
|
|
- Config files for WireGuard peers are shown as QR Code
|
|
- Assistant for initial set-up
|
|
- Web frontend has responsive design
|
|
- Web frontend does not run with root privileges
|
|
- Simple installation
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Make sure that WireGuard is available and its tools are installed:
|
|
|
|
```shell
|
|
# For Alpine:
|
|
apk add wireguard wireguard-tools
|
|
# For Debian:
|
|
apt install wireguard wireguard-tools
|
|
```
|
|
|
|
Install as root user using PyPi:
|
|
|
|
```shell
|
|
pip3 install wgfrontend
|
|
```
|
|
|
|
Note that this no longer works in more recent environments as `pip3` should no longer install in the system environment. You may do
|
|
|
|
```shell
|
|
pip3 install wgfrontend --break-system-packages
|
|
```
|
|
|
|
to override. Alternatively use `pipx` (install via `apt install pipx` on Debian) like this:
|
|
|
|
```shell
|
|
PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/bin pipx install wgfrontend
|
|
```
|
|
|
|
You may use another directory than `/opt/pipx` but it must be accessible for the regular user that will run `wgfrontend` later (i.e. don't use the default directory located within the root home directory). `PIPX_BIN_DIR` needs to be in the system search path (`systemd-path search-binaries-default` on Debian).
|
|
|
|
Note: In case you get an error regarding the imaging library needed for generating QR Codes, try to install it via the operating system packages:
|
|
|
|
```shell
|
|
# For Alpine:
|
|
apk add py3-pillow
|
|
# For Debian:
|
|
apt install python3-pil
|
|
```
|
|
|
|
---
|
|
|
|
## Quickstart
|
|
|
|
After installing "wgfrontend" as shown above, just execute the tool with root permissions to get started:
|
|
|
|
```shell
|
|
wgfrontend
|
|
```
|
|
|
|
An interactive set-up assistant queries for the needed configuration data and sets up the environment.
|
|
Once everything is configured, "wgfrontend" drops root privileges and runs a small web server on port 8080 to serve the web frontend.
|
|
|
|
Note: You may run the set-up assistant from scratch after deleting the configuration files (see the details below) manually.
|
|
|
|
---
|
|
|
|
## Screenshots
|
|
|
|
|
|
|
|
See additional screenshots in the "screenshots" folder.
|
|
|
|
---
|
|
|
|
## Details
|
|
|
|
### The wgfrontend configuration file
|
|
|
|
The interactive set-up assistant creates a configuration file with the desired information. It is located at "/etc/wgfrontend/wgfrontend.conf".
|
|
|
|
Here is an example:
|
|
|
|
```
|
|
### Config file of the Towalink WireGuard Frontend ###
|
|
[general]
|
|
# The WireGuard config file to read and write
|
|
wg_configfile = /etc/wireguard/wg_rw.conf
|
|
|
|
# The command to be executed when the WireGuard config has changed
|
|
on_change_command = "sudo /etc/init.d/wgfrontend_interface restart"
|
|
|
|
# The interface to bind to for the web server
|
|
socket_host = 0.0.0.0
|
|
|
|
# The port to bind to for the web server
|
|
socket_port = 8080
|
|
|
|
# The system user to be used for the frontend
|
|
user = wgfrontend
|
|
|
|
[users]
|
|
admin = dc524e423d9762830649d4d9e18f4b47a56c92f96646104dd06c71b26b54f732e8318d5b60a6b2b01b4f269407771496e879c9bf65ca9ef4f55a243ff358fc8dfea0bd9d30d766320857093eb95022822f71b098215f26f6d2644033d956bfdd
|
|
```
|
|
|
|
### Add an additional frontend user
|
|
|
|
Create a password hash using the following command:
|
|
|
|
```shell
|
|
wgfrontend-password
|
|
```
|
|
|
|
Using this, you can add another user to the [users] section in the wgfrontend configuration file.
|
|
|
|
### A note on security
|
|
|
|
Don't expose the web frontend to the Internet without another layer of protection.
|
|
|
|
The wgfrontend web server does not run with root permissions. That's a start and better than many other WireGuard frontends. But the web server user has the permission to write to a WireGuard configuration file. This file may reference scripts that are run with root permissions when wg-quick is run. In case of a vulnerability in wgfrontend, this can be abused for privilege escalation. Thus add an additional safeguard layer of protection.
|
|
|
|
---
|
|
|
|
## Reporting bugs
|
|
|
|
In case you encounter any bugs, please report the expected behavior and the actual behavior so that the issue can be reproduced and fixed.
|
|
|
|
---
|
|
|
|
## Developers
|
|
|
|
### Clone repository
|
|
|
|
Clone this repo to your local machine using `https://github.com/towalink/wgfrontend.git`
|
|
|
|
Install the module temporarily to make it available in your Python installation:
|
|
```shell
|
|
pip3 install -e <path to directory with setup.py>
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
[](https://opensource.org/licenses/AGPL-3.0)
|
|
|
|
- **[AGPL3 license](https://opensource.org/licenses/AGPL-3.0)**
|
|
- Copyright 2020 © <a href="https://github.com/towalink/wgfrontend" target="_blank">Dirk Henrici</a>.
|
|
- [WireGuard](https://www.wireguard.com/) is a registered trademark of Jason A. Donenfeld.
|