Netclient Installation

As of v0.18.0 Netclient is now in its own standalone repo separate from netmaker.

Netclient is a tool for managing WireGuard connections on client devices (nodes) within a network. It operates as a system daemon, facilitating secure tunneling and communication. This document details the installation, configuration, and uninstallation processes for various operating systems.

Prerequisites

Supported Operating Systems

• Linux (most distributions)

• Windows

• macOS

• FreeBSD

For unsupported devices, please use the Remote Access Client config. This is a standard WireGuard configuration file that can be easily added to any device that supports WireGuard.

Basic Requirements

• Access Token: You'll need a token to join a network after installation.

• System Permissions: Administrative or root access for installation commands and daemon management.

Software Dependencies (if applicable)

• For Docker: Ensure Docker is installed on your machine if you plan to run Netclient in a Docker container.

Firewall Configuration

Ensure that, at minimum, outbound port 443 (UDP and TCP) is allowed. Inbound port 443 should be open as well if at all possible. Optionally, open 51821 UDP and TCP, which acts as a fallback port if 443 is unavailable.

Installation

Before adding the machine to a network, the netclient must be installed. A successful installation sets up the netclient executable on the machine and adds it as a system daemon. The daemon will listen for changes for any network it joins.

The client install does not add the client as a member of any network. Once the client is installed, you must run:

netclient join -t <token>

The following are install instructions for most operating systems.

Linux

Debian Distros (debian/ubuntu/mint/pop-os)

curl -sL 'https://apt.netmaker.org/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/netmaker-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/netmaker-keyring.gpg] https://apt.netmaker.org stable main" | sudo tee /etc/apt/sources.list.d/netclient.list
sudo apt update
sudo apt install netclient

Red Hat Distros (fedora/redhat/centos/rocky)

curl -sL 'https://rpm.netmaker.org/gpg.key' | sudo tee /tmp/gpg.key
curl -sL 'https://rpm.netmaker.org/netclient-repo' | sudo tee /etc/yum.repos.d/netclient.repo
sudo rpm --import /tmp/gpg.key
sudo dnf check-update
sudo dnf install netclient

Arch Distros (arch/manjaro/endeavouros)

yay -S netclient

OpenSUSE (tumbleweed/leap)

sudo rpm --import https://rpm.netmaker.org/gpg.key
curl -sL 'https://rpm.netmaker.org/netclient-repo' | sudo tee /etc/zypp/repos.d/netclient.repo
sudo zypper refresh
sudo zypper install netclient

Windows

Bundled Installer

Download Link: https://fileserver.netmaker.org/releases/download/latest/netclientbundle.exe

To install via command line:

.\netclientbundle.exe quiet

macOS

Brew Install

brew tap gravitl/netclient
# (optional) brew audit netclient
brew install netclient

Installer

Download Link for Apple silicon: https://fileserver.netmaker.org/releases/download/latest/Netclient-M1.pkg

Download Link for Apple Intel: https://fileserver.netmaker.org/releases/download/latest/Netclient-Intel.pkg

Docker

You can run Netclient using Docker instead of installing it on your local machine.

Install Docker and docker-compose (example for Debian/Ubuntu):

sudo apt-get update
sudo apt-get install -y docker.io docker-compose

To join a network using docker run (token available from the Netmaker UI access key view):

docker run -d --network host --privileged -e TOKEN=<TOKEN> -v /etc/netclient:/etc/netclient --name netclient gravitl/netclient:<CURRENT_VERSION>

To have the container restart after reboots, include:

--restart=always

Example docker-compose (host networking):

version: "3.4"

services:
    netclient:
        network_mode: host
        privileged: true
        restart: always
        environment:
            - TOKEN=<networktoken>
            - PORT=<wg interface port>
            - ENDPOINT=<endpoint ip>
            - MTU=<mtu>
            - HOST_NAME=<host name>
            - IS_STATIC=<static host (true/false)>
        volumes:
            - '/etc/netclient:/etc/netclient'
        container_name: netclient
        image: 'gravitl/netclient:latest'

If running multiple netclient containers on one host, do not use host networking and use separate volume paths and IFACE_NAME/HOST_NAME to avoid conflicts. Example:

version: "3.4"

services:
    netclient:
        privileged: true
        network_mode: host
        restart: always
        environment:
            - TOKEN=<networktoken>
            - PORT=<wg interface port>
            - ENDPOINT=<endpoint ip>
            - MTU=<mtu>
            - HOST_NAME=nc-docker-2
            - IS_STATIC=<static host (true/false)>
            - IFACE_NAME=netmaker-2
        volumes:
            - '/etc/netclient2:/etc/netclient'
        container_name: netclient2
        image: 'gravitl/netclient:latest'

Important: For docker netclient to function correctly as either remote access/egress gateway, run these commands on the host:

iptables -I DOCKER-USER -i netmaker -j ACCEPT
iptables -I DOCKER-USER -o netmaker -j ACCEPT

Note: If a bare-metal netclient is already installed on the host, running a containerized netclient with host networking can cause conflicts. Use separate volumes and disable host networking to run multiple netclients on the same host.

Managing Netclient

Joining a Network

The join command provides flags for various options.

With a token:

netclient join -t <token>

To use a desired port:

netclient join -t <token> --static-port -p 51821

With username/password:

netclient join -n <net name> -u <username> -s api.<netmaker domain>
# example: netclient join -n mynet -u admin -s api.nm.example-domain.io

With SSO (oauth must be configured):

netclient join -n <net name> -s api.<netmaker domain>

With docker:

docker run -d --network host --privileged -e TOKEN=<TOKEN> -v /etc/netclient:/etc/netclient --name netclient gravitl/netclient:<CURRENT_VERSION>

If running a docker netclient alongside an existing bare-metal netclient, you may need to set HOST_NAME and IFACE_NAME and use separate volumes:

docker run -d --network host --privileged -e TOKEN=<TOKEN> -e HOST_NAME=nc-docker-2 -e IFACE_NAME="netmaker-2" -v /etc/netclient2:/etc/netclient --name netclient2 gravitl/new-netclient:<CURRENT_VERSION>

You can set verbosity level (0-4) when joining:

netclient join -t <token> -v <0-4>

Connecting / Disconnecting from a network

From the CLI:

netclient connect <network_name>
netclient disconnect <network_name>

You can also disconnect/reconnect from the Netmaker UI by selecting the node, editing it, and toggling the Connected switch.

Leaving a network

From the CLI:

netclient leave <network>

Or use the leave network button in the network details in the UI.

List Networks

netclient list

Multi-Server

List servers the client is registered with:

netclient server list

Switch between servers (warning: switching disconnects netclient from all networks on the current server):

netclient server switch <server name>

Leave a server completely (warning: removes the host from all networks on the server and deletes the host from the server; to reconnect you must join or register):

netclient server leave <server name>

Use a different version

Choose a specific netclient version (available v0.18.0+):

netclient use <version>

Netclient also has an auto-update feature as of v0.18.0.

Uninstalling

Leave any networks:

netclient leave <network>

Uninstall from CLI:

netclient uninstall

Uninstall using package manager (example):

apt remove netclient

macOS:

• Delete the Netclient app from Applications, or if installed via Homebrew:

brew uninstall netclient

Windows:

• Remove via “Add or remove programs” in system settings.