Advanced Client Installation

This document tells you how to install the netclient on machines that will be a part of your Netmaker network, as well as non-compatible systems.

These steps should be run after the Netmaker server has been created and a network has been designated within Netmaker.

Introduction to Netclient

At its heart, the netclient is a simple CLI for managing access to various WireGuard-based networks. It manages WireGuard on the host system, so that you don’t have to. Why is this necessary?

If you are setting up a WireGuard-based virtual network, you must configure each machine with very specific settings, so that every machine can reach it, and it can reach every machine. Any changes to the settings of any one of these machines can break those connections. Any machine that is added, removed, or modified on the network requires reconfiguring every peer in the network. This can be very time consuming.

The netmaker server holds configuration details about every machine in your network and how other machines should connect to it.

The netclient agent connects to the server, pushing and pulling information when the network (or its local configuration) changes.

The netclient agent then configures WireGuard (and other network properties) locally, so that the network stays intact.

Notes on Windows

If running the netclient on windows, you must download the netclient.exe binary and run it from Powershell as an Administrator.

Windows will by default have firewall rules that prevent inbound connections. If you wish to allow inbound connections from particular peers, use the following command:

netsh advfirewall firewall add rule name="Allow from <peer private addr>" dir=in action=allow protocol=ANY remoteip=<peer private addr>

If you want to allow all peers access, but do not want to configure firewall rules for all peers, you can configure access for one peer, and set it as a Relay Server.

Running the install script

Some file locations have issues running the install script, such as running from the root C:/ folder. Users have noted the following locations work well for running the install powershell script:

  • C:/Program Files/wireguard

  • C:/Windows/System32

Running netclient commands

If running the netclient manually (“netclient join”, “netclient checkin”, “netclient pull”) it should be run from outside of the installed directory, which will be either:

  • C:/Program Files/netclient

  • C:/ProgramData/netclient

It is better to call it from a different directory.

High CPU Utilization

With some versions of WireGuard on Windows, high CPU utilization has been found with the netclient. This is typically due to interaction with the WireGuard GUI component (app). If you’re experiencing high CPU utilization, close the WireGuard app. WireGuard will still be running, but the CPU usage should go back down to normal.

Notes on OpenWRT

Deploying on OpenWRT depends a lot on the version of OpenWRT and the hardware being used. If the primary installer does not work, there are two things you can try:

  1. This community-run package for OpenWRT: https://github.com/sbilly/netmaker-openwrt

  2. Manual installation:

  1. You may experience an issue with the length of the token, which has limits on some OpenWRT shells. If you run into this problem, you can use the following script to convert your token into a “netclient join” command:

  • wget https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/token-convert.sh

  • ./token-convert <token value>

  • Run the output on your OpenWRT machine

Modes and System Compatibility

Note: If you would like to connect non-Linux/Unix machines to your network such as phones and Windows desktops, please see the documentation on External Clients

The netclient can be run in a few “modes”. System compatibility depends on which modes you intend to use. These modes can be mixed and matched across a network, meaning all machines do not have to run with the same “mode.”

CLI

In its simplest form, the netclient can be treated as just a simple, manual, CLI tool, which a user can call to configure the machine. The cli can be compiled from source code to run on most systems, and has already been compiled for x86 and ARM devices.

As a CLI, the netclient should function on any Linux or Unix based system that has the wireguard utility (callable with wg) installed.

Daemon

The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service, or launchd/windows service for Mac or Windows.

If running the netclient on non-systemd linux, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.

Private DNS Management

To manage private DNS, the netclient relies on systemd-resolved (resolvectl). Absent this, it cannot set private DNS for the machine.

A user may choose to manually set a private DNS nameserver of <netmaker server>:53. However, beware, as netmaker sets split dns, and the system must be configured properly. Otherwise, this nameserver may break your local DNS.

Prerequisites

To obtain the netclient, go to the GitHub releases: https://github.com/gravitl/netmaker/releases

For netclient cli: Linux/Unix with WireGuard installed (wg command available)

For netclient daemon: Systemd Linux + WireGuard

For Private DNS management: Resolvectl (systemd-resolved)

Configuration

The CLI has information about all commands and variables. This section shows the “help” output for these commands as well as some additional reference.

CLI Reference

sudo netclient --help

NAME:
   Netclient CLI - Netmaker's netclient agent and CLI. Used to perform interactions with Netmaker server and set local WireGuard config.

USAGE:
   netclient [global options] command [command options] [arguments...]

COMMANDS:
   register    Register with Netmaker Server for secure GRPC communications.
   join        Join a Netmaker network.
   leave       Leave a Netmaker network.
   checkin     Checks for local changes and then checks into the specified Netmaker network to ask about remote changes.
   push        Push configuration changes to server.
   pull        Pull latest configuration and peers from server.
   list        Get list of networks.
   uninstall   Uninstall the netclient system service.
   unregister  Unregister the netclient from secure server GRPC.
   help, h     Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help (default: false)

sudo netclient join --help

alex@workstation:~$ sudo netclient join --help
NAME:
   netclient join - Join a Netmaker network.

USAGE:
   netclient join [command options] [arguments...]

OPTIONS:
   --network value, -n value            Network to perform specified action against. (default: "all") [$NETCLIENT_NETWORK]
   --password value, -p value           Password for authenticating with netmaker. [$NETCLIENT_PASSWORD]
   --endpoint value, -e value           Reachable (usually public) address for WireGuard (not the private WG address). [$NETCLIENT_ENDPOINT]
   --macaddress value, -m value         Mac Address for this machine. Used as a unique identifier within Netmaker network. [$NETCLIENT_MACADDRESS]
   --publickey value, --pubkey value    Public Key for WireGuard Interface. [$NETCLIENT_PUBLICKEY]
   --privatekey value, --privkey value  Private Key for WireGuard Interface. [$NETCLIENT_PRIVATEKEY]
   --port value                         Port for WireGuard Interface. [$NETCLIENT_PORT]
   --keepalive value                    Default PersistentKeepAlive for Peers in WireGuard Interface. (default: 0) [$NETCLIENT_KEEPALIVE]
   --operatingsystem value, --os value  Identifiable name for machine within Netmaker network. [$NETCLIENT_OS]
   --name value                         Identifiable name for machine within Netmaker network. [$NETCLIENT_NAME]
   --localaddress value                 Local address for machine. Can be used in place of Endpoint for machines on the same LAN. [$NETCLIENT_LOCALADDRESS]
   --address value, -a value            WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESS]
   --addressIPv6 value, --a6 value      WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESSIPV6]
   --interface value, -i value          WireGuard local network interface name. [$NETCLIENT_INTERFACE]
   --apiserver value                    Address + GRPC Port (e.g. 1.2.3.4:50051) of Netmaker server. [$NETCLIENT_API_SERVER]
   --grpcserver value                   Address + API Port (e.g. 1.2.3.4:8081) of Netmaker server. [$NETCLIENT_GRPC_SERVER]
   --key value, -k value                Access Key for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSKEY]
   --token value, -t value              Access Token for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSTOKEN]
   --localrange value                   Local Range if network is local, for instance 192.168.1.0/24. [$NETCLIENT_LOCALRANGE]
   --dns value                          Sets private dns if 'on'. Ignores if 'off'. Will retrieve from network if unset. (default: "on") [$NETCLIENT_DNS]
   --islocal value                      Sets endpoint to local address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_LOCAL]
   --isdualstack value                  Sets ipv6 address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_DUALSTACK]
   --udpholepunch value                 Turns on udp holepunching if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_UDP_HOLEPUNCH]
   --ipforwarding value                 Sets ip forwarding on if 'on'. Ignores if 'off'. On by default. (default: "on") [$NETCLIENT_IPFORWARDING]
   --postup value                       Sets PostUp command for WireGuard. [$NETCLIENT_POSTUP]
   --postdown value                     Sets PostDown command for WireGuard. [$NETCLIENT_POSTDOWN]
   --daemon value                       Installs daemon if 'on'. Ignores if 'off'. On by default. (default: "on") [$NETCLIENT_DAEMON]
   --roaming value                      Checks for IP changes if 'on'. Ignores if 'off'. On by default. (default: "on") [$NETCLIENT_ROAMING]
   --help, -h                           show help (default: false)

Config File Reference

There is a config file for each node under /etc/netconfig-<network name>. You can change these values and then set “postchanges” to “true”, or go to the CLI and run netclient push -n <network>

server:
    corednsaddr: 147.182.251.203 # Address of CoreDNS Server (set locally with resolvectl)
    grpcaddress: 10.101.0.1:50051 # Address of GRPC Server (used for all interaction with server after registration)
    apiaddress: 1.2.3.4:8081 # Address of API Server (used only for registration/unregistration)
    accesskey: 5qKTbTgsvb45y3qyRmWft # Key used to sign up with server. Used only during registration
node:
    name: my-computer # name of this node
    interface: nm-example # name of interface to create/use for WG
    network: example # name of network this ode is a part of
    password: $2a$0afehuytviN/thMpVlCYkonxy.Ws2.rNCJjBSAa3HZuhrK5hpYxme # encrypted node password, used to retrieve JWT. Can be changed to new pass in plaintext and CLI will update/replace with encrypted pass
    macaddress: 6c:4b:91:0g:68:7b # MAC of node. Used as a Unique ID
    localaddress: 192.168.1.32 # Address on local network, used as endpoint for other local nodes for faster comms
    wgaddress: 10.7.11.2 # Private WG addres on network
    wgaddress6: "f8:34:41:77:5c:15" # Private ipv6 address if network is dual stack
    roaming: "yes" # Whether or not to grab new endpoint value automatically
    dnson: "no" # Whether or not to set local DNS based on Netmaker's Private DNS server
    islocal: "no" # Based on network. If yes, will use local IP as endpoint.
    isdualstack: "yes" # Use IPv6 in addition to IPv4
    isingressgateway: "no" # whether or not node is an ingress gateway (will set iptables forwarding rules)
    allowedips: "" # additional IP's to add to client
    localrange: "" # local range if it's a local network. For instance, 192.168.1.0/24
    postup: "" # postup command, used by ingress/egress gateways to set iptables
    postdown: "" # postdown command, used by ingress/egress gateways to set iptables
    port: 51821 # WG port to use
    keepalive: 20 # default keepalive with nodes
    publickey: 8/q9cOg7c9QjnoXygVrY/VNE197VMRadJodkb1ZsujA= # public key of node to show to other nodes
    privatekey: "" # private key, set only for changing and then will revert to blank in config
    endpoint: 78.170.22.168 # public endpoint for reaching node 
    postchanges: "false" # if true, will post and config file changes on next checkin and then revert to false
    ipforwarding: "yes" # set ip forwarding; highly recommended to leave on
    isstatic: "no" # if yes, daemon will not change pubkey, endpoint, or address
    udpholepunch: "yes" # run UDP hole punching (will ignore port above, e.g. 51821)
    network: home # the network (duplicate of node.network)
daemon: "yes" # whether or not to manage systemd
operatingsystem: "" # not currently in use

Installation

To install netmaker, you need a server token for a particular network, unless you’re joining a network that allows manual signup, in which case you can join without a token, but the server will quarantine the machine until the admin approves it.

An admin creates a token in the ACCESS KEYS section of the UI. Upon creating a token, it generates 3 values:

Access Key: The secret key to authenticate as a node in the network

Access Token: The secret key plus information about how to access the server (addresses, ports), all decoded by the netclient to register with the server

Install Command: A short script that will obtain the netclient binary, register with the server, and join the network, all in one

For first time installations, you can run the Install Command. For additional networks, simply run netclient join -t <access token>. The raw access key will not be needed unless there are special circumstances, mostly troubleshooting incorrect information in the token (you can instead manually specify the server location).

Managing Netclient

Viewing Logs

to view current networks

netclient list

to tail logs

journalctl -u netclient

to get most recent log run

systemctl status netclient

Re-syncing netclient (basic troubleshooting)

If the daemon is not running correctly run, try restarting the daemon, or pulling changes directly (don’t do both at once)

systemctl restart netclient

sudo netclient pull

Making Updates

vim /etc/netclient/config/netconfig-<network>

Change any of the variables in this file, and changes will be pushed to the server and processed locally on the next checkin.

For instance, change the private address, endpoint, or name. See above example config file for details

Adding/Removing Networks

netclient join -t <token>

Set any of the above flags (netclient join –help) to override settings for joining the network. If a key is provided (-k), then a token is unnecessary, but grpc, server, ports, and network must all be provided via flags.

Uninstalling

netclient uninstall