# wgtrack
"wgtrack" tracks WireGuard links, exports the links' status, and updates endpoints as needed.
WireGuard is a great VPN solution. wgtrack provides the tooling around it to track the status of the links and export the data for monitoring solutions. It also re-resolves endpoint hostnames to thus support connections between dial-in peers with changing IP addresses.
Note: This is code in "works for me" quality but in use for quite some time now. This tool started as an exercise in using Python's asyncio library.
---
## Installation
wgtrack can be installed easily on Linux:
- Make sure that you use Python version 3.5 or newer
- Install wgtrack from PyPi
```shell
$ pip install wgtrack
```
- Configure wgtrack using /etc/wgtrack.conf
- Configure wgtrack to run as a service as needed
### Clone (for developers only)
Clone this repo to your local machine using `https://github.com/towalink/wgtrack.git`
---
## Features
- Checks the status of WireGuard links based on heartbeat success
- Optionally ping the remote peers regularly to check the tunnels
- Export the status of WireGuard links (eg. attributes like tx/rx counters) for use by monitoring applications (currently: Telegraf)
- Re-resolve the endpoint in case of tunnel failure to thus support endpoints with changing IP addresses (can be used for "UDP Hole Punching" in NAT scenarios, tested with FritzBox routers)
- Fine-granular control of timers to avoid unnecessary traffic and DNS requests.
## Usage
- Basic usage
> Start wgtrack using the config file /etc/wgtrack.conf:
```shell
$ python -m wgtrack
```
- You may specify some command line parameters as needed
> Alternative config file:
```shell
$ python -m wgtrack --config /etc/my_special_wgtrack.conf
```
- Configure the level of detail of logging information
```shell
$ python -m wgtrack --loglevel debug
```
- Show help page for details on command line arguments
```shell
$ python -m wgtrack --help
```
## Documentation
After initialization (1), this tool periodically queries the status (2) of the WireGuard links, acts on their peers' status (3), and outputs the status (4) as requested.
### (1) Initialization
The wgtrack configuration file and also the WireGuard configuration files in "/etc/wireguard" are read. Based on this, the tool knows about all configured WireGuard interfaces and their peers (including configured endpoint hostnames). In case of a change of the configuration, wgtrack may be notified by a SIGHUP signal to redo this initialization step.
The wgtrack configuration file uses the ini format. General parameters are specified in the "[general]" section. Parameters that shall be applied to all sections are specified in the "[DEFAULT]" section. Parameters for individual interfaces are specified in sections named "[interface:<ifname>]" with "<ifname>" being the name of the interface. Parameters for individual outputs are specified in sections named "[output:<outputname>]" with "<outputname>" being the name of the output.
### (2) Periodic queries
wgtrack periodically queries the status of the WireGuard interfaces and their peers. This is done using the "wg show all dump" command.
How often this is done can be configured using the "cycle_time" parameter (default: 30s).
In case the heartbeat of a link to a peer shows usual times that indicate a working link, the link can be checked using echo requests. By default, this is done each "cycle_time" (default "ping_interval" is 1 for this). It can be disabled by setting "ping_interval" to 0. After the configured number of failed echo requests ("ping_failafternum", default 2), the link is considered down despite the heartbeat appearing ok.
The first "allowed-ip" configured for the respective peer is used as the destination for the respective echo request.
### (3) Act on peer status
If a link is considered down, its peer endpoint can be re-resolved. Before this is done, the tool waits for the configured number of periods ("cycles_wait", default 2) to wait for an Internet connection with a dynamic IP address to be reestablished after disconnection. After that, the endpoint is re-resolved "cycles_checking" times each multitude "cycles_checkperiod" of the "cycle_time". After that, an exponential back-off takes place. However, "cycles_slowcheckingperiod" (default 20) defines the longest interval (as a multitude of the "cycle_time" until a regular recheck is done.
### (4) Output the interface and peer status
Outputs for the status information can be configured. Currently, the wire protocol of InfluxDB is supported as output format. This format is used by "Telegraf".
Add the following in your wgtrack.ini to enable output in the Influx wire format:
```
[output:influx]
```
In the Telegraf config, something like the following needs to be added:
```
[[inputs.file]]
files = ["/var/cache/wg-track_influx.out"]
```
---
## License
[](https://opensource.org/licenses/AGPL-3.0)
- **[AGPL3 license](https://opensource.org/licenses/AGPL-3.0)**
- Copyright 2020-2022 © <a href="https://www.towalink.net" target="_blank">Dirk Henrici</a>.
Raw data
{
"_id": null,
"home_page": "https://www.towalink.net",
"name": "wgtrack",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "WireGuard monitoring Towalink VPN dyndns NAT-traversal",
"author": "The Towalink Project",
"author_email": "pypi.wgtrack@towalink.net",
"download_url": "https://files.pythonhosted.org/packages/ad/52/821f8533ae85daf8a4181f6115b8faa660a79724f073a7a9a43fbeda02ef/wgtrack-0.1.11.tar.gz",
"platform": null,
"description": "# wgtrack\n\n\"wgtrack\" tracks WireGuard links, exports the links' status, and updates endpoints as needed.\n\nWireGuard is a great VPN solution. wgtrack provides the tooling around it to track the status of the links and export the data for monitoring solutions. It also re-resolves endpoint hostnames to thus support connections between dial-in peers with changing IP addresses.\n\nNote: This is code in \"works for me\" quality but in use for quite some time now. This tool started as an exercise in using Python's asyncio library.\n\n---\n\n## Installation\n\nwgtrack can be installed easily on Linux:\n\n- Make sure that you use Python version 3.5 or newer\n- Install wgtrack from PyPi\n\n```shell\n$ pip install wgtrack\n```\n\n- Configure wgtrack using /etc/wgtrack.conf\n- Configure wgtrack to run as a service as needed\n\n### Clone (for developers only)\n\nClone this repo to your local machine using `https://github.com/towalink/wgtrack.git`\n\n---\n\n## Features\n\n- Checks the status of WireGuard links based on heartbeat success\n- Optionally ping the remote peers regularly to check the tunnels\n- Export the status of WireGuard links (eg. attributes like tx/rx counters) for use by monitoring applications (currently: Telegraf)\n- Re-resolve the endpoint in case of tunnel failure to thus support endpoints with changing IP addresses (can be used for \"UDP Hole Punching\" in NAT scenarios, tested with FritzBox routers)\n- Fine-granular control of timers to avoid unnecessary traffic and DNS requests.\n\n## Usage\n\n- Basic usage\n\n> Start wgtrack using the config file /etc/wgtrack.conf:\n\n```shell\n$ python -m wgtrack\n```\n\n- You may specify some command line parameters as needed\n\n> Alternative config file:\n\n```shell\n$ python -m wgtrack --config /etc/my_special_wgtrack.conf\n```\n- Configure the level of detail of logging information\n\n```shell\n$ python -m wgtrack --loglevel debug\n```\n\n- Show help page for details on command line arguments\n\n```shell\n$ python -m wgtrack --help\n```\n\n## Documentation\n\nAfter initialization (1), this tool periodically queries the status (2) of the WireGuard links, acts on their peers' status (3), and outputs the status (4) as requested.\n\n### (1) Initialization\n\nThe wgtrack configuration file and also the WireGuard configuration files in \"/etc/wireguard\" are read. Based on this, the tool knows about all configured WireGuard interfaces and their peers (including configured endpoint hostnames). In case of a change of the configuration, wgtrack may be notified by a SIGHUP signal to redo this initialization step.\n\nThe wgtrack configuration file uses the ini format. General parameters are specified in the \"[general]\" section. Parameters that shall be applied to all sections are specified in the \"[DEFAULT]\" section. Parameters for individual interfaces are specified in sections named \"[interface:<ifname>]\" with \"<ifname>\" being the name of the interface. Parameters for individual outputs are specified in sections named \"[output:<outputname>]\" with \"<outputname>\" being the name of the output.\n\n### (2) Periodic queries\n\nwgtrack periodically queries the status of the WireGuard interfaces and their peers. This is done using the \"wg show all dump\" command.\nHow often this is done can be configured using the \"cycle_time\" parameter (default: 30s).\n\nIn case the heartbeat of a link to a peer shows usual times that indicate a working link, the link can be checked using echo requests. By default, this is done each \"cycle_time\" (default \"ping_interval\" is 1 for this). It can be disabled by setting \"ping_interval\" to 0. After the configured number of failed echo requests (\"ping_failafternum\", default 2), the link is considered down despite the heartbeat appearing ok.\nThe first \"allowed-ip\" configured for the respective peer is used as the destination for the respective echo request.\n\n### (3) Act on peer status\n\nIf a link is considered down, its peer endpoint can be re-resolved. Before this is done, the tool waits for the configured number of periods (\"cycles_wait\", default 2) to wait for an Internet connection with a dynamic IP address to be reestablished after disconnection. After that, the endpoint is re-resolved \"cycles_checking\" times each multitude \"cycles_checkperiod\" of the \"cycle_time\". After that, an exponential back-off takes place. However, \"cycles_slowcheckingperiod\" (default 20) defines the longest interval (as a multitude of the \"cycle_time\" until a regular recheck is done.\n\n### (4) Output the interface and peer status\n\nOutputs for the status information can be configured. Currently, the wire protocol of InfluxDB is supported as output format. This format is used by \"Telegraf\".\n\nAdd the following in your wgtrack.ini to enable output in the Influx wire format:\n```\n[output:influx]\n```\n\nIn the Telegraf config, something like the following needs to be added:\n```\n[[inputs.file]]\n files = [\"/var/cache/wg-track_influx.out\"]\n```\n\n---\n\n## License\n\n[](https://opensource.org/licenses/AGPL-3.0)\n\n- **[AGPL3 license](https://opensource.org/licenses/AGPL-3.0)**\n- Copyright 2020-2022 \u00a9 <a href=\"https://www.towalink.net\" target=\"_blank\">Dirk Henrici</a>.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "wgtrack tracks WireGuard links, exports the status, and updates endpoints as needed",
"version": "0.1.11",
"split_keywords": [
"wireguard",
"monitoring",
"towalink",
"vpn",
"dyndns",
"nat-traversal"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "1fef0d6240dbf081c161059ac9c77408",
"sha256": "7be7121f0db858f07a5f8077eb34fa22014894936cf82b25deb1497f30d2ef9f"
},
"downloads": -1,
"filename": "wgtrack-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fef0d6240dbf081c161059ac9c77408",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 32746,
"upload_time": "2022-12-27T18:53:22",
"upload_time_iso_8601": "2022-12-27T18:53:22.199493Z",
"url": "https://files.pythonhosted.org/packages/0b/79/70b3d1711ab771fb36fdf51947509f86e7c093d6ea2f6f7f3e6b29a82dc1/wgtrack-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "a8be9f15c35e440139a8c706dac354e8",
"sha256": "db2c3495cb60123e70d5e9c69c4dda6c530f705725181161a566a3a199b21b08"
},
"downloads": -1,
"filename": "wgtrack-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "a8be9f15c35e440139a8c706dac354e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 30911,
"upload_time": "2022-12-27T18:53:32",
"upload_time_iso_8601": "2022-12-27T18:53:32.711764Z",
"url": "https://files.pythonhosted.org/packages/ad/52/821f8533ae85daf8a4181f6115b8faa660a79724f073a7a9a43fbeda02ef/wgtrack-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-27 18:53:32",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "wgtrack"
}
JSON