Wiresteward is a WireGuard peer manager with oauth2 authentication. It is comprised of two components: server and agent.
The design is for Wiresteward server to run on a remote machine in a private network, to which users will connect with WireGuard in order to access the private network.
The agent runs on the user's machine and is responsible for authenticating with the server and retrieving WireGuard configuration.
Both components will configure their local WireGuard devices and route tables as needed to enable access to a private network.
Download the latest binary from: https://github.com/utilitywarehouse/wiresteward/releases
If you're on macOS or Linux and have Homebrew installed, getting Wiresteward is as simple as running:
brew install utilitywarehouse/tap/wiresteward
The Wiresteward agent is responsible for:
- creating network tun devices
- fetching oauth tokens to pass server authentication
- registering WireGuard keys with the Wiresteward server and retrieving configuration
- configuring WireGuard peers
- configuring routes for the subnets allowed by the server
It is recommended that the agent is run as a Systemd (Linux) / launchd (macOS) service.
But you can also run the executable directly:
# wiresteward -agent -config=path-to-config.jsonPlease note that because wiresteward will create and manage network devices
and network routes, it requires NET_ADMIN capabilities. You can run it as
root with sudo.
See examples/server.json and
examples/agent.json for example configuration.
The agent can take a config file as an argument or look for it under the default location:
/etc/wiresteward/config.json
The config contains details about the oauth server and the local devices that we need the agent to manage.
An example, where the config format can be found in
examples/agent.json.
The default MTU for the interfaces created via the agent is 1420 and it comes
from the default value of wireguard-go
package.
Optionally, MTU can be set explicitly per wg device created by the agent via
the configuration file (using the "MTU" key under device config)
The agent is designed to run as a Systemd service. An example working service
is described in
examples/wiresteward.service.
A typical location for user defined systemd service is
/etc/systemd/system/wiresteward.service so you'll need to copy the unit file
to that location and then run:
# systemctl daemon-reload
# systemctl enable --now wiresteward.serviceTo look at its logs:
$ journalctl -u wiresteward.serviceAn example working service for launchd is described in
examples/uk.co.uw.wiresteward.plist.
You need to copy the file under /Library/LaunchDaemons/ and then set the
ownership to root:
# chown root:admin /Library/LaunchDaemons/uk.co.uw.wiresteward.plistThen need to load the service:
# sudo launchctl load /Library/LaunchDaemons/uk.co.uw.wiresteward.plistThis will allow the service to run as root, which is required to operate on the network devices and routing table.
Logs are stored in /var/log/wirestward.log as defined in the service file. To
view the logs you can:
$ tail -f /var/log/wiresteward.logYou might want to setup log rotation as well if you find that the log file grows too large.
The agent runs a local server on port 7773 and expects the user to visit
http://localhost:7773/ in order to authenticate. Once authenticated, the
agent will be able to continue operating until the token retrieved is expired,
at which point the user needs to authenticate again.
Visiting http://localhost:7773/ will cause the agent to immediately configure
the local WireGuard devices. If it already has a valid token, it will not prompt
the user to re-authenticate but it will re-configure the system.
The Wiresteward server is responsible for:
- creating new network WireGuard device
- registering new peers and allocating ip addresses for them
- configuring WireGuard peers
- revoking access for expired address leases
It is recommended that the agent is run as a systemd service.
The server can take a config file as an argument or look for it under the
default location /etc/wiresteward/config.json. The config contains details
about the oauth server and the network subnets that need to be exposed, as well
as the network subnet from which peer addresses are leased to agents.
An example, where the config format can be found in
examples/server.json.
There are Terraform modules defined under terraform/ which
describe the recommended deployment method in AWS and GCP. See the more specific
README file for details.