# Advanced Netclient 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 other 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 of 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. ## Note on MTU Settings IPv6 requires a minimum MTU of 1280. A lot of router configurations expect a standard MTU setting. You can adjust the MTU to whatever fits your needs, but setting the MTU below the standardized 1280 may cause wireguard to have issues when setting up interfaces with some systems like Windows. ## 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 " dir=in action=allow protocol=ANY remoteip= ``` 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 (Professional Edition Feature) from Netmaker GUI. To achieve this, a netmaker pro edition is required. Running netclient commands If running the netclient manually (“netclient install”, “netclient join”, “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. Changing network profile to private By default, the netmaker network profile is added as a public network. This is the default behaviour on Windows. To change it to private, please run the Powershell command: ``` Set-NetConnectionProfile -InterfaceAlias 'netmaker' -NetworkCategory 'Private' ``` Issue after Windows sleep/hibernate Sometimes the netclient does not work after the Windows wake up from sleep/hibernation. The root cause is not identified. Restarting the netclient service can fix the issue. Irregular netclient restart on Windows 2016 server There is one issue reported on the Windows 2016 server. The netclient restarted irregularly. The root cause is not identified. However, as per the feedback from the client, the issue can be fixed by disabling the ISATAP adapter and 6to4 feature: ``` Set-Net6to4configuration -state disabled Set-Netisatapconfiguration -state disabled Set-NetTeredoConfiguration -type disabled ``` Event id 0 in Windows Event logs netclient service is delegated to Winsw on Windows. An issue is reported that the stop/start/restart events in Event logs show the event ID as 0 always. It does not impact any netclient functions. ## 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 Remote Access Clients (previously 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 architectures. 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 :53. However, beware, as netmaker sets split DNS, the system must be configured properly. Otherwise, this nameserver may break your local DNS. ## Prerequisites To obtain the netclient, go to the GitHub 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) Please refer to the Firewall Rules for Machines Running Netclient for more information: ## Configuration The CLI has information about all commands and variables. This section shows the “help” output for these commands as well as some additional references. ### CLI Reference Run: ``` sudo netclient --help ``` ```plaintext NAME: Netclient CLI - Netmaker's netclient agent and CLI. Used to perform interactions with Netmaker server and set local WireGuard config. USAGE: netclient [command] COMMANDS: completion Generate the autocompletion script for the specified shell connect connect to a netmaker network daemon netclient daemon disconnect disconnet from a network help Help about any command install install netclient binary and daemon join join a network leave leave a network list display list of netmaker networks pull get the latest host configuration push push host config to server register register to a Netmaker instance server server commands [list, switch, leave] uninstall uninstall netclient use use a specific version of netclient version Displays version information Flags: -h, --help help for netclient -v, --verbosity int set logging verbosity 0-4 Use "netclient [command] --help" for more information about a command. ``` Run: ``` sudo netclient join --help ``` ```shell join a netmaker network using: token: netclient join -t // join using token server: netclient join -s // join a specific server via SSO if Oauth configured net: netclient join -s -n // attempt to join specified network via auth all-networks: netclient join -s -A // attempt to register to all allowed networks on given server via auth user: netclient join -s -u // attempt to join/register via basic auth NAME: netclient join - Join a Netmaker network. USAGE: netclient join [flags] OPTIONS: -A, --all-networks attempts to join/register to all available networks to user -e, --endpoint-ip string sets endpoint on host -h, --help help for join -m, --mtu string sets MTU on host -o, --name string sets host name -n, --net string network to attempt to join/register to -p, --port int sets wg listen port -s, --server string server for attempting SSO/Auth registration -i, --static flag to set host as static -t, --token string enrollment token for joining/registering -u, --user string user name for attempting Basic Auth join/registration GLOBAL OPTIONS: -v, --verbosity int set logging verbosity 0-4 ``` Run: ``` sudo netclient push --help ``` ```plaintext push netclient host configuration using: NAME: netclient push - Pushes custom host configuration. USAGE: netclient push [flags] OPTIONS: -e, --endpoint-ip string sets endpoint on host -h, --help help for push -m, --mtu int sets MTU on host -o, --name string sets host name -p, --port int sets wg listen port -i, --static flag to set host as static GLOBAL OPTIONS: -v, --verbosity int set logging verbosity 0-4 ``` ## Installation To install netclient and join a network, you need to use the netclient install command and get an enrollment key for a particular network from netmaker. An admin creates an enrollment key in the “Enrollment Keys” section of the UI. Upon creating a key, it can be viewed by clicking on the key from the UI. Some details regarding the key will be visible: * Key: The enrollment key to join and authenticate to a netmaker network * Type: The type of key determines the usage limitation of a particular key. Possible values are: Unlimited, Time Bound, Limited Number of Uses * Expires at: Shows the expiration date of the particular enrollment key * Networks: Shows which netmaker networks can be joined by using the particular enrollment key * Install Command: The CLI command to register with the server using the enrollment key, and join the networks {% stepper %} {% step %} ### Obtain an enrollment key An admin creates an enrollment key in the “Enrollment Keys” section of the Netmaker UI. Copy the enrollment key or the provided install command. {% endstep %} {% step %} ### Run the install command For first-time installations, run the Install Command (provided in the UI) which registers the host with the Netmaker server and installs the netclient. {% endstep %} {% step %} ### Join additional networks For additional networks, use: ``` netclient join -t ``` You may set any of the available flags documented by `netclient join --help` to override settings when joining. {% endstep %} {% endstepper %} ## Managing Netclient Connect / Disconnect * To disconnect from a network previously joined (without leaving the network): ``` netclient disconnect ``` * To connect with a network previously disconnected: ``` netclient connect ``` 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, try restarting the daemon, or pulling changes directly (don’t do both at once): ``` systemctl restart netclient sudo netclient pull ``` Adding/Removing Networks ``` netclient join -t ``` Set any flags from `netclient join --help` to override settings for joining the network. Uninstalling ``` netclient uninstall ``` ## Troubleshooting and Notes * Windows: Run netclient.exe as Administrator from PowerShell. * Windows firewall: Use netsh to allow inbound peer IPs if needed. * High CPU on Windows: Close the WireGuard GUI app if present. * Sleep/hibernate issues on Windows: Restart netclient service to recover. * Windows 2016 restart issue: Try disabling ISATAP/6to4/Teredo as above. * Event ID 0 in Windows Event logs: This is cosmetic and does not impact functionality. ## References * Netclient releases: * Firewall rules for machines running netclient: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://learn.netmaker.io/getting-started/server-and-client-management/client-installation/netclient-installation/advanced-netclient-installation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.