WireRest is a powerful, restful stateless API for Wireguard. With built-in caching, it is optimized to work with large configurations. You can use it both for your small private server and for high-load public applications. It is written in Java using Spring Boot and Spring WebFlux.
DEMO: http://wr-demo.fokidoki.su:8081/swagger-ui
- Get all peers (sorting is available)
- Automatically create and add peer
- Manually create and add peer
- Delete peer
- Update peer
- Get peer by public key
- Get interface configuration
- Get general config (interface) information
- Token authentication
You can use this bash script to install WireRest automatically.
Script tested on
- Ubuntu >= 18.04
- Debian >= 10
- Fedora 16
- CentOS 8
If your OS is not on this list, you can still try using this script, just install Java 21 before
Wireguard must be installed in advance (You can use this script to install & configure WG)
wget https://github.com/FokiDoki/WireRest/releases/download/0.7-BETA/install.sh
chmod +x install.sh
./install.shIf you want to install WireRest for other WireGuard profiles just run this script again. Warning: WireRest and its service will be reinstalled.
[!!] Java 21 is required (how to install)
Simple run:
wget https://github.com/FokiDoki/WireRest/releases/download/0.7-BETA/wirerest-0.7.jar
sudo java -jar wirerest-0.7.jar --wg.interface.name=wg0Replace wg0 with the name of your Wireguard interface. Use sudo wg show to list all active Wireguard interfaces if you don't know your interface name.
Syntax:
sudo java -jar wirerest-0.7.jar --parameter=value --parameter2=value2 ...The default port is 8081.
If the launch was successful, you can check the list of available methods and parameters in swagger at http://SERVER-IP:8081/swagger-ui
All parameters that are set as an example are the default values
--wg.interface.name=wg0- Wireguard interface name--security.token=admin- Token for access to API (change it! If you want to disable token auth, set it to empty string). More info--server.port=8081- WireRest port--wg.cache.enabled=true- Enable or disable caching (true is recommended). More info about caching here--wg.interface.default.mask=32- Mask for ip of new peers--wg.interface.default.persistent-keepalive=0- Default persistent keepalive for new clients--wg.cache.update-interval=60- Cache update interval (seconds). it is needed to track changes that have occurred bypassing WireRest. A shorter interval can increase CPU usage. Be careful with this parameter.--logging.api.max-elements=1000- The maximum number of logs that will be saved for access to them through the API
Each request to the API must contain a token.
The token is set in the --security.token parameter.
If you want to disable token authentication, set it to empty.
Token can be passed in two ways:
- As a query parameter like
/v1/peers?token=TOKEN - As a header (bearer authentication):
Authorization: Bearer TOKEN
WireRest has built-in caching. It is enabled by default.
Caching greatly improves performance on large configurations.
The cache is updated every --wg.cache.update-interval seconds (default 60 seconds).
Quick overview:
transferRx,transferTxandlatestHandshakefields are updated after every sync- Peer creation, deletion, and update operations work instantly.
- If you update the wireguard configuration bypassing WireRest, the changes will appear in WireRest during the next sync
It's recommended to use caching, but if you want to disable it, set --wg.cache.enabled=false
You can monitoring Wireguard and WIreRest with prometheus.
WireGuard metrics:
- Number of peers
- Number of avaliable/total IPs
- Network TX/RX for all clients in config
WireRest metrics:
- WireRest CPU/RAM usage
- Uptime
- Endpoints requests
- RPS
- etc.
You also can download grafana dashboard. Guide how to install and dashboard avaliable here or here
sudo apt-get update
wget https://download.oracle.com/java/21/latest/jdk-21_linux-x64_bin.deb
sudo dpkg -i jdk-21_linux-x64_bin.deb
If you get an error dpkg: error processing package jdk-21
Run this command:
apt --fix-broken installAnd then run dpkg again sudo dpkg -i jdk-21_linux-x64_bin.deb
wget https://download.oracle.com/java/21/latest/jdk-21_linux-aarch64_bin.rpm
sudo rpm -i jdk-21_linux-aarch64_bin.rpmThen check if java is installed:
java --version
> openjdk 21 2023-09-19
> OpenJDK Runtime Environment (build 21+35)
> OpenJDK 64-Bit Server VM (build 21+35, mixed mode, sharing)You can find the Java 21 package for your system there
curl -X 'GET' \
'http://localhost:8081/v1/peers?limit=1' \
-H 'accept: application/json'{
"totalPages": 100,
"currentPage": 0,
"content": [
{
"publicKey": "ALD3x7qWP0W/4zC26jFozxw28vXJsazA33KnHF+AfHw=",
"presharedKey": "3hFqZXqzO+YkVL4nX2siavxK1Z3h5lRLkEQz1qf3giI=",
"endpoint": "123.23.2.3:55412",
"allowedSubnets": [
"10.1.142.196/32",
"2002:0:0:1234::/64"
],
"latestHandshake": 1690200786,
"transferRx": 12345,
"transferTx": 54321,
"persistentKeepalive": 25
}
]
}curl -X 'POST' \
'http://localhost:8081/v1/peers' \
-H 'accept: application/json'{
"publicKey": "cHViREF4TWc9PUZha2VQdWJLZXkgICAgICAyMDAxMw==",
"presharedKey": "RmFrZVBza0tleUZha2VQc2tLZXkgICAgICAyMDAxNA==",
"privateKey": "RmFrZVBydktleUZha2VQcnZLZXkgICAgICAyMDAxMg==",
"allowedSubnets": [
"10.0.0.9/32"
],
"persistentKeepalive": 0
}curl -X 'POST' \
'http://localhost:8081/v1/peers?publicKey=RmFrZVBydktleUZha2VQcnZLZXkgICAgICAyMDAxNQ%3D%3D&presharedKey=RmFrZVBza0tleUZha2VQc2tLZXkgICAgICAyMDAxNw%3D%3D&privateKey=cHViREF4TlE9PUZha2VQdWJLZXkgICAgICAyMDAxNg%3D%3D&allowedIps=10.0.0.32%2F32&allowedIps=2002%3A0%3A0%3A1234%3A%3A%2F64&persistentKeepalive=25' \
-H 'accept: application/json'{
"publicKey": "RmFrZVBydktleUZha2VQcnZLZXkgICAgICAyMDAxNQ==",
"presharedKey": "RmFrZVBza0tleUZha2VQc2tLZXkgICAgICAyMDAxNw==",
"privateKey": "cHViREF4TlE9PUZha2VQdWJLZXkgICAgICAyMDAxNg==",
"allowedSubnets": [
"2002:0:0:1234::/64",
"10.0.0.32/32"
],
"persistentKeepalive": 25
}curl -X 'DELETE' \
'http://localhost:8081/v1/peers?publicKey=AhM4WLR7ETzLYDQ0zEq%2F0pvbYAxsbLwzzlIAdWhR7yg%3D' \
-H 'accept: application/json'{
"publicKey": "AhM4WLR7ETzLYDQ0zEq/0pvbYAxsbLwzzlIAdWhR7yg=",
"presharedKey": "3hFqZXqzO+YkVL4nX2siavxK1Z3h5lRLkEQz1qf3giI=",
"endpoint": "123.23.2.3:55412",
"allowedSubnets": [
"10.1.142.196/32",
"2002:0:0:1234::/64"
],
"latestHandshake": 1690200786,
"transferRx": 12345,
"transferTx": 54321,
"persistentKeepalive": 25
}curl -X 'PATCH' \
'http://localhost:8081/v1/peers?publicKey=cHViREF4T0E9PUZha2VQdWJLZXkgICAgICAyMDAxOQ%3D%3D&presharedKey=%2BEWn9NeR2pVuFHihYMC6LKreccd5VIW4prUkzHLy0nw%3D' \
-H 'accept: application/json'{
"publicKey": "cHViREF4T0E9PUZha2VQdWJLZXkgICAgICAyMDAxOQ==",
"presharedKey": "+EWn9NeR2pVuFHihYMC6LKreccd5VIW4prUkzHLy0nw=",
"endpoint": "123.123.123.123:12345",
"allowedSubnets": [
"10.0.0.11/32"
],
"latestHandshake": 1690200786,
"transferRx": 12345,
"transferTx": 54321,
"persistentKeepalive": 25
}curl -X 'GET' \
'http://localhost:8081/v1/peers/find?publicKey=cHViREF4T0E9PUZha2VQdWJLZXkgICAgICAyMDAxOQ%3D%3D' \
-H 'accept: application/json'{
"publicKey": "cHViREF4T0E9PUZha2VQdWJLZXkgICAgICAyMDAxOQ==",
"presharedKey": "+EWn9NeR2pVuFHihYMC6LKreccd5VIW4prUkzHLy0nw=",
"endpoint": "123.123.123.123:12345",
"allowedSubnets": [
"10.0.0.11/32"
],
"latestHandshake": 1690200786,
"transferRx": 12345,
"transferTx": 54321,
"persistentKeepalive": 25
}curl -X 'GET' \
'http://localhost:8081/v1/interface' \
-H 'accept: application/json'{
"privateKey": "RmFrZVBydktleUZha2VQcnZLZXkgICAgICAgICAgMA==",
"publicKey": "cHViQ0FnTVE9PUZha2VQdWJLZXkgICAgICAgICAgMg==",
"listenPort": 16666,
"fwMark": 0
}curl -X 'GET' \
'http://localhost:8081/v1/service/logs?from=0&limit=100' \
-H 'accept: application/json'[
{
"level": "INFO",
"message": "Init duration for springdoc-openapi is: 529 ms",
"timestamp": 1690301255231
},
{
"level": "ERROR",
"message": "Peer with public key ALD3x7qWP0W/4zC26jFozxw28vXJsazA33KnHF+AfHw= not found",
"timestamp": 1690301333239
}
]These are all just examples, more parameters and example responses can be found in your version of swagger ui
mvn clean package