dsnet/CONFIG.md

Explanation of each field:

    {
        "ExternalHostname": "",

The `ExternalHostname` is used for the client config server `Endpoint` if
defined. It has precedence over `ExternalIP` and `ExternalIP6`.


        "ExternalIP": "198.51.100.2",
        "ExternalIP6": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",

This is the external IPv4 and IPv6 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
IP will win.

When generating configs, the `ExternalHostname` has precendence for the server
`Endpoint`, followed by `ExternalIP` (IPv4) and `ExternalIP6` (IPv6) The IPs are
discovered automatically on init. Define an `ExternalHostname` if you're using
dynamic DNS, want to change IPs without updating configs, or want wireguard to
be able to choose between IPv4/IPv6. It is only possible to specify one
Endpoint per peer entry in wireguard.


        "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",
        "Network6": "fd00:7b31:106a:ae00::/64",

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.

A random ULA network with a subnet of 0 is generated for IPv6.

        "IP": "10.164.236.1",
        "IP6": "fd00:7b31:106a:ae00:44c3:29c3:53b1:a6f9",

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. The shortcode file is included in this repository under
`etc/`.

        "PostUp": ""
        "PostDown": ""

Allows a user to specify commands to run after the device is up or down. This is
typcially a collection of `iptables` invocations. The commands are executed by
`/bin/sh`. *NOTE* These commands run as root, so make sure you check that they
are secure.

        "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.


        }