From 007eb357d28862856df02e2e3adeb75c78a19852 Mon Sep 17 00:00:00 2001
From: Cloud9 GF4 wgapi <c9@gitea.gf4>
Date: Sat, 23 Oct 2021 19:34:43 -0600
Subject: [PATCH] #9 Improved README

---
 README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 84 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 8919570..7a0b220 100644
--- a/README.md
+++ b/README.md
@@ -4,53 +4,118 @@
 
 ## Installation
 
-### Docker
+### with Docker
 
-Install docker and docker-compose.  Then create a project directory and pull the `docker-compose.yml` file
+Install docker and docker-compose.  Then create a project directory and pull the sample environment files.  
 
-```
-$ sudo mkdir /srv/wgapi
-$ cd /srv/wgapi
-$ sudo wget https://gitea.gf4.pw/gf4/wgapi/raw/branch/master/docker-compose.yml
+```sh
+sudo mkdir /srv/wgapi
+cd /srv/wgapi
+sudo wget 'https://gitea.gf4.pw/gf4/wgapi/raw/branch/master/docker-compose.yml.sample'
+sudo wget 'https://gitea.gf4.pw/gf4/wgapi/raw/branch/master/env.json.sample'
+sudo cp docker-compose.yml.sample docker-compose.yml
+sudo cp env.json.sample env.json
 ```
 
-Edit the compose file according to its comments.  Then you can start the service.  
+Edit `docker-compose.yml` and `env.json` files according to their comments.  Then you can start the service:  
 
-```
+```sh
 docker-compose up -d
 ```
 
 The API will modify your wireguard configuration file.  Changes will not take effect unless the interface is restarted periodically.  One way of doing this is with a systemd timer.  
 
-TODO: Add systemd timer and instructions
+### systemd
 
-**NOTE:** The API is not protected by any authentication.  As it stands, anyone can connect to your API and access your wireguard network!  Be sure to protect it with authentication in a web proxy or by blocking access with a firewall.  
+The API edits the wireguard config in the background but doesn't restart the service.  To have changes take effect every 10 minutes, you can use this repo's systemd unit files:
+
+```sh
+cd /etc/systemd/system
+sudo wget 'https://gitea.gf4.pw/gf4/wgapi/raw/branch/master/systemd/restart-wg-quick@.service'
+sudo wget 'https://gitea.gf4.pw/gf4/wgapi/raw/branch/master/systemd/restart-wg-quick@.timer'
+sudo systemctl daemon-reload
+# Replace this with your interface
+sudo systemctl start restart-wg-quick@wg0.timer
+```
+
+If that works, make it run on boot:
+
+```sh
+sudo systemctl enable restart-wg-quick@wg0.timer
+```
 
 ## Usage
 
-Once the server is listening, there are two endpoints that clients can direct requests to.  
+Once the server is listening, there are three endpoints that clients can direct requests to.  
+
+### List (/list)
+
+This endpoint returns a user's `user` object, including an auth token, containing all the peer information in `user.peers`.  
+
+#### Request
+
+Just `GET /list` and this endpoint will detect who you are based on your IP and return your user object.  
+
+#### Response
+
+Returns the user object and peers as json.  
+
+```json
+{
+	"name": myusername,
+	"token": longsecrettokenhere,
+	"subnet": "8",
+	"peers": [
+		{
+			"name": "host1",
+			"ipv4": "10.5.8.1"
+			"ipv6": "fd69:1337:0:420:f4:f5:8:1"
+		},
+		{
+			"name": "host2",
+			"ipv4": "10.5.8.2"
+			"ipv6": "fd69:1337:0:420:f4:f5:8:2"
+		}
+	]
+}
+```
+
+...
 
 ### Add
 
-This endpoint adds a peer to the wireguard server.  
+This endpoint adds a peer to the wireguard servers and adds its IP address to the nameserver.  To guard against IP spoofing, it requires a token from a `/list` request.  
 
-TODO: Write how to use it. 
+#### Request
+
+Simply `GET /add?token=MYTOKEN&name=host3` where `MYTOKEN` is the secret token from the `/list` request and `host3` is the new hostname.  The backend will add your new peer to its wireguard config and inform other servers of the new peer.  Then it will modify the nameserver to add your peer's IP addresses under the domain `host3.myusername.tld`.  
+
+#### Response
+
+A successful `/add` request will return the new peer's wireguard configuration as plaintext.  Copy and paste it to your client machine's `/etc/wireguard/wg0.conf` file.
+
+A failed requst will return an error code.  `5XX` HTTP codes provide have errors in the log.  
 
 ### Delete
 
-This endpoint deletes a peer from the server.  
+This endpoint deletes a peer from the wireguard servers and removes its domain from the nameserver.  To guard against IP spoofing, it requires a token from a `/list` request.
 
-TODO: Write how to use it. 
+#### Request
 
-## Notes
+After getting a token from a `/list` request, a peer can be identified and deleted using any of these requests: 
 
-After a config has been downloaded by a client, the user is free to modify it to peer with friends' hosts.  
+ - `GET /del?token=MYTOKEN&name=host3` using the hostname
+ - `GET /del?token=MYTOKEN&pubkey=PUBKEY` using a wireguard public key
+ - `GET /del?token=MYTOKEN&privkey=PRIVKEY` using a wireguard private key
+ - `GET /del?token=MYTOKEN&psk=PSK` using the wireguard preshared key
+ - `GET /del?token=MYTOKEN&ip=IP` using an IPv4 or IPv6 address
 
-TODO: Add instructions on how to do this.  
+#### Response
+
+It will simply return `200 OK` in case of success.  `5XX` HTTP codes provide have errors in the log.  
 
 ## License (GPLv2)
 
- 
 Copyright © 2021 Keith Irwin
 
 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.