search

FokiDoki / WireRest

REST API for Wireguard
MIT License
18 stars 5 forks source link
api java java-21 monitoring prometheus prometheus-exporter rest rest-api restful-api swagger-ui vpn wireguard wireguard-vpn

readme

WireRest - REST API for Wireguard

Build status Tests coverage

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

Features:

Install script

You can use this bash script to install WireRest automatically.

Script tested on

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.sh

If you want to install WireRest for other WireGuard profiles just run this script again. Warning: WireRest and its service will be reinstalled.

How to run:

[!!] 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=wg0

Replace 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

Available run parameters:

All parameters that are set as an example are the default values

Token authentication

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:

  1. As a query parameter like /v1/peers?token=TOKEN
  2. As a header (bearer authentication): Authorization: Bearer TOKEN

Caching

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:

It's recommended to use caching, but if you want to disable it, set --wg.cache.enabled=false

Monitoring

You can monitoring Wireguard and WIreRest with prometheus.

WireGuard metrics:

WireRest metrics:

You also can download grafana dashboard. Guide how to install and dashboard avaliable here or here

How to install Java 21

For debian (ubuntu) x64 systems:

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 install

And then run dpkg again sudo dpkg -i jdk-21_linux-x64_bin.deb

For arm64 systems:

wget https://download.oracle.com/java/20/latest/jdk-21_linux-aarch64_bin.rpm
sudo rpm -i jdk-21_linux-aarch64_bin.rpm

Then 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)

Continue installation

You can find the Java 21 package for you system there

Examples:

Get all peers:

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
    }
  ]
}

Create peer automatically:

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
}

Create peer with custom parameters:

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
}

Delete peer:

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
}

Update peer:

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
}

Get peer by public key:

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
}

Get logs of service:

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

How to build:

mvn clean package