simono41/prometheus_wireguard_exporter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Readme simplifications and improvements (#65)

Browse source 
- Split setup section in three subsections:
     1. Pre built binaries, empty for now, with a subscribe link to #59 
     2. Docker with simplified step-by-step instructions
         - Add Docker tagged images information
     3. Rust with simplified step-by-step instructions
- Fix `<switch>` not showing in tables
- Add syntax highlighting to code blocks
- Highlight Docker image cross cpu compatibility, as many users crave for this for their ARM devices
- Precise docker build only work on amd64/686 CPUs
- Clear up rustc version required to build
This commit is contained in:
Quentin McGaw 2021-07-08 10:57:40 -07:00 committed by GitHub
parent 9d37840b83
commit 45472a35b1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 60 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

102
README.md
View file

@ -16,7 +16,7 @@
## Intro
A Prometheus exporter for [WireGuard](https://www.wireguard.com), written in Rust. This tool exports the `wg show all dump` (or `wg show <interface> dump` if you specify a config file) results in a format that [Prometheus](https://prometheus.io/) can understand. The exporter is very light on your server resources, both in terms of memory and CPU usage.
A Prometheus exporter for [WireGuard](https://www.wireguard.com), written in Rust. This tool exports the `wg show all dump` (or `wg show <interface> dump` if you specify a config file) results in a format that [Prometheus](https://prometheus.io/) can understand. The exporter is very light on your server resources, both in terms of memory and CPU usage. It's also built for Docker for the following CPU architectures: `amd64`, `386`, `arm64`, `armv7` and `armv6`.
![](extra/01.png)
@ -31,77 +31,95 @@ A Prometheus exporter for [WireGuard](https://www.wireguard.com), written in Rus
* From release [3.0.0](https://github.com/MindFlavor/prometheus_wireguard_exporter/releases/tag/3.0.0) the exporter allows two label modes: one is to dump every allowed ip in a single label (called `allowed_ips`) along with their subnets. The second one is to create a pair of labels for each allowed ip/subnet pair (called `allowed_ip_0`/`allowed_subnet_0`, `allowed_ip_1`/`allowed_subnet_1` and so on for every allowed ip). The default if the single label mode but you can enable the second mode by specifying the `-s` switch at startup. Thank you [Toon Schoenmakers](https://github.com/schoentoon) for this solution (see issue [#8](https://github.com/MindFlavor/prometheus_wireguard_exporter/issues/8)).
* Starting from release [2.0.2](https://github.com/MindFlavor/prometheus_wireguard_exporter/releases/tag/2.0.2) this exporter supports IPv6 addresses too (thanks to [Maximilian Bosch](https://github.com/Ma27)'s PR [#5](https://github.com/MindFlavor/prometheus_wireguard_exporter/pull/5)).
## Prerequisites
## Setup
* You need [Rust](https://www.rust-lang.org/) to compile this code. Simply follow the instructions on Rust's website to install the toolchain. If you get weird errors while compiling please try and update your Rust version first (I have developed it on `rustc 1.55.0-nightly (798baebde 2021-07-02)`). Alternatively you can build the docker image or use the prebuilt one.
* You need [WireGuard](https://www.wireguard.com) *and* the `wg` CLI in the path. The tool will call `wg show <interface(s)>|all dump` and of course will fail if the `wg` executable is not found. If you want I can add the option of specifying the `wg` path in the command line, just open an issue for it.
### Pre-built binaries
Alternatively, as long as you have Wireguard on your host kernel with some Wireguard interfaces running, you can use Docker. For example:
Coming soon, subcribe to [#59](https://github.com/MindFlavor/prometheus_wireguard_exporter/issues/59)
```sh
docker run -it --rm --init --net=host --cap-add=NET_ADMIN mindflavor/prometheus-wireguard-exporter
# Check it's up
docker run -it --rm alpine:3.12 wget -qO- http://localhost:9586/metrics
```
### Docker
ℹ️ The Docker image is compatible with `amd64`, `386`, `arm64`, `armv7` and `armv6` CPUs.
1. You need Docker installed
1. You need [WireGuard](https://www.wireguard.com) installed in your host kernel
1. You need some Wireguard interfaces running
1. Download and run the container with:
To update the image, you can use
```sh
docker run -d --init --net=host --cap-add=NET_ADMIN --name wgexporter mindflavor/prometheus-wireguard-exporter
```
1. Check it's up by visiting [http://localhost:9586/metrics](http://localhost:9586/metrics)
You can then update the image with
```sh
docker pull mindflavor/prometheus_wireguard_exporter
```
You can also build it with:
Or use a [tagged image](https://hub.docker.com/r/mindflavor/prometheus-wireguard-exporter/tags) such as `:3.5.1`.
If your host has an `amd64` or `686` CPU, you can also build the Docker image from source (you need `git`) with:
```sh
docker build -t mindflavor/prometheus_wireguard_exporter https://github.com/MindFlavor/prometheus_wireguard_exporter.git
docker build -t mindflavor/prometheus_wireguard_exporter https://github.com/MindFlavor/prometheus_wireguard_exporter.git#master
```
## Compilation
### Build from source
To compile the latest master version:
1. You need [Rust](https://www.rust-lang.org/tools/install) installed
1. You need [WireGuard](https://www.wireguard.com) installed on your host
1. You need `wg` accessible in your path. The tool will call `wg show <interface(s)>|all dump` and of course will fail if the `wg` executable is not found.
1. You need some Wireguard interfaces running
1. You need `git` installed
1. Clone the repository with
```bash
git clone https://github.com/MindFlavor/prometheus_wireguard_exporter.git
cd prometheus_wireguard_exporter
cargo install --path .
```
```sh
git clone https://github.com/MindFlavor/prometheus_wireguard_exporter.git
cd prometheus_wireguard_exporter
```
If you want the latest release you can simply use:
1. Compile the program with
```bash
cargo install prometheus_wireguard_exporter
```
```sh
cargo install --path .
```
You can also build the Docker image with
💁 If you encounter errors, please try updating your rust installation with `rustup update`.
The code should compile with any relatively recent, 2018-compliant rustc version.
As a frame of reference, the last release was built using the Rust Docker image using `rustc 1.53.0 (53cb7b09b 2021-06-17)`.
```sh
docker build -t mindflavor/prometheus-wireguard-exporter .
```
1. Run the program
```sh
./prometheus_wireguard_exporter
```
1. Check it's up by visiting [http://localhost:9586/metrics](http://localhost:9586/metrics)
## Usage
### Flags available
Start the binary with `-h` to get the complete syntax. The parameters are:
| Parameter | Mandatory | Valid values | Default | Accepts multiple occurrences? | Description |
| -- | -- | -- | -- | -- | -- |
| `-v` | no | <switch> | | No | Enable verbose mode.
| `-a` | no | <switch> | | No | Prepends sudo to `wg` commands.
| `-l` | no | any valid ip address | 0.0.0.0 | No | Specify the service address. This is the address your Prometheus instance should point to.
| `-p` | no | any valid port number | 9586 | No | Specify the service port. This is the port your Prometheus instance should point to.
| `-v` | no | `<switch>` | | No | Enable verbose mode.
| `-a` | no | `<switch>` | | No | Prepends sudo to `wg` commands.
| `-l` | no | any valid ip address | `0.0.0.0` | No | Specify the service address. This is the address your Prometheus instance should point to.
| `-p` | no | any valid port number | `9586` | No | Specify the service port. This is the port your Prometheus instance should point to.
| `-n` | no | path to the wireguard configuration file | | Yes | This flag adds the *friendly_name* attribute or the *friendly_json* attributes to the exported entries. See [Friendly tags](#friendly-tags) for more details. Multiple files are allowed (they will be merged as a single file in memory so avoid duplicates).
| `-s` | no | <switch> | off | No | Enable the allowed ip + subnet split mode for the labels.
| `-r` | no | <switch> | off | No | Exports peer's remote ip and port as labels (if available).
| `-s` | no | `<switch>` | off | No | Enable the allowed ip + subnet split mode for the labels.
| `-r` | no | `<switch>` | off | No | Exports peer's remote ip and port as labels (if available).
| `-i` | no | your interface name(s) | `all` | Yes | Specifies the interface(s) passed to the `wg show <interface> dump` parameter. Multiple parameters are allowed.
Once started, the tool will listen on the specified port (or the default one, 9586, if not specified) and return a Prometheus valid response at the url `/metrics`. So to check if the tool is working properly simply browse the `http://localhost:9586/metrics` (or whichever port you choose).
## Friendly Tags
### Friendly Tags
Starting from version 3.5 you can instruct the exporter to append a *friendly name* or a *friendly_json* to the exported entries. This can make the output more understandable than using the public keys. For example this is the standard output:
```
```ebnf
# HELP wireguard_sent_bytes_total Bytes sent to the peer
# TYPE wireguard_sent_bytes_total counter
wireguard_sent_bytes_total{interface="wg0",public_key="2S7mA0vEMethCNQrJpJKE81/JmhgtB+tHHLYQhgM6kk=",allowed_ips="10.70.0.2/32,10.70.0.66/32"} 3208804
@ -133,7 +151,7 @@ wireguard_latest_handshake_seconds{interface="wg0",public_key="wTjv6hS6fKfNK+SzO
And this is the one augmented with friendly names:
```
```ebnf
# HELP wireguard_sent_bytes_total Bytes sent to the peer
# TYPE wireguard_sent_bytes_total counter
wireguard_sent_bytes_total{interface="wg0",public_key="2S7mA0vEMethCNQrJpJKE81/JmhgtB+tHHLYQhgM6kk=",allowed_ips="10.70.0.2/32,10.70.0.66/32",friendly_name="OnePlus 6T"} 3208804
@ -163,8 +181,8 @@ wireguard_latest_handshake_seconds{interface="wg0",public_key="928vO9Lf4+Mo84cWu
wireguard_latest_handshake_seconds{interface="wg0",public_key="wTjv6hS6fKfNK+SzOLo7O6BQjEb6AD1TN9GjwZ08IwA=",allowed_ips="10.70.0.5/32",friendly_name="folioarch"} 0
```
In order for this to work, you need to add the `friendly_name` key value to the comments preceding a peer a specific metadata (in your wireguard configuration file). See below the `[Peer]` definition for an example.
The tag is called `friendly_name` and it will be added to the entry exported to Prometheus. Note that this is not a standard but, since it's a comment, will not interfere with WireGuard in any way.
In order for this to work, you need to add the `friendly_name` key value to the comments preceding a peer a specific metadata (in your wireguard configuration file). See below the `[Peer]` definition for an example.
The tag is called `friendly_name` and it will be added to the entry exported to Prometheus. Note that this is not a standard but, since it's a comment, will not interfere with WireGuard in any way.
From version [3.5.0](https://github.com/MindFlavor/prometheus_wireguard_exporter/releases/tag/3.5.0) you can optionally specify a `friendly_json` tag followed by a flat json (that is, a json with only top level, simple entries). If a `friendly_json` tag will be found every entry will be used as attribute in the exported Prometheus instance. No compliance check will be done. Also, numbers will be converted to strings (as it's expected for a Prometheus attribute).
For example this is how you edit your WireGuard configuration file:
@ -197,7 +215,7 @@ As you can see, all you need to do is to add the friendly name in the comments p
This is a sample of the label split mode:
```
```ebnf
# HELP wireguard_sent_bytes_total Bytes sent to the peer
# TYPE wireguard_sent_bytes_total counter
wireguard_sent_bytes_total{interface="wg0",public_key="2S7mA0vEMethCNQrJpJKE81/JmhgtB+tHHLYQhgM6kk=",allowed_ip_0="10.70.0.2",allowed_subnet_0="32",allowed_ip_1="10.70.0.66",allowed_subnet_1="32",friendly_name="OnePlus 6T"} 3208804
@ -231,7 +249,7 @@ wireguard_latest_handshake_seconds{interface="wg0",public_key="wTjv6hS6fKfNK+SzO
Now add the exporter to the Prometheus exporters as usual. I recommend to start it as a service. It's necessary to run it as root (if there is a non-root way to call `wg show all dump` please let me know). My systemd service file is like this one:
```
```ini
[Unit]
Description=Prometheus WireGuard Exporter
Wants=network-online.target