{"id":13606602,"url":"https://github.com/jamescun/wg-api","last_synced_at":"2025-04-10T22:49:06.116Z","repository":{"id":48876480,"uuid":"241939512","full_name":"jamescun/wg-api","owner":"jamescun","description":"WG-API is a JSON-RPC Server for WireGuard","archived":false,"fork":false,"pushed_at":"2023-10-25T07:50:14.000Z","size":47,"stargazers_count":152,"open_issues_count":7,"forks_count":21,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-10T22:48:52.899Z","etag":null,"topics":["api","json-rpc","linux","networking","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/jamescun.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,"dei":null}},"created_at":"2020-02-20T16:56:24.000Z","updated_at":"2025-04-08T17:49:26.000Z","dependencies_parsed_at":"2024-04-09T23:48:36.200Z","dependency_job_id":"874e2133-5737-4c4f-9a55-700a86890730","html_url":"https://github.com/jamescun/wg-api","commit_stats":null,"previous_names":["jamescun/wireguard-api"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamescun%2Fwg-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamescun%2Fwg-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamescun%2Fwg-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamescun%2Fwg-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamescun","download_url":"https://codeload.github.com/jamescun/wg-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312191,"owners_count":21082637,"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":["api","json-rpc","linux","networking","wireguard"],"created_at":"2024-08-01T19:01:10.588Z","updated_at":"2025-04-10T22:49:06.092Z","avatar_url":"https://github.com/jamescun.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# WG-API 🔐\n\nWG-API presents a JSON-RPC interface on top of a WireGuard network interface.\n\n* 💖 **Add/Remove Peers**\n  Modify known peers without reloading\n\n* 📈 **Statistics**\n  View data usage and allowed IPs of all peers\n\n* 📞 **JSON-RPC 2.0 API**\n  No custom client integrations required, standard API accepted everywhere.\n\n**NOTE:** WG-API is currently only compatible with the WireGuard Linux kernel module and userland wireguard-go. It does not currently work with the MacOS NetworkExtension.\n\n\n## Getting WG-API\n\n### Pre-Built Binary\n\nBinaries for Linux are available [here](https://github.com/jamescun/wg-api/releases).\n\n### Build Yourself\n\nWG-API requires at least Go 1.17.\n\n```sh\ngo install github.com/jamescun/wg-api\n```\n\nThis should install the server binary `wg-api` in your $GOPATH/bin.\n\n### Docker\n\nWG-API can also be run inside a Docker container, however the container will need to existing within the same network namespace as the host and have network administrator capability (CAP_NET_ADMIN) to be able to control the WireGuard interface.\n\n```sh\ndocker run --name=wg-api -d -p 8080:8080 --network host --cap-add NET_ADMIN james/wg-api:latest --device=\u003cmy device\u003e\n```\n\nThe Docker container now supports Linux on AMD64, ARM64 and ARMv7 architectures.\n\n## Configuring WG-API\n\nWG is configured using command line arguments:\n\n```sh\n$ wg-api --help\nWG-API presents a JSON-RPC API to a WireGuard device\nUsage: wg-api [options]\n\nHelpers:\n  --list-devices  list wireguard devices on this system and their name to be\n                  given to --device\n  --version       display the version number of WG-API\n\nOptions:\n  --device=\u003cname\u003e         (required) name of WireGuard device to manager\n  --listen=\u003c[host:]port\u003e  address where API server will bind\n                          (default localhost:8080)\n  --tls                   enable Transport Layer Security (SSL) on server\n  --tls-key               TLS private key\n  --tks-cert              TLS certificate file\n  --tls-client-ca         enable mutual TLS authentication (mTLS) of the client\n  --token                 opaque value provided by the client to authenticate\n                          requests. may be specified multiple times.\n\nEnvironment Variables:\n  WGAPI_TOKENS  comma seperated list of authentication tokens, equivalent to\n                calling --token one or more times.\n\nWarnings:\n  WG-API can perform sensitive network operations, as such it should not be\n  publicly exposed. It should be bound to the local interface only, or\n  failing that, be behind an authenticating proxy or have mTLS enabled.\n  Additionally authentication tokens should be configured.\n```\n\nThe only required argument is `--device`, which tells WG-API which WireGuard device to control. To control multiple WireGuard devices, launch multiple instances of WG-API.\n\nBy default, this launches WG-API on `localhost:8080` which may conflict with the typical development environment. To bind it elsewhere, use `--listen`:\n\n```sh\n$ wg-api --device=\u003cmy device\u003e --listen=localhost:1234\n```\n\n**NOTE:** `--listen` will not prevent you from binding the server to a public interface. Care should be taken to prevent public access to the WG-API server; such as binding it only to a local interface, enabling auth tokens, placing an authenticating reverse proxy in-front of it or using mTLS (detailed below).\n\nAuthentication tokens can be provided either on the command line or via an environment variable. `--token` may be specified multiple times, or a comma-seperated list may be provided with the `WGAPI_TOKENS` environment variable. Environment variables are preferred as the token may be visible from process lists when using the command line `--token`.\n\n```sh\n$ WGAPI_TOKENS=\u003crandom string\u003e wg-api --device=\u003cmy device\u003e\n```\n\nThen provided as part of the HTTP exchange in the HTTP `Authorization` header as the `Token` scheme.\n\n```sh\n$ curl http://localhost:8080 -H \"Authorization: Token \u003crandom string\u003e\" ...\n```\n\n```\nPOST / HTTP/1.1\nHost: localhost:8080\nAuthorization: Token \u003crandom string\u003e\nContent-Type: application/json\n```\n\nWG-API can optional listen using TLS and HTTP/2. To enable TLS, you will also need a TLS Certificate and matching private key.\n\n```sh\n$ wg-api --device=\u003cmy device\u003e --tls --tls-key=key.pem --tls-cert=cert.pem\n```\n\nAnd optionally WG-API can request and validate client certificates to implement TLS Mutual Authentication (mTLS):\n\n```sh\n$ wg-api --device=\u003cmy device\u003e --tls --tls-key=key.pem --tls-cert=cert.pem --tls-client-ca=clientca.pem\n```\n\n\n## Using WG-API\n\nWG-API exposes a JSON-RPC 2.0 API with five methods.\n\nAll calls are made using the POST method, and require the `Content-Type` header to be set to `application/json`. The server ignores the URL path it is given, allowing the server to be mounted under another hierarchy in a reverse proxy.\n\nThe structures expected by the server can be found in [client/client.go](client/client.go).\n\nAuthentication may optionally be configured. This is supplied via the `Authorization` header as the `Token` scheme. See [Configuring WG-API](##Configuring-WG-API) for an example.\n\n\n### GetDeviceInfo\n\nGetDeviceInfo returns information such as the public key and type of interface for the currently configured device.\n\n```sh\ncurl http://localhost:8080 -H \"Content-Type: application/json\" -d '{\"jsonrpc\": \"2.0\", \"method\": \"GetDeviceInfo\", \"params\": {}}'\n```\n\n#### Example Response\n\n```json\n{\n  \"device\": {\n    \"name\": \"wg0\",\n    \"type\": \"Linux kernel\",\n    \"public_key\": \"xoY2MZZ1UmbEakFBPyqryHwTaMi6ae4myP+vuILmJUY=\",\n    \"listen_port\": 51820,\n    \"num_peers\": 13\n  }\n}\n```\n\n\n### ListPeers\n\nListPeers retrieves information about all Peers known to the current WireGuard interface, including allowed IP addresses and usage stats, optionally with pagination.\n\n```sh\ncurl http://localhost:8080 -H \"Content-Type: application/json\" -d '{\"jsonrpc\": \"2.0\", \"method\": \"ListPeers\", \"params\": {}}'\n```\n\n#### Example Response\n\n```json\n{\n  \"peers\": [\n    {\n      \"public_key\": \"xoY2MZZ1UmbEakFBPyqryHwTaMi6ae4myP+vuILmJUY=\",\n      \"has_preshared_key\": false,\n      \"endpoint\": \"67.234.65.104:57436\",\n      \"last_handshake\": \"2020-02-20T16:35:12Z\",\n      \"receive_bytes\": 834854756,\n      \"transmit_bytes\": 3883746,\n      \"allowed_ips\": [\n        \"10.1.1.0/24\"\n      ],\n      \"protocol_version\": 1\n    },\n    ...\n  ]\n}\n```\n\n\n### GetPeer\n\nGetPeer retrieves a specific Peer by their public key.\n\n```sh\ncurl http://localhost:8080 -H \"Content-Type: application/json\" -d '{\"jsonrpc\": \"2.0\", \"method\": \"GetPeer\", \"params\": {\"public_key\": \"xoY2MZZ1UmbEakFBPyqryHwTaMi6ae4myP+vuILmJUY=\"}}'\n```\n\n#### Example Response\n\n```json\n{\n  \"peer\": {\n    \"public_key\": \"xoY2MZZ1UmbEakFBPyqryHwTaMi6ae4myP+vuILmJUY=\",\n    \"has_preshared_key\": false,\n    \"endpoint\": \"67.234.65.104:57436\",\n    \"last_handshake\": \"2020-02-20T16:35:12Z\",\n    \"receive_bytes\": 834854756,\n    \"transmit_bytes\": 3883746,\n    \"allowed_ips\": [\n      \"10.1.1.0/24\"\n    ],\n    \"protocol_version\": 1\n  }\n}\n```\n\n\n### AddPeer\n\nAddPeer inserts a new Peer into the WireGuard interfaces table, multiple calls to AddPeer can be used to update details of the Peer.\n\n```sh\ncurl http://localhost:8080 -H \"Content-Type: application/json\" -d '{\"jsonrpc\": \"2.0\", \"method\": \"AddPeer\", \"params\": {\"public_key\": \"xoY2MZZ1UmbEakFBPyqryHwTaMi6ae4myP+vuILmJUY=\",\"allowed_ips\": [ \"10.1.1.0/24\" ]}}'\n```\n\n\n### RemovePeer\n\nRemovePeer deletes a Peer from the WireGuard interfaces table by their public key,\n\n```sh\ncurl http://localhost:8080 -H \"Content-Type: application/json\" -d '{\"jsonrpc\": \"2.0\", \"method\": \"RemovePeer\", \"params\": {\"public_key\": \"xoY2MZZ1UmbEakFBPyqryHwTaMi6ae4myP+vuILmJUY=\"}}'\n```\n\n## Thanks\n\nWith many thanks to:\n\n  - [Jason A. Donenfeld](https://github.com/zx2c4)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamescun%2Fwg-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamescun%2Fwg-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamescun%2Fwg-api/lists"}