Repository files navigation

Simple command to manage a centralised wireguard VPN. Think wg-quick but quicker: key generation + address allocation. It can generate ready-to-go client configs forwg-quick, EdgeOS and NixOS.

Set up a VPN in one minute:

The server peer is listening, and a client peer config has been generated andadded to the server peer:

More client peers can be added withdsnet add. They can connect immediatelyafter! Don't forget toenable IP forwardingto allow peers to talk to one another.

It works on AMD64 based linux and also ARMv5.

Usage:    dsnet [command]Available Commands:  add         Add a new peer + sync  down        Destroy the interface, run pre/post down  help        Help about any command  init        Create /etc/dsnetconfig.json containing default configuration + new keys without loading. Edit to taste.  regenerate  Regenerate keys and config for peer  remove      Remove a peer by hostname provided as argument + sync  report      Generate a JSON status report to the location configured in /etc/dsnetconfig.json.  sync        Update wireguard configuration from /etc/dsnetconfig.json after validating  up          Create the interface, run pre/post up, sync  version     Print versionFlags:  -h, --help            help for this command      --output string   config file format: vyatta/wg-quick/nixos (default "wg-quick")Use "dsnet [command] --help" for more information about a command.

Quick start (AMD64 linux) -- install wireguard, then, after making sure/usr/local/bin is in your path:

sudo wget https://github.com/naggie/dsnet/releases/latest/download/dsnet-linux-amd64 -O /usr/local/bin/dsnetsudo chmod +x /usr/local/bin/dsnetsudo dsnet init# edit /etc/dsnetconfig.json to tastesudo dsnet upsudo dsnet add banana > dsnet-banana.confsudo dsnet add apple > dsnet-apple.conf# enable IP forwarding to allow peers to talk to one anothersudo sysctl -w net.ipv4.ip_forward=1   # edit /etc/sysctl.conf to make this persistent across reboots

Copy the generated configuration file to your device and connect!

To send configurations, here are a few suggestions.

• ffsend, the most straightforward option;
• magic wormhole, a more advancedoption, where the file never passes through another server;
• wormhole-william, a Goimplementation of the above.

For the above options, one should transfer the password separately.

A local QR code generator, such as the popularqrencode may also be used to generate aQR code of the configuration. For instance:dsnet add | qrencode -t ansiutf8.This works because the dsnet prompts are on STDERR and not passed to qrencode.

The peer private key is generated on the server, which is technically not assecure as generating it on the client peer and then providing the server thepublic key; there is provision to specify a public key in the code when addinga peer to avoid the server generating the private key. The feature will beadded when requested.

Note that named arguments can be specified on the command line as well asentered by prompt; this allows for unattended usage.

Dsnet does not include or require a GUI, however there is now a separateofficial monitoring GUI:https://github.com/botto/dsnet-gui.

The configuration is a single JSON file. Beyond possible initialcustomisations, the file is managed entirely by dsnet.

dsnetconfig.json is the only file the server needs to run the VPN. It containsthe server keys, peer public/shared keys and IP settings.A working version isautomatically generated bydsnet init which can be modified as required.

Currently its location is fixed as all my deployments are for a single network.I may add a feature to allow setting of the location via environment variablein the future to support multiple networks on a single host.

Main (automatically generated) configuration example:

{    "ExternalHostname": "",    "ExternalIP": "198.51.100.2",    "ExternalIP6": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",    "ListenPort": 51820,    "Domain": "dsnet",    "InterfaceName": "dsnet",    "Network": "10.164.236.0/22",    "Network6": "fd00:7b31:106a:ae00::/64",    "IP": "10.164.236.1",    "IP6": "fd00:d631:74ca:7b00:a28:11a1:b821:f013",    "DNS": "",    "Networks": [],    "ReportFile": "/var/lib/dsnetreport.json",    "PrivateKey": "uC+xz3v1mfjWBHepwiCgAmPebZcY+EdhaHAvqX2r7U8=",    "PostUp": "",    "PostDown" "",    "Peers": [        {            "Hostname": "test",            "Owner": "naggie",            "Description": "Home server",            "IP": "10.164.236.2",            "IP6": "fd00:7b31:106a:ae00:44c3:29c3:53b1:a6f9",            "Added": "2020-05-07T10:04:46.336286992+01:00",            "Networks": [],            "PublicKey": "altJeQ/V52JZQrGcA9RiKcpZusYU6zMUJhl7Wbd9rX0=",            "PresharedKey": "GcUtlze0BMuxo3iVEjpOahKdTf8xVfF8hDW3Ylw5az0="        }    ]}

SeeCONFIG.md for an explanation of each field.

An example report file, generated bydsnet report to/var/lib/dsnetreport.json by default:

{    "ExternalIP": "198.51.100.2",    "InterfaceName": "dsnet",    "ListenPort": 51820,    "Domain": "dsnet",    "IP": "10.164.236.1",    "Network": "10.164.236.0/22",    "DNS": "",    "PeersOnline": 4,    "PeersTotal": 13,    "ReceiveBytes": 32517164,    "TransmitBytes": 85384984,    "ReceiveBytesSI": "32.5 MB",    "TransmitBytesSI": "85.4 MB",    "Peers": [        {            "Hostname": "test",            "Owner": "naggie",            "Description": "Home server",            "Online": false,            "Dormant": true,            "Added": "2020-03-12T20:15:42.798800741Z",            "IP": "10.164.236.2",            "ExternalIP": "198.51.100.223",            "Networks": [],            "Added": "2020-05-07T10:04:46.336286992+01:00",            "ReceiveBytes": 32517164,            "TransmitBytes": 85384984,            "ReceiveBytesSI": "32.5 MB",            "TransmitBytesSI": "85.4 MB"        }        <...>    ]}

Fields mean the same as they do above, or are self explanatory. Note that somedata is converted into human readable formats in addition to machine formats --this is technically redundant but useful with Hugo shortcodes and other site generators.

The report can be converted, for instance, into a HTML table as below:

Seeetc/README.mdfor hugo and PHP code for rendering a similar table.

dsnet currently supports the generation of awg-quick configuration bydefault. It can also generate VyOS/Vyatta configuration for EdgeOS/Unifi devicessuch as the Edgerouter 4 using thewireguard-vyatta package,as well as configuration forNixOS, ready to be added toconfiguration.nix environment definition.

To change the config file format, set the following environment variables:

• DSNET_OUTPUT=vyatta
• DSNET_OUTPUT=wg-quick
• DSNET_OUTPUT=nixos

Example vyatta output:

configureset interfaces wireguard wg23 address 10.165.52.3/22set interfaces wireguard wg23 address fd00:7b31:106a:ae00:f7bb:bf31:201f:60ab/64set interfaces wireguard wg23 route-allowed-ips trueset interfaces wireguard wg23 private-key cAtj1tbjGGmVoxdY78q9Sv0EgNlawbzffGWjajQkLFw=set interfaces wireguard wg23 description dsnetset interfaces wireguard wg23 peer PjxQM7OwVYvOJfORA1EluLw8CchSu7jLq92YYJi5ohY= endpoint 123.123.123.123:51820set interfaces wireguard wg23 peer PjxQM7OwVYvOJfORA1EluLw8CchSu7jLq92YYJi5ohY= persistent-keepalive 25set interfaces wireguard wg23 peer PjxQM7OwVYvOJfORA1EluLw8CchSu7jLq92YYJi5ohY= preshared-key w1FtOKoMEdnhsjREtSvpg1CHEKFzFzJWaQYZwaUCV38=set interfaces wireguard wg23 peer PjxQM7OwVYvOJfORA1EluLw8CchSu7jLq92YYJi5ohY= allowed-ips 10.165.52.0/22set interfaces wireguard wg23 peer PjxQM7OwVYvOJfORA1EluLw8CchSu7jLq92YYJi5ohY= allowed-ips fd00:7b31:106a:ae00::/64commit; save

The interface (in this casewg23) is deterministically chosen in the rangewg0-wg999. This is such that you can use multiple dsnet configurations andthe interface numbers will (probably) be different. The interface number isarbitrary, so if it is already assigned replace it with a number of yourchoice.

Example NixOS output:

networking.wireguard.interfaces = {  dsnet = {    ips = [      "10.9.8.2/22"      "fd00:80f8:af4a:4700:aaaa:bbbb:cccc:88ad/64"      ];    privateKey = "2PvML6bsmTCK+cBxpV9SfF261fsH6gICixtppfG6KFc=";    peers = [      {        publicKey = "zCDo5yn7Muy3mPBXtarwm5S7JjNKM0IdIdGqoreWmSA=";        presharedKey = "5Fa8Zc8gIkpfBPJUJn5OEVuE00iqmXnS34v4evv1MUM=";        allowedIPs = [          "10.56.72.0/22"          "fd00:80f8:af4a:4700::/64"          ];        endpoint = "123.123.123.123:51820";        persistentKeepalive = 25;      }    ];  };};

Does dsnet support IPv6?

Yes! By default since version 0.2, a random ULA subnet is generated with a 0subnet ID. Peers are allocated random addresses when added. Existing IPv4configs will not be updated -- add aNetwork6 subnet to the existing configto allocate addresses to new peers.

Like IPv4, it's up to you if you want to provide NAT IPv6 access to theinternet; alternatively (and preferably) you can allocate a a real IPv6 subnetsuch that all peers have a real globally routeable IPv6 address.

Upon initialisation, the server IPv4 and IPv6 external IP addresses arediscovered on a best-effort basis. Clients will have configuration configuredfor the server IPv4 preferentially. If not IPv4 is configured, IPv6 is used;this is to give the best chance of the VPN working regardless of the dodgynetwork you're on.

Is dsnet production ready?

Absolutely, it's just a configuration generator so your VPN does not depend ondsnet 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 willbe made clear in release notes.

Client private keys are generated on the server. Can I avoid this?

Allowing generation of the pub/priv keypair on the client is not yet supported,but will be soon as provision exists within the code base. Note that whilstclient peer private keys are generated on the server, they are never stored.

How do I get dsnet to bring the (server) interface up on startup?

Assuming you're running a systemd powered linux distribution (most of them are):

1. Copyetc/dsnet.serviceto/etc/systemd/system/
2. Runsudo systemctl daemon-reload to get systemd to see it
3. Then runsudo systemctl enable dsnet to enable it at boot

How can I generate the report periodically?

Either with cron or a systemd timer. Cron is easiest:

echo '* * * * * root /usr/local/bin/dsnet report | sudo tee /etc/cron.d/dsnetreport'

Note that whilst report generation requires root, consuming the report does notas it's just a world-readable file. This is important for web interfaces thatneed to be secure.

This is also why dsnet loads its configuration from a file -- it's possible toset permissions such that dsnet synchronises the config generated by a non-rootuser. Combined with a periodicdsnet sync like above, it's possible to builda secure web interface that does not require root. A web interface is currentlybeing created by a friend; it will not be part of dstask, rather a separateproject.