# 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:

```bash
netclient join -t <token>
```

The following are install instructions for most operating systems.

## Linux

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

```bash
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)

```bash
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)

```bash
yay -S netclient
```

### OpenSUSE (tumbleweed/leap)

```bash
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:

```powershell
.\netclientbundle.exe quiet
```

## macOS

### Brew Install

```bash
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):

```bash
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):

```bash
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):

```yaml
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:

```yaml
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:

```bash
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:

```bash
netclient join -t <token>
```

To use a desired port:

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

With username/password:

```bash
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):

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

With docker:

```bash
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:

```bash
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:

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

### Connecting / Disconnecting from a network

From the CLI:

```bash
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.

![](https://1465744049-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqMcN3gvfPLhO0hh4agC%2Fuploads%2FzpdGOyb0lRLCDAyK5FIu%2Fn1.png?alt=media\&token=570b9c2b-e3d9-4b48-b94a-b06771240365)

### Leaving a network

From the CLI:

```bash
netclient leave <network>
```

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

### List Networks

```bash
netclient list
```

### Multi-Server

List servers the client is registered with:

```bash
netclient server list
```

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

```bash
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):

```bash
netclient server leave <server name>
```

### Use a different version

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

```bash
netclient use <version>
```

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

## Uninstalling

Leave any networks:

```bash
netclient leave <network>
```

Uninstall from CLI:

```bash
netclient uninstall
```

Uninstall using package manager (example):

```bash
apt remove netclient
```

macOS:

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

```bash
brew uninstall netclient
```

Windows:

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


---

# 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.md?ask=<question>
```

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.