From 55aaaa3a78dc79bee8c2cda17fb8569b5a8c4f47 Mon Sep 17 00:00:00 2001 From: Daniel Redetzke Date: Sat, 3 Oct 2026 20:14:38 +0300 Subject: [PATCH] Prepare README for public release and add MIT license --- LICENSE | 21 +++++++++++++++++++ README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 72 insertions(+), 11 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2d98136 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Daniel Redetzke + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b221b32..0ce453d 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,52 @@ # GHOSTWIRE -A small WireGuard server manager: one Go binary with a web interface and a JSON -API (also meant for a future iOS app). It configures the WireGuard server, -manages peers (add, change, disable, remove) and records traffic per peer. +**ゴーストワイヤー** · A self-hosted WireGuard server manager in a single Go +binary, with a web interface, a JSON API and a native iPhone app. -- **State:** everything lives in `config.json`. The kernel is reconciled to it, - so there is no `/etc/wireguard`, no `wg-quick` and no `wireguard-tools`. +GHOSTWIRE sets up the WireGuard server, manages peers (add, change, disable, +remove), hands out client configs as a download or QR code, and records traffic +and connection history per peer. There are no install scripts and no +dependencies on the server: the binary installs, updates and removes itself. + +## Features + +- **One file of state:** everything lives in `config.json`. The kernel is + reconciled to it, so there is no `/etc/wireguard`, no `wg-quick` and no + `wireguard-tools`. - **Kernel access:** netlink creates `wg0` and sets its addresses and MTU; wgctrl sets keys and peers; nftables holds the rules in its own `inet GHOSTWIRE` table. - **Live peer changes:** only peers that changed are touched, the same effect as `wg syncconf`, so connected peers stay connected. -- **Logs:** written to `GHOSTWIRE.jsonl`, rotated at 10 MB with 5 old files kept by default (Settings → Data retention). -- **Traffic history:** kept in `stats.json`: hourly for 48 h and daily for 400 days by default (Settings → Data retention). -- **Connection history:** every online session per peer, with start, duration, address and traffic. A new session starts when a device changes networks. Country and network operator come from the free [DB-IP Lite](https://db-ip.com) databases (CC BY 4.0). GHOSTWIRE downloads them monthly (about 20 MB) and looks addresses up locally, so peer addresses never leave the server. You can switch this off under Settings → Data retention. +- **IPv4 and IPv6:** IPv6 inside the tunnel is turned on automatically when the + server has a global IPv6 address. +- **Traffic history:** kept in `stats.json`, hourly for 48 h and daily for + 400 days by default (Settings → Data retention). +- **Connection history:** every online session per peer, with start, duration, + address and traffic. A new session starts when a device changes networks. + Country and network operator come from the free + [DB-IP Lite](https://db-ip.com) databases (CC BY 4.0). GHOSTWIRE downloads + them monthly (about 20 MB) and looks addresses up locally, so peer addresses + never leave the server. You can switch this off under Settings → Data + retention. +- **Logs:** written to `GHOSTWIRE.jsonl`, rotated at 10 MB with 5 old files + kept by default. Changes are marked as audit entries. +- **HTTPS built in:** Let's Encrypt, a self-signed certificate, your own + certificate files, or plain HTTP behind a reverse proxy. + +## Security + - **Client private keys are never stored.** A config is shown once, as a download or QR code. "Issue new config" makes new keys. +- **The service is not root.** It runs as user `ghostwire` with only + `CAP_NET_ADMIN` and `CAP_NET_BIND_SERVICE`, and can write only to + `/opt/ghostwire`. +- **Sign-in:** one admin account. The password is stored as an argon2id hash. + After 5 failed attempts, sign-in is locked for 15 minutes. Sessions use an + HttpOnly, SameSite=Strict cookie and last 12 hours by default. +- **API tokens** are stored only as hashes and can be read-only or full access. +- `config.json` holds the server private key and is readable only by the + service (0600). ## Requirements @@ -25,6 +56,9 @@ manages peers (add, change, disable, remove) and records traffic per peer. ## Build +Building needs Go 1.27 or newer. The binaries are static (no cgo), so they run +on any Linux distribution. + ```sh make linux-amd64 # dist/amd64/GHOSTWIRE make linux-arm64 # dist/arm64/GHOSTWIRE (Raspberry Pi 64-bit, ARM servers) @@ -59,9 +93,8 @@ later in the web interface or with `-endpoint`. Running it again is safe: steps that are already done are skipped. -The service runs as user `ghostwire` with only `CAP_NET_ADMIN` and -`CAP_NET_BIND_SERVICE`, and can write only to `/opt/ghostwire`. Root is needed -only for the commands below, never for the running service. +Then open `https://vpn.example.net` and sign in as `admin`. Root is needed only +for the commands below, never for the running service. ## Commands (as root) @@ -168,3 +201,10 @@ password first: ```sh make build && mkdir -p dev && ./GHOSTWIRE -config dev/config.json -passwd ``` + +## License + +GHOSTWIRE is released under the [MIT License](LICENSE). + +The DB-IP Lite databases it downloads are by [DB-IP](https://db-ip.com) and +licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).