From 990495c7a3c1307c41df020ca1953a612efaba5e Mon Sep 17 00:00:00 2001 From: pufferffish Date: Fri, 12 Apr 2024 05:18:54 +0100 Subject: [PATCH] Add documentation for --info --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 03522f8..41cf48e 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,8 @@ of wireproxy by [@juev](https://github.com/juev). ``` usage: wireproxy [-h|--help] [-c|--config ""] [-s|--silent] - [-d|--daemon] [-v|--version] [-n|--configtest] + [-d|--daemon] [-i|--info ""] [-v|--version] + [-n|--configtest] Userspace wireguard client for proxying @@ -48,9 +49,11 @@ Arguments: -c --config Path of configuration file -s --silent Silent mode -d --daemon Make wireproxy run in background + -i --info Specify the address and port for exposing health status -v --version Print version -n --configtest Configtest mode. Only check the configuration file for validity. + ``` # Build instruction @@ -188,6 +191,63 @@ PublicKey = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY= AllowedIPs = 10.254.254.100/32 # Note there is no Endpoint defined here. ``` +# Health endpoint +Wireproxy supports exposing a health endpoint for monitoring purposes. +The argument `--info/-i` specifies an address and port (e.g. `localhost:9080`), which exposes a HTTP server that provides health status metric of the server. + +Currently two endpoints are implemented: +`/metrics`: Exposes information of the wireguard daemon, this provides the same information you would get with `wg show`. [This](https://www.wireguard.com/xplatform/#example-dialog) shows an example of what the response would look like. + +`/readyz`: This responds with a json which shows the last time a pong is received from an IP specified with `CheckAlive`. When `CheckAlive` is set, a ping is sent out to addresses in `CheckAlive` per `CheckAliveInterval` seconds (defaults to 5) via wireguard. If a pong has not been received from one of the addresses within the last `CheckAliveInterval` seconds (+2 seconds for some leeway to account for latency), then it would respond with a 503, otherwise a 200. + +For example: +``` +[Interface] +PrivateKey = censored +Address = 10.2.0.2/32 +DNS = 10.2.0.1 +CheckAlive = 1.1.1.1, 3.3.3.3 +CheckAliveInterval = 3 + +[Peer] +PublicKey = censored +AllowedIPs = 0.0.0.0/0 +Endpoint = 149.34.244.174:51820 + +[Socks5] +BindAddress = 127.0.0.1:25344 +``` +`/readyz` would respond with +``` +< HTTP/1.1 503 Service Unavailable +< Date: Thu, 11 Apr 2024 00:54:59 GMT +< Content-Length: 35 +< Content-Type: text/plain; charset=utf-8 +< +{"1.1.1.1":1712796899,"3.3.3.3":0} +``` + +And for: +``` +[Interface] +PrivateKey = censored +Address = 10.2.0.2/32 +DNS = 10.2.0.1 +CheckAlive = 1.1.1.1 +``` +`/readyz` would respond with +``` +< HTTP/1.1 200 OK +< Date: Thu, 11 Apr 2024 00:56:21 GMT +< Content-Length: 23 +< Content-Type: text/plain; charset=utf-8 +< +{"1.1.1.1":1712796979} +``` + +If nothing is set for `CheckAlive`, an empty JSON object with 200 will be the response. + +The peer which the ICMP ping packet is routed to depends on the `AllowedIPs` set for each peers. # Stargazers over time [![Stargazers over time](https://starchart.cc/octeep/wireproxy.svg)](https://starchart.cc/octeep/wireproxy)