<h1id="client-installation--page-root">Client Installation<aclass="headerlink"href="#client-installation--page-root"title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<p>These steps should be run after the Netmaker server has been created and a network has been designated within Netmaker.</p>
<h2id="introduction-to-netclient">Introduction to Netclient<aclass="headerlink"href="#introduction-to-netclient"title="Permalink to this headline">¶</a></h2>
<p>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?</p>
<p>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.</p>
<p>The netmaker server holds configuration details about every machine in your network and how other machines should connect to it.</p>
<p>The netclient agent connects to the server, pushing and pulling information when the network (or its local configuration) changes.</p>
<p>The netclient agent then configures WireGuard (and other network properties) locally, so that the network stays intact.</p>
<h2id="modes-and-system-compatibility">Modes and System Compatibility<aclass="headerlink"href="#modes-and-system-compatibility"title="Permalink to this headline">¶</a></h2>
<p><strong>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</strong></p>
<p>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.”</p>
<h3id="cli">CLI<aclass="headerlink"href="#cli"title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>As a CLI, the netclient should function on any Linux or Unix based system that has the wireguard utility (callable with <strong>wg</strong>) installed.</p>
<h3id="daemon">Daemon<aclass="headerlink"href="#daemon"title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>This requires a systemd-based linux operating system.</p>
<p>If running the netclient on a non-systemd system, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.</p>
<h3id="private-dns-management">Private DNS Management<aclass="headerlink"href="#private-dns-management"title="Permalink to this headline">¶</a></h3>
<p>To manage private DNS, the netclient relies on systemd-resolved (resolvectl). Absent this, it cannot set private DNS for the machine.</p>
<p>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.</p>
<h2id="prerequisites">Prerequisites<aclass="headerlink"href="#prerequisites"title="Permalink to this headline">¶</a></h2>
<p>To obtain the netclient, go to the GitHub releases: <aclass="reference external"href="https://github.com/gravitl/netmaker/releases">https://github.com/gravitl/netmaker/releases</a></p>
<p>The CLI has information about all commands and variables. This section shows the “help” output for these commands as well as some additional reference.</p>
<spanclass="l l-Scalar l-Scalar-Plain">Netclient CLI - Netmaker's netclient agent and CLI. Used to perform interactions with Netmaker server and set local WireGuard config.</span>
<spanclass="l l-Scalar l-Scalar-Plain">register Register with Netmaker Server for secure GRPC communications.</span>
<spanclass="l l-Scalar l-Scalar-Plain">join Join a Netmaker network.</span>
<spanclass="l l-Scalar l-Scalar-Plain">leave Leave a Netmaker network.</span>
<spanclass="l l-Scalar l-Scalar-Plain">checkin Checks for local changes and then checks into the specified Netmaker network to ask about remote changes.</span>
<spanclass="l l-Scalar l-Scalar-Plain">push Push configuration changes to server.</span>
<spanclass="l l-Scalar l-Scalar-Plain">pull Pull latest configuration and peers from server.</span>
<spanclass="l l-Scalar l-Scalar-Plain">list Get list of networks.</span>
<spanclass="l l-Scalar l-Scalar-Plain">uninstall Uninstall the netclient system service.</span>
<spanclass="l l-Scalar l-Scalar-Plain">unregister Unregister the netclient from secure server GRPC.</span>
<spanclass="l l-Scalar l-Scalar-Plain">help, h Shows a list of commands or help for one command</span>
<spanclass="l l-Scalar l-Scalar-Plain">--help, -h show help (default</span><spanclass="p p-Indicator">:</span><spanclass="l l-Scalar l-Scalar-Plain">false)</span>
<spanclass="l l-Scalar l-Scalar-Plain">--endpoint value, -e value Reachable (usually public) address for WireGuard (not the private WG address). [$NETCLIENT_ENDPOINT]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--macaddress value, -m value Mac Address for this machine. Used as a unique identifier within Netmaker network. [$NETCLIENT_MACADDRESS]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--publickey value, --pubkey value Public Key for WireGuard Interface. [$NETCLIENT_PUBLICKEY]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--privatekey value, --privkey value Private Key for WireGuard Interface. [$NETCLIENT_PRIVATEKEY]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--port value Port for WireGuard Interface. [$NETCLIENT_PORT]</span>
<spanclass="nt">--keepalive value Default PersistentKeepAlive for Peers in WireGuard Interface. (default</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">0) [$NETCLIENT_KEEPALIVE]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--operatingsystem value, --os value Identifiable name for machine within Netmaker network. [$NETCLIENT_OS]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--name value Identifiable name for machine within Netmaker network. [$NETCLIENT_NAME]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--localaddress value Local address for machine. Can be used in place of Endpoint for machines on the same LAN. [$NETCLIENT_LOCALADDRESS]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--address value, -a value WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESS]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--addressIPv6 value, --a6 value WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESSIPV6]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--interface value, -i value WireGuard local network interface name. [$NETCLIENT_INTERFACE]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--key value, -k value Access Key for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSKEY]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--token value, -t value Access Token for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSTOKEN]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--localrange value Local Range if network is local, for instance 192.168.1.0/24. [$NETCLIENT_LOCALRANGE]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--dns value Sets private dns if 'on'. Ignores if 'off'. Will retrieve from network if unset. (default</span><spanclass="p p-Indicator">:</span><spanclass="s">"on"</span><spanclass="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_DNS]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--islocal value Sets endpoint to local address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_LOCAL]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--isdualstack value Sets ipv6 address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_DUALSTACK]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--udpholepunch value Turns on udp holepunching if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_UDP_HOLEPUNCH]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--ipforwarding value Sets ip forwarding on if 'on'. Ignores if 'off'. On by default. (default</span><spanclass="p p-Indicator">:</span><spanclass="s">"on"</span><spanclass="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_IPFORWARDING]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--postup value Sets PostUp command for WireGuard. [$NETCLIENT_POSTUP]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--postdown value Sets PostDown command for WireGuard. [$NETCLIENT_POSTDOWN]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--daemon value Installs daemon if 'on'. Ignores if 'off'. On by default. (default</span><spanclass="p p-Indicator">:</span><spanclass="s">"on"</span><spanclass="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_DAEMON]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--roaming value Checks for IP changes if 'on'. Ignores if 'off'. On by default. (default</span><spanclass="p p-Indicator">:</span><spanclass="s">"on"</span><spanclass="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_ROAMING]</span>
<spanclass="l l-Scalar l-Scalar-Plain">--help, -h show help (default</span><spanclass="p p-Indicator">:</span><spanclass="l l-Scalar l-Scalar-Plain">false)</span>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">netclient</span><spanclass="pre">push</span><spanclass="pre">-n</span><spanclass="pre"><network></span></code></p>
<spanclass="nt">corednsaddr</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">147.182.251.203</span><spanclass="c1"># Address of CoreDNS Server (set locally with resolvectl)</span>
<spanclass="nt">grpcaddress</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">10.101.0.1:50051</span><spanclass="c1"># Address of GRPC Server (used for all interaction with server after registration)</span>
<spanclass="nt">apiaddress</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">1.2.3.4:8081</span><spanclass="c1"># Address of API Server (used only for registration/unregistration)</span>
<spanclass="nt">accesskey</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">5qKTbTgsvb45y3qyRmWft</span><spanclass="c1"># Key used to sign up with server. Used only during registration</span>
<spanclass="nt">name</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">my-computer</span><spanclass="c1"># name of this node</span>
<spanclass="nt">interface</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">nm-example</span><spanclass="c1"># name of interface to create/use for WG</span>
<spanclass="nt">network</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">example</span><spanclass="c1"># name of network this ode is a part of</span>
<spanclass="nt">password</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">$2a$0afehuytviN/thMpVlCYkonxy.Ws2.rNCJjBSAa3HZuhrK5hpYxme</span><spanclass="c1"># encrypted node password, used to retrieve JWT. Can be changed to new pass in plaintext and CLI will update/replace with encrypted pass</span>
<spanclass="nt">macaddress</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">6c:4b:91:0g:68:7b</span><spanclass="c1"># MAC of node. Used as a Unique ID</span>
<spanclass="nt">localaddress</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">192.168.1.32</span><spanclass="c1"># Address on local network, used as endpoint for other local nodes for faster comms</span>
<spanclass="nt">wgaddress</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">10.7.11.2</span><spanclass="c1"># Private WG addres on network</span>
<spanclass="nt">wgaddress6</span><spanclass="p">:</span><spanclass="s">"f8:34:41:77:5c:15"</span><spanclass="c1"># Private ipv6 address if network is dual stack</span>
<spanclass="nt">roaming</span><spanclass="p">:</span><spanclass="s">"yes"</span><spanclass="c1"># Whether or not to grab new endpoint value automatically</span>
<spanclass="nt">dnson</span><spanclass="p">:</span><spanclass="s">"no"</span><spanclass="c1"># Whether or not to set local DNS based on Netmaker's Private DNS server</span>
<spanclass="nt">islocal</span><spanclass="p">:</span><spanclass="s">"no"</span><spanclass="c1"># Based on network. If yes, will use local IP as endpoint.</span>
<spanclass="nt">isdualstack</span><spanclass="p">:</span><spanclass="s">"yes"</span><spanclass="c1"># Use IPv6 in addition to IPv4</span>
<spanclass="nt">isingressgateway</span><spanclass="p">:</span><spanclass="s">"no"</span><spanclass="c1"># whether or not node is an ingress gateway (will set iptables forwarding rules)</span>
<spanclass="nt">localrange</span><spanclass="p">:</span><spanclass="s">""</span><spanclass="c1"># local range if it's a local network. For instance, 192.168.1.0/24</span>
<spanclass="nt">postup</span><spanclass="p">:</span><spanclass="s">""</span><spanclass="c1"># postup command, used by ingress/egress gateways to set iptables</span>
<spanclass="nt">postdown</span><spanclass="p">:</span><spanclass="s">""</span><spanclass="c1"># postdown command, used by ingress/egress gateways to set iptables</span>
<spanclass="nt">port</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">51821</span><spanclass="c1"># WG port to use</span>
<spanclass="nt">keepalive</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">20</span><spanclass="c1"># default keepalive with nodes</span>
<spanclass="nt">publickey</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">8/q9cOg7c9QjnoXygVrY/VNE197VMRadJodkb1ZsujA=</span><spanclass="c1"># public key of node to show to other nodes</span>
<spanclass="nt">privatekey</span><spanclass="p">:</span><spanclass="s">""</span><spanclass="c1"># private key, set only for changing and then will revert to blank in config</span>
<spanclass="nt">endpoint</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">78.170.22.168</span><spanclass="c1"># public endpoint for reaching node </span>
<spanclass="nt">postchanges</span><spanclass="p">:</span><spanclass="s">"false"</span><spanclass="c1"># if true, will post and config file changes on next checkin and then revert to false</span>
<spanclass="nt">ipforwarding</span><spanclass="p">:</span><spanclass="s">"yes"</span><spanclass="c1"># set ip forwarding; highly recommended to leave on</span>
<spanclass="nt">isstatic</span><spanclass="p">:</span><spanclass="s">"no"</span><spanclass="c1"># if yes, daemon will not change pubkey, endpoint, or address</span>
<spanclass="nt">udpholepunch</span><spanclass="p">:</span><spanclass="s">"yes"</span><spanclass="c1"># run UDP hole punching (will ignore port above, e.g. 51821)</span>
<spanclass="nt">network</span><spanclass="p">:</span><spanclass="l l-Scalar l-Scalar-Plain">home</span><spanclass="c1"># the network (duplicate of node.network)</span>
<spanclass="nt">daemon</span><spanclass="p">:</span><spanclass="s">"yes"</span><spanclass="c1"># whether or not to manage systemd</span>
<p>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.</p>
<p>An admin creates a token in the ACCESS KEYS section of the UI. Upon creating a token, it generates 3 values:</p>
<p><strong>Access Key:</strong> The secret key to authenticate as a node in the network</p>
<p><strong>Access Token:</strong> The secret key plus information about how to access the server (addresses, ports), all decoded by the netclient to register with the server</p>
<p><strong>Install Command:</strong> A short script that will obtain the netclient binary, register with the server, and join the network, all in one</p>
<p>For first time installations, you can run the Install Command. For additional networks, simply run <codeclass="docutils literal notranslate"><spanclass="pre">netclient</span><spanclass="pre">join</span><spanclass="pre">-t</span><spanclass="pre"><access</span><spanclass="pre">token></span></code>. 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).</p>
<dt><strong>to view all logs</strong></dt><dd><p><codeclass="docutils literal notranslate"><spanclass="pre">journalctl</span><spanclass="pre">-u</span><spanclass="pre">netclient@<net</span><spanclass="pre">name></span></code></p>
</dd>
<dt><strong>to get most recent log run</strong></dt><dd><p><codeclass="docutils literal notranslate"><spanclass="pre">systemctl</span><spanclass="pre">status</span><spanclass="pre">netclient@<net</span><spanclass="pre">name></span></code></p>
<h3id="adding-removing-networks">Adding/Removing Networks<aclass="headerlink"href="#adding-removing-networks"title="Permalink to this headline">¶</a></h3>
