Metadata-Version: 2.4
Name: opnspeedguard
Version: 1.0.0
Summary: A tool that automatically makes an OPNSense firewall's WireGuard daemon switch to another server(peer) with a good bandwidth, for use in a road warrior setup.
Project-URL: Homepage, https://github.com/KipJM/OPNSpeedGuard
Project-URL: Issues, https://github.com/KipJM/OPNSpeedGuard/issues
Author-email: KIP <kip@kip.gay>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: requests
Requires-Dist: speedtest-cli
Requires-Dist: urllib3
Description-Content-Type: text/markdown

# OPNSpeedGuard
A tool that automatically makes an [OPNSense](https://opnsense.org/) firewall's WireGuard daemon
switch to another server(peer) with a good bandwidth, for use in a 
[road warrior setup](https://docs.opnsense.org/manual/how-tos/wireguard-client.html).

# Demo
# TODO

# Install
There are two versions:
- From PyPI, Here: #TODO
- A packaged executable via pyinstaller.
  - Lastest release here: [Link](https://github.com/KipJM/opnspeedguard/releases/latest)

Both have full functionality, but since pyinstaller can't cross-compile, the packaged executable currently only has a Windows build.

# Usage
## Setup
As stated, this only works for a road warrior setup. Specifically, this is designed for Mullvad, for
use in conjunction with my [OpnsenseMullvadPeerAdder](https://github.com/KipJM/OpnsenseMullvadPeerAdder).
However this tool will work with other wg setups as well, but some cosmetic features will be broken.

**You'll need two main things:**
- api_key.txt: API key file
- config.json: tool config file

### api_key.txt
You can retrieve this from your OPNSense web UI.
1. Go to your web UI
2. Switch to System > Access > Users
3. It is recommended to create a dedicated app user for security, but you do you.
4. Make sure the user has at least the following permissions:
   - **VPN: WireGuard: Configuration**
   - **VPN: WireGuard: Status**
   - System: Gateways _(optional, for resetting gateway watcher)_ 
5. Generate the api_key.txt file by clicking the ticket button next to the user. It is recommended to rename the file "api_key.txt". Inside should be two lines, key=..., secret=... .
6. Either pass its path through the -api argument, or put it in the working directory and the tools will find it automatically (must be call "api_key.txt").

### config.json
This controls most behaviors of OPNSpeedGuard. A few optional controls are given through CLI prompts if `automatic=false`.

You can generate a template via the command `opnspeedguard --genconfig --config [path to generated config file]`.
Once generated, you'll have to edit some of its values. **Descriptions on what each variable controls can be found in
[config.py](https://github.com/KipJM/opnspeedguard/blob/master/config.py).**

**YOU MUST EDIT `instance_UUID` and `opnsense_api`.**
- `instance_UUID`: Can be found via devtools or this [script](https://github.com/KipJM/OpnsenseMullvadPeerAdder/blob/master/config_and_run_me_first.py).
- `opnsense_api`: URL to your firewall's web portal, include the /api location. The script has certificate verification turned off, so feel free to use self-signed HTTPS.  

## Running
For python version, run
`python -m opnspeedguard  [...]`.\
**Run `python -m opnspeedguard -h` for help information.**

For packaged executable version, run it like any other shell tool. For example on Windows Powershell, 
run `.\opnspeedguard [...]`.

The tool itself should contain enough help info on what each step does.

# License
```
OPNSpeedGuard: A tool that automatically makes an OPNSense firewall's WireGuard daemon
switch to another server(peer) with a good bandwidth, for use in a road warrior setup.
Copyright (C) 2026 KIP

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

You can contact me, the author, via email at oss@kip.gay.
```
_OPNSense, WireGuard, and Mullvad are registered trademarks of their respective owners. This is an unofficial project not associated nor endorsed with/by these entities._