{"id":13492308,"url":"https://github.com/apognu/wgctl","last_synced_at":"2025-03-28T09:34:14.100Z","repository":{"id":144202497,"uuid":"144188659","full_name":"apognu/wgctl","owner":"apognu","description":"Utility to configure and manage your WireGuard tunnels","archived":false,"fork":false,"pushed_at":"2023-03-06T23:26:14.000Z","size":167,"stargazers_count":64,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-31T06:34:54.734Z","etag":null,"topics":["golang","linux","netlink","vpn","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apognu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-08-09T18:19:24.000Z","updated_at":"2024-08-19T01:30:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"0d99e3a9-ff2b-4c59-8eca-87f9536f7608","html_url":"https://github.com/apognu/wgctl","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apognu%2Fwgctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apognu%2Fwgctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apognu%2Fwgctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apognu%2Fwgctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apognu","download_url":"https://codeload.github.com/apognu/wgctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246004477,"owners_count":20708223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","linux","netlink","vpn","wireguard"],"created_at":"2024-07-31T19:01:04.850Z","updated_at":"2025-03-28T09:34:13.739Z","avatar_url":"https://github.com/apognu.png","language":"Go","readme":"# wgctl - WireGuard control utility\n\n[![CI Status](https://img.shields.io/travis/apognu/wgctl/master.svg?style=flat-square)](https://travis-ci.org/apognu/wgctl)\n[![Coverage Status](https://img.shields.io/coveralls/apognu/wgctl/master.svg?style=flat-square)](https://coveralls.io/github/apognu/wgctl?branch=master)\n\nThis is a personal project to allow WireGuard to be configured through the use of YAML files. It uses Netlink (through [wgctrl](https://golang.zx2c4.com/wireguard/wgctrl)) under the hood for all interaction with the system.\n\nThis tool is very opinionated and designed for my own use (working on that), it _might_ not be what you're looking for.\n\nThe configuration file should look like this (if you are using \u003c= 1.0.0, please see [this README](https://github.com/apognu/wgctl/blob/v1.0.0/README.md)):\n\n```yaml\ndescription: Personal VPN server #1\nprivate_key: /etc/wireguard/vpn1.key\npeers:\n  - description: Local laptop\n    address: 192.168.0.1/32\n    listen_port: 42000\n    public_key: BooRta+d0t/2djkdZ3xfe/5xndKvPtfqH3pdZcdZ2TY=\n    preshared_key: e16f1596201850fd4a63680b27f603cb64e67176159be3d8ed78a4403fdb1700\n    fwmark: 1024\n    routes: false\n    post_up:\n      - [ '/usr/bin/notify-send', 'WireGuard tunnel went up', 'A WireGuard tunnel was just brought up. Congrats.' ]\n    pre_down:\n      - [ '/usr/bin/notify-send', 'WireGuard tunnel went down', 'A WireGuard tunnel was just torn down. Congrats.' ]\n  - description: VPN gateway at provider X\n    address: 192.168.0.2/32\n    listen_port: 42000\n    public_key: cyfBMbaJ6kgnDYjio6xqWikvTz2HvpmvSQocRmF/ZD4=\n    preshared_key: e16f1596201850fd4a63680b27f603cb64e67176159be3d8ed78a4403fdb1700\n    endpoint: 1.2.3.4:42000\n    keepalive_interval: 10s\n    allowed_ips:\n      - 192.168.0.0/30\n      - 0.0.0.0/0\n```\n\nBy default, ```wgctl``` will look for its configuration files under ```/etc/wireguard``` (as ```/etc/wireguard/\u003cid\u003e.yml```). This can be overriden by giving it a filesystem path instead of an identifier. You can alsow set the directory where ```wgctl``` looks for its configuration by settings the environment variable ```WGCTL_CONFIG_PATH```.\n\nThe ```post_up``` and ```pre_down``` directives take an array of arrays of commands to execute during the tunnel lifecycle events. You must use an absolute path to target the command you want to invoke.\n\nKeep in mind that in order to put IPv6 addresses in the configuration, you'll need to coerce the value to a string with quotes :\n\n```yaml\npeers:\n  - endpoint: '[cafe:1:2:3::1]:10000'\n```\n\nThe configuration is built so as to be able to be copied on all peers identically, the current node is detected when a peer public key matches the private key at the root of the file.\n\n## Build\n\n```shell\n$ go get -u github.com/apognu/wgctl\n```\n\nor\n\n```shell\n$ git clone https://github.com/apognu/wgctl.git \u0026\u0026 cd wgctl\n$ dep ensure\n$ go build .\n```\n\nYou can, of course, get a prebuilt binary from the [Releases](https://github.com/apognu/wgctl/releases) section.\n\n### Testing\n\nYou can run the tests for this project, as root (since we are testing netlink communication and device creation). Keep in mind that this will modify properties on your live system (devices, routes, /proc settings, etc.), so use with caution.\n\n```shell\n$ sudo -E go test ./... \n```\n\n## Usage\n\n```shell\n$ wgctl help\nusage: wgctl [\u003cflags\u003e] \u003ccommand\u003e [\u003cargs\u003e ...]\n\nWireGuard control plane helper\n\nFlags:\n  -h, --help  Show context-sensitive help (also try --help-long and --help-man).\n\nCommands:\n  help [\u003ccommand\u003e...]\n  start [\u003cflags\u003e] \u003cinstance\u003e\n  stop \u003cinstance\u003e\n  restart [\u003cflags\u003e] \u003cinstance\u003e\n  status [\u003cflags\u003e] [\u003cinstance\u003e]\n  info \u003cinstance\u003e\n  set \u003cinstance\u003e [\u003csettings\u003e...]\n  peer\n    set \u003cinstance\u003e \u003cpeer\u003e...\n    replace \u003cinstance\u003e \u003cpeer\u003e...\n  key\n    private\n    public\n    psk\n  version\n```\n\n### Control the state of tunnels\n\n```shell\n$ wgctl start -f vpn\n$ wgctl start vpn\n$ wgctl stop vpn\n$ wgctl restart vpn\n```\n\n### Obtain the state of all configured or active tunnels\n\nThe ```-s``` option only displays the name of active tunnels, for ease of use in scripts.\n\n```\n$ wgctl status\n[↓] tunnel 'vpn1' is down\n[↑] tunnel 'vpn2' is up and running\n[↓] tunnel 'corporate' is down\n[↓] tunnel 'personal' is up and running\n\n$ wgctl status -s\nvpn2\npersonal\n\n$ wgctl status vpn1\n[↓] tunnel 'vpn1' is down\n```\n\n### Get configuration and runtime details for an active tunnel\n\n```shell\n$ wgctl info vpn2\ntunnel: \n  interface: Personal VPN tunnel #2\n  public key: SqtWXnIGoHWibfqZwAe6iFc560wWuV6zUL+4CqzDxlQ=\n  port: 51822\n  fwmark: 12548\n  peer: VPN gateway\n    public key: /7vJFkiTPPTznPvey4Z4+xn+HRGlT/X3hv1o4+kS7FQ=\n    endpoint: 4.3.2.1:10000\n    allowed ips: 192.168.0.1/30, 0.0.0.0/0\n    transfer: ↓ 0 ↑ 0\n```\n\n### Change tunnel configuration on the fly\n\nThose changes are not persisted, if you want to export the current configuration of a tunnel, use ```export``` below. Please note that you can provide a subset of the options shown below.\n\n```shell\n# Change properties on the interface itself\n$ wgctl set vpn1 privkey=/etc/wireguard/new.key port=43210 fwmark=1437\n\n# Add a new peer or change the properties of the peer with the given public key\n$ wgctl peer set vpn1 pubkey=sSg9kL+KsMBQpFPO+TXl7A4OKjLb0xWORx7eR3JDjXM= endpoint=192.168.255.254:10000 allowedips=2.2.2.2/24,3.3.3.3/30 keepalive=20 psk=636493c476092bf06806794d6c2d62c990c68a39b71b73019a328a4d646d9e42\n\n# Replace the whole set of peers with the given one\n$ wgctl peer replace vpn1 pubkey=sSg9kL+KsMBQpFPO+TXl7A4OKjLb0xWORx7eR3JDjXM= endpoint=192.168.255.254:10000 allowedips=2.2.2.2/24,3.3.3.3/30 keepalive=20 psk=636493c476092bf06806794d6c2d62c990c68a39b71b73019a328a4d646d9e42\n```\n\n### Export the configuration of a tunnel\n\nYou can export the current configuration of an active tunnel by using the ```wgctl export``` command. If a ```wgctl``` configuration already exists, non-WireGuard properties (descriptions, hooks, etc.) will be merged with the running config. If not, the default values will be used.\n\nPlease note that if the tunnel was not created through ```wgctl```, the private key path will be left blank.\n\n```shell\n$ wgctl export vpn1\ninterface:\n  description: Personal VPN server #1\n  address: 192.168.0.1/32\n  listen_port: 42000\n  private_key: /path/to/private.key\n  routes: false\n  post_up:\n    - [ '/usr/bin/notify-send', 'WireGuard tunnel went up', 'A WireGuard tunnel was just brought up. Congrats.' ]\n  pre_down:\n    - [ '/usr/bin/notify-send', 'WireGuard tunnel went down', 'A WireGuard tunnel was just torn down. Congrats.' ]\npeers:\n  - description: VPN gateway at provider X\n    public_key: cyfBMbaJ6kgnDYjio6xqWikvTz2HvpmvSQocRmF/ZD4=\n    preshared_key: e16f1596201850fd4a63680b27f603cb64e67176159be3d8ed78a4403fdb1700\n    endpoint: 1.2.3.4:42000\n    keepalive_interval: 10s\n    allowed_ips:\n      - 192.168.0.0/30\n      - 0.0.0.0/0\n```\n\n### Generate keys to be used by WireGuard\n\n```shell\n$ wgctl key private\nnAyxQotWfano6/cC9S6fjSRYe9oQ0/GQn2mK9/PXvyg=\n$ wgctl key private | wgctl key public\nOtvPEAa2d3PP0qAT9bm7zxdTLa6i6w2wNrCdziI76Hg=\n$ wgctl key psk\nd9c966f0cf2320d4e67d543e0a0cd3856fc0f065392799fff8e040bed51b3176\n```\n\n## Routes and firewall\n\nBy default, ```wgctl``` will add routes matching your allowed IP addresses in order to traffic to be routed through your VPN. Similarly to ```wg-quick```, il will set up any default routes to route all your traffic (with the ```fwmark``` technique).\n\nIf you want to manage the routing yourself, you can pass ```--no-routes``` to ```wgctl start``` and ```wgctl restart``` to prevent that behavior. You can also set the ```interface``` directive ```routes``` to ```false``` to disable this behavior permanently.\n\n```wgctl``` will not touch your firewall rules, if you need to open a port or add specific rules, you'll need to do it yourself manually, or use a ```post_up``` directive.\n\n## Use as a service\n\nYou can tell `wgctl` to stay in the foreground by starting your tunnel with the `-f` flag. This allows you to start up your tunnels as daemons with, for example, this `systemd` service unit:\n\n```shell\n$ cat /etc/systemd/system/wgctl@.service\n[Unit]\nDescription=Wireguard tunnel\n\n[Service]\nType=simple\nRestart=always\nWorkingDirectory=/etc/wireguard\nExecStart=/usr/local/bin/wgctl start -f %i\nExecStopPost=-/usr/local/bin/wgctl stop %i\n\n[Install]\nWantedBy=multi-user.target\n```\n","funding_links":[],"categories":["Go","Projects"],"sub_categories":["User Interface"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapognu%2Fwgctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapognu%2Fwgctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapognu%2Fwgctl/lists"}