wgstarman

wgstarman

WireGuard manager written in Python 3 to connect two or more peers in a star VPN, i.e. having a central peer which routes the traffic within the VPN. It includes a DHCP-like IP address allocation mechanism.

It currently supports IPv6 only, but IPv4 is in the plans (it needs a proper IP address release logic).

It has been designed and tested on Linux, specifically due to the paths and commands used, but it should work on any POSIX / UNIX operating systems (like MacOS).

Security

The VPN can be accessed only knowing a pre-shared key, generated by the server / central node the first time it is being executed. In case of PSK exposure, the --refresh-psk might be used to generate a new one.

Every message exchanged with the protocol is encrypted and decrypted via the given PSK.

Once the peer joins the network, the WireGuard asymmetric encryption secures the connection between the peers.

Software requirement

• WireGuard kernel's module (it should be enabled by default)
• wg and wg-quick commands (provided by most Linux distributions via the wireguard-tools package)

Setting up the server

wgstarman server --ipv6-network fdxx:xxxx:xxxx:yyyy:zzzz:zzzz::/64
                 [--device-name wg0]
                 [--listen-address-4 0.0.0.0]
                 [--listen-address-6 ::]
                 [--listen-port 1194]
                 [--enable-listen-ipv6]
                 [--refresh-psk]
                 [--debug]

• --ipv6-network the IPv6 network to use for the VPN, i.e. fdxx:xxxx:xxxx:yyyy:zzzz:zzzz::/64
• --device-name the name of both the network device and the configuration file (default: wg0)
• --listen-address-4 the address IPv4 on which the address manager will listen on (default: 0.0.0.0)
• --listen-address-6 the address IPv6 on which the address manager will listen on; requires --enable-listen-ipv6 (default: ::)
• --listen-port the port on which WireGuard (UDP) and the address manager (TCP) will listen on (default: 1194)
• --enable-listen-ipv6 enable address manager to listen on {listen_address_6}:{listen_port}
• --refresh-psk force the refresh of the pre-shared key
• --debug enable debug log

The manager will output the pre-shared key (PSK), to be used for interacting with it and connect new peers.

The central peer will assign to itself the first IP of the network.

NOTE: the pre-shared key is being stored in /etc/wgstarman/wgstarman.conf and is formatted in the following way:

{server_public_key} = {pre-shared key}

The server's public key is generated at runtime the first time the network is being configured.

sysctl configurations

The following sysctl configurations must be set:

• net.ipv6.conf.all.disable_ipv6=0 to enable IPv6 addresses
• net.ipv6.conf.all.forwarding=1 to allow the packets routing via IPv6

docker caps

In case the server is run in docker, the following caps must be set:

• NET_ADMIN
• SYS_MODULE

Setting up the peers

wgstarman peer --server-address xx.yy.zz.kk
               [--server-port 1194]
               --device-name wg0
               --psk ODjCtWVtBzAq11clgtEwYxhHfEz8asGmnzwEQsqIZTU=
               [--host-name peer-name]
               [--keep-alive]
               [--overwrite]
               [--debug]

• --server-address the server's public IP (either IPv4 or IPv6)
• --server-port (default 1194) the port on which the server is listening (see server configuration)
• --device-name the device and configuration file WireGuard will use for this VPN
• --psk the pre-shared key, given by the server at startup
• --host-name name of the peer, resolvable via wgstarman resolv (optional)
• --keep-alive keep the connection to the server alive (to avoid connection drop in case of NAT)
• --overwrite overwrite if a configuration already exists
• --debug enable debug log

Once the command is given and throws no errors, a configuration file is being written in /etc/wireguard/[device-name].conf and the connection is established; the VPN connection can thus be upped or downed via the wg-quick commands.

In case wgstarman is used again specifying an already configured device name, it will connect to the wgstarman server again and verify its address / public key against the server's configuration: in case the server doesn't have the peer's record, it will assign a new IP and the peer will overwrite its own configuration.

Resolving VPN names

As WireGuard supports only layer 3 of the ISO/OSI stack, peers can't use multicast messages to share their positions (for instance using ZeroConf's mDNS protocol).

The tool also intentionally doesn't change the system's resolv configuration, as each system may vary and this might lead to unwanted behaviours (i.e. removing company's name servers etc).

As a result, the tool supports a DNS-like mechanism to resolve host names into their VPN IP addresses. This sub-command can be used as regular users.

The server replying to the resolv requests is the same which assigns the IP addresses, so it always knows which host have which address.

wgstarman resolv --device-name, -d wg0
                 [--resolv-port, -p 1195]
                 {host_name}

• --device-name, -d the device associated with the network
• --resolv-port, -p the resolv port (server listen port + 1)
• {host_name} the host name to query

The resolv command will output the list of the found address(es) connected to the central peer, one address per line. In case of error, an error will be logged in stderr.

Exit codes:

• 0 no error
• 1 resolv server error
• 2 unable to connect to resolv server