add config documentation

README.md

@@ -22,16 +22,161 @@ Quick start -- install wireguard and dsnet, then:
 	dsnet add banana > dsnet-banana.conf
 	dsnet add apple > dsnet-apple.conf
 
-Copy the configuration file to your devices and connect!
+Copy the generated configuration file to your device and connect!
-
-Dsnet assumes a DNS server is running on the server at the moment.
 
 To send configurations, ffsend (with separately transferred password) or a local QR code generator may be used.
 
-TODO after first release:
+# Walkthrough of /etc/dsnetconfig.json
 
-  * Hooks for adding routes/ IPtables forwarding rules
+dsnetconfig.json is the only file the server needs to run the VPN. It contains
-  * Route entire internet option
+the server keys, peer public/shared keys and IP settings.
-  * Support for additional subnets in peer config (with routes) in separate networks section in report
+
-  * Peer endpoint support
+Currently its location is fixed as all my deployments are for a single network.
-  * Decide what to do with assumed default DNS server
+I may add a feature to allow setting of the location via environment variable
+in the future to support multiple networks on a single host.
+
+Main configuration, generated by `dsnet init` and edited manually:
+
+    {
+        "ExternalIP": "198.51.100.2",
+
+This is the external IP that will be the value of Endpoint for the server peer
+in client configs. It is automatically detected by opening a socket or using an
+external IP discovery service -- the first to give a valid public IPv4 will
+win.
+
+
+        "ListenPort": 51820,
+
+The port wiregard should listen on.
+
+        "Domain": "dsnet",
+
+The domain to copy to the report file. Not used for anything else; it's useful
+for DNS integration. At one site I have a script to add hosts to a zone upon
+connection by polling the report file.
+
+        "InterfaceName": "dsnet",
+
+The wireguard interface name.
+
+        "Network": "10.164.236.0/22",
+
+The CIDR network to use when allocating IPs to peers. This subnet, a `/22` in
+the `10.0.0.0/16` block is generated randomly to (probably) avoid collisions
+with other networks. There are 1022 addresses available. Addresses are
+allocated to peers when peers are added with `dsnet add` using the lowest
+available address.
+
+        "IP": "10.164.236.1",
+
+This is the private VPN IP of the server peer. It is the first address in the
+above pool.
+
+        "DNS": "",
+
+If defined, this IP address will be set in the generated peer wg-quick config
+files.
+
+        "Networks": [],
+
+This is a list of additional CIDR-notated networks that can be routed through
+the server peer. They will be added under the server peer under `AllowedIPs` in
+addition to the private network defined in `Network` above. If you want to
+route the whole internet through the server peer, add `0.0.0.0/0` to the list
+before adding peers. For more advanced options and theory, see
+<https://www.wireguard.com/netns/>.
+
+        "ReportFile": "/var/lib/dsnetreport.json",
+
+This is the location of the report file generated with `dsnet report`. It is
+suggested that this command is run via a cron job; the report can be safely
+consumed by a web service or DNS integration script, for instance.
+
+The report contains no sensitive information. At one site I use it together
+with [hugo](https://gohugo.io/)
+[shortcodes](https://gohugo.io/templates/shortcode-templates/) to generate a
+network overview page.
+
+        "PrivateKey": "uC+xz3v1mfjWBHepwiCgAmPebZcY+EdhaHAvqX2r7U8=",
+
+The server private key, automatically generated and very sensitive!
+
+        "Peers": []
+
+The list of peers managed by `dsnet add` and `dsnet remove`. See below for format.
+
+    }
+
+The configuration file can be manually/programatically managed outside of dsnet
+if desired; `dsnet sync` will update wireguard.
+
+Peer configuration, `Peers: []` in `dsnetconfig.json`:
+
+        {
+            "Hostname": "test",
+
+The hostname given via `dsnet add <hostname>`. It is used to identify the peer
+in the report and for peer removal via `dsnet remove <hostname>`. It can also
+be used to update a DNS zone via a custom script that operates on the report
+file as mentioned above.
+
+            "Owner": "naggie",
+
+The owner of the peer, copied to the report file.
+
+            "Description": "Home server",
+
+A description of the peer, copied to the report file; the lack of which in
+`wq-quick` is what inspired me to write dsnet in the first place.
+
+
+            "IP": "10.164.236.2",
+
+The private VPN IP allocated by dsnet for this peer. It is the lowest available
+IP in the pool from `Network`, above.
+
+            "Added": "2020-05-07T10:04:46.336286992+01:00",
+
+The timestamp of when the peer was added by dsnet.
+
+            "Networks": [],
+
+Any other CIDR networks that can be routed through this peer.
+
+            "PublicKey": "altJeQ/V52JZQrGcA9RiKcpZusYU6zMUJhl7Wbd9rX0=",
+
+The public key derived from the private key generated by dsnet when the peer
+was added.
+
+            "PresharedKey": "GcUtlze0BMuxo3iVEjpOahKdTf8xVfF8hDW3Ylw5az0="
+
+The pre-shared key for this peer. The peer has the same key defined as the
+pre-shared key for the server peer. This is optional in wireguard but not for
+dsnet due to the extra (post quantum!) security it provides.
+
+
+        }
+
+# Report file overview
+
+# FAQ
+
+> Does dsnet support IPv6?
+
+Not currently but this is a [planned feature](https://github.com/naggie/dsnet/issues/1).
+
+> Is dsnet production ready?
+
+Absolutely, it's just a configuration generator so your VPN does not depend on
+dsnet after adding peers. I use it in production at 2 companies so far.
+
+Note that before version 1.0, the config file schema may change. Changes will
+be made clear in release notes.
+
+> Why are their very few issues?
+
+I'm tracking development elsewhere using
+[dstask](https://github.com/naggie/dstask). I keep public initiated issues on
+github though, and will probably migrate issues over if this gains use outside
+of what I'm doing.