# 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
Install using PyPi:
```shell
pip3 install wgfrontend
```
Note: In the 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.
---
## 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.
Raw data
{
"_id": null,
"home_page": "https://www.github.com/towalink/wgfrontend",
"name": "wgfrontend",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Towalink VPN WireGuard frontend gui",
"author": "The Towalink Project",
"author_email": "pypi.wgfrontend@towalink.net",
"download_url": "https://files.pythonhosted.org/packages/c4/0d/2107ca06bee2b932b25e6aaae93c2efdbc0f074acfe864690f78ac881011/wgfrontend-1.0.1.tar.gz",
"platform": null,
"description": "# wgfrontend\n\nA simple web frontend for configuring peers within a WireGuard configuration file to thus administer road warrior clients.\n\nThere 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).\n\nThis little tool is independent of the Towalink site connectivity solution (see https://towalink.readthedocs.io).\n\n---\n\n## Features\n\n- Web frontend for adding, modifying, and deleting WireGuard peers\n- Config files for WireGuard peers can be downloaded\n- Config files for WireGuard peers are shown as QR Code\n- Assistant for initial set-up\n- Web frontend has responsive design\n- Web frontend does not run with root privileges\n- Simple installation\n\n---\n\n## Installation\n\nInstall using PyPi:\n\n```shell\npip3 install wgfrontend\n```\n\nNote: In the case you get an error regarding the imaging library needed for generating QR Codes, try to install it via the operating system packages:\n\n```shell\n# For Alpine:\napk add py3-pillow\n# For Debian:\napt install python3-pil\n```\n\n---\n\n## Quickstart\n\nAfter installing \"wgfrontend\" as shown above, just execute the tool with root permissions to get started:\n\n```shell\nwgfrontend\n```\n\nAn interactive set-up assistant queries for the needed configuration data and sets up the environment.\nOnce everything is configured, \"wgfrontend\" drops root privileges and runs a small web server on port 8080 to serve the web frontend.\n\n---\n\n## Screenshots\n\n![screenshot: show a client config](https://raw.githubusercontent.com/towalink/wgfrontend/main/screenshots/show.png \"Show a client config\")\n\nSee additional screenshots in the \"screenshots\" folder.\n\n---\n\n## Details\n\n### The wgfrontend configuration file\n\nThe interactive set-up assistant creates a configuration file with the desired information. It is located at \"/etc/wgfrontend/wgfrontend.conf\".\n\nHere is an example:\n\n```\n### Config file of the Towalink WireGuard Frontend ###\n[general]\n# The WireGuard config file to read and write\nwg_configfile = /etc/wireguard/wg_rw.conf\n\n# The command to be executed when the WireGuard config has changed\non_change_command = \"sudo /etc/init.d/wgfrontend_interface restart\"\n\n# The interface to bind to for the web server\nsocket_host = 0.0.0.0\n\n# The port to bind to for the web server\nsocket_port = 8080\n\n# The system user to be used for the frontend\nuser = wgfrontend\n\n[users]\nadmin = dc524e423d9762830649d4d9e18f4b47a56c92f96646104dd06c71b26b54f732e8318d5b60a6b2b01b4f269407771496e879c9bf65ca9ef4f55a243ff358fc8dfea0bd9d30d766320857093eb95022822f71b098215f26f6d2644033d956bfdd\n```\n\n### Add an additional frontend user\n\nCreate a password hash using the following command:\n\n```shell\nwgfrontend-password\n```\n\nUsing this, you can add another user to the [users] section in the wgfrontend configuration file.\n\n### A note on security\n\nDon't expose the web frontend to the Internet without another layer of protection.\n\nThe 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.\n\n---\n\n## Reporting bugs\n\nIn case you encounter any bugs, please report the expected behavior and the actual behavior so that the issue can be reproduced and fixed.\n\n---\n\n## Developers\n\n### Clone repository\n\nClone this repo to your local machine using `https://github.com/towalink/wgfrontend.git`\n\nInstall the module temporarily to make it available in your Python installation:\n```shell\npip3 install -e <path to directory with setup.py>\n```\n\n---\n\n## License\n\n[](https://opensource.org/licenses/AGPL-3.0)\n\n- **[AGPL3 license](https://opensource.org/licenses/AGPL-3.0)**\n- Copyright 2020 \u00a9 <a href=\"https://github.com/towalink/wgfrontend\" target=\"_blank\">Dirk Henrici</a>.\n- [WireGuard](https://www.wireguard.com/) is a registered trademark of Jason A. Donenfeld.\n",
"bugtrack_url": null,
"license": null,
"summary": "web-based user interface for configuring WireGuard for roadwarriors",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://towalink.readthedocs.io",
"Homepage": "https://www.github.com/towalink/wgfrontend",
"Project homepage": "https://www.towalink.net",
"Repository": "https://www.github.com/towalink/wgfrontend"
},
"split_keywords": [
"towalink",
"vpn",
"wireguard",
"frontend",
"gui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0b58d098fc470e34826ab2c50ee70a165685c1180227fc2e6284a62a38292345",
"md5": "acd34c5e9c17a859881e094a4acfca18",
"sha256": "74e65a00405db45fa81cacff21a5cd7244de44cdbd8748f7be18c81930548df4"
},
"downloads": -1,
"filename": "wgfrontend-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acd34c5e9c17a859881e094a4acfca18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 40057,
"upload_time": "2024-05-04T20:11:05",
"upload_time_iso_8601": "2024-05-04T20:11:05.761072Z",
"url": "https://files.pythonhosted.org/packages/0b/58/d098fc470e34826ab2c50ee70a165685c1180227fc2e6284a62a38292345/wgfrontend-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c40d2107ca06bee2b932b25e6aaae93c2efdbc0f074acfe864690f78ac881011",
"md5": "d75aa9dd445aaf574569fc1d21812928",
"sha256": "712dbc2026bbae0dd53505d477ac02a36197a1499dcf9e8c211208c094a97e8a"
},
"downloads": -1,
"filename": "wgfrontend-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d75aa9dd445aaf574569fc1d21812928",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 36378,
"upload_time": "2024-05-04T20:11:10",
"upload_time_iso_8601": "2024-05-04T20:11:10.469323Z",
"url": "https://files.pythonhosted.org/packages/c4/0d/2107ca06bee2b932b25e6aaae93c2efdbc0f074acfe864690f78ac881011/wgfrontend-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-04 20:11:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "towalink",
"github_project": "wgfrontend",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wgfrontend"
}
JSON
