# Getting Started

Helpful resources to get you started on your journey with Netmaker.

<figure><picture><source srcset="/files/NDSeECMYB2Cu2QtlNvT4" media="(prefers-color-scheme: dark)"><img src="/files/Unb3y9LUSobLls3CDvI1" alt="" width="375"></picture><figcaption></figcaption></figure>

{% embed url="<https://www.youtube.com/watch?v=tRkV6j1pUss>" fullWidth="false" %}

## Welcome to Netmaker

Netmaker is a Zero Trust networking platform designed to give you maximum control over virtual networks, for use cases like remote access, overlays, and site-to-site. The platform is fast, robust, and secure, utilizing the latest in encryption from WireGaurd.

&#x20;Below, find some great resources to help you get started on your journey.

Or if you're looking for something specific, try asking our new AI-powered answers, which can provide step-by-step guidance.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">How can I get started with Netmaker?</button>

## Getting Started

{% columns %}
{% column width="50%" %}
{% content-ref url="/pages/36963c9ece2f1bae9517c79fcc775c59e29651ca" %}
[About](/getting-started/about)
{% endcontent-ref %}
{% endcolumn %}

{% column width="50%" %}
{% content-ref url="/pages/acc7c9a179ab73ad4563ff9c6ceea18c49cc63f7" %}
[Quick Start](/getting-started/quick-start)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
{% content-ref url="/pages/f28160b6e908750cd81b8bb7dd839b980aba6749" %}
[Walkthrough](/getting-started/walkthrough)
{% endcontent-ref %}
{% endcolumn %}

{% column %}
{% content-ref url="/pages/1a4ed7d6644f06ea871154d7789286aa1104797a" %}
[Features](/features)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
{% content-ref url="/pages/IwF9A2Ff5VdtyS5IzjL1" %}
[Server and Client Management](/getting-started/server-and-client-management)
{% endcontent-ref %}
{% endcolumn %}

{% column %}
{% content-ref url="/pages/e80fff41d834fbac63321845d0e27d19a80f999d" %}
[Operations Field Guide](/getting-started/operations-field-guide)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}


# About

<picture><source srcset="/files/NDSeECMYB2Cu2QtlNvT4" media="(prefers-color-scheme: dark)"><img src="/files/Unb3y9LUSobLls3CDvI1" alt="" width="375"></picture>

## What is Netmaker?

Netmaker is an open-source, Zero Trust networking platform built on **WireGuard®,** designed to connect devices, servers, containers, and users across any environment. It automates the creation and management of secure overlay networks, helping teams reduce complexity, improve performance, enhance security, and **scale seamlessly to hundreds or thousands of nodes, networks, and users**.

With Netmaker, you can connect cloud, on-premises, and edge resources under a single, **encrypted network,** making distributed infrastructure feel like one unified local network.

<figure><img src="/files/AMOKHwBSCGMuyzF32q5c" alt=""><figcaption></figcaption></figure>

Netmaker creates a **flat, encrypted network** where all devices can communicate securely. From a machine’s perspective, every other node is “next door,” even if they are spread across the world.

Think of it as an **AWS VPC** for arbitrary computers — Netmaker gives you the flexibility to scale and manage multiple environments, networks, and users.

Netmaker also enables you to **control traffic flows** using:

* **Gateways** → Manage the relaying of traffic across your network, inbound user traffic, and outbound internet traffic.
* **Security & Access Policies** → Control which devices or users can communicate. Supports integration with **IDPs such as Google, Microsoft Entra ID (Azure), and Okta** for authentication, SSO, and centralized user management.
* **Egress routing** → Route traffic through selected egress nodes **based on domain(s) or IP range(s)**, giving fine-grained control over network paths.

This makes it possible to build **advanced patterns** like remote access, multi-site connectivity, and private networks.

<div><figure><img src="/files/I26wwTeMNQWz6eZ5ycn1" alt=""><figcaption></figcaption></figure> <figure><img src="/files/0KYmyeHTnnne4IewcmZF" alt=""><figcaption></figcaption></figure></div>

Netmaker has many similarities to platforms like Tailscale, ZeroTier, and NetBird. What makes Netmaker different is the speed and flexibility. Netmaker is faster because it uses kernel WireGuard. It is more flexible because it lets you build many different types and patterns of networks, and also gives you the choice of how endpoints are added to the network, with three different client-side applications. And, of course, you can also self-host Netmaker, to give you complete control of your network traffic.

## How Does Netmaker Work?

Netmaker relies on WireGuard to create **encrypted tunnels** between machines, while the platform automates configuration and routing.

### Components

Netmaker consists of several key components that work together to create a **secure, dynamic overlay network**:

{% stepper %}
{% step %}

### Netmaker Server

* Acts as the **central configuration and orchestration hub**.
* Can be **self-hosted** or deployed via **Netmaker SaaS**.
* Stores network and device configurations and **pushes updates** to all nodes automatically.
  {% endstep %}

{% step %}

### Clients

Netmaker supports multiple client types:

* **Netclient** → Headless agent for servers, IoT devices, or routing nodes. Runs on **Windows, Linux, macOS, and Docker**.
* **WireGuard Endpoints** → Pure WireGuard tunnels for any compatible device.
* **Netmaker Desktop /** **Mobile** → User-focused app for secure remote access with **authentication, authorization, and session expiry**.
  {% endstep %}

{% step %}

### Message Queue (MQ)

* Ensures **reliable communication** between the server and clients.
* Synchronizes configuration changes dynamically across the network.
  {% endstep %}

{% step %}

### DNS Service

* Provides **hostname resolution** across all nodes.
* Supports **domain-specific rules** (match specific domains) or **catch-all resolution**.
* Configurable **name-servers** can be scoped to **specific peers**, allowing fine-grained control over which devices use which DNS servers.
* Eliminates the need to memorize IP addresses and ensures predictable connectivity.
  {% endstep %}
  {% endstepper %}

The server manages network configurations, while clients report local changes (IP, ports). This enables a **fully dynamic, self-updating network**.

## Netmaker Editions

Netmaker provides a range of options tailored to suit different use cases and organizational needs. Whether you’re a small team, a growing business, or a large enterprise, Netmaker provides the right tools to improve security, efficiency, and scalability.

{% content-ref url="/pages/u41wuCUmsQEp5N4EASvX" %}
[Feature Matrix](/getting-started/feature-matrix)
{% endcontent-ref %}

### Netmaker SaaS

Hosted in the cloud and managed entirely by the Netmaker team, our SaaS provides enterprise-grade networking with minimal setup.

* Technical Highlights:
  * Automatic scaling of resources based on network usage.
  * Built-in redundancy and high availability for reliable performance.
  * Seamless updates and patches, ensuring you’re always on the latest version.
  * Managed security configurations to safeguard your data.

Netmaker SaaS is ideal for businesses and users that need rapid deployment and scalable solutions without handling infrastructure.

## Use Cases for Netmaker

There are many use cases for Netmaker. In fact, you could probably be using it right now. Because of Netmaker’s extreme speed, there is almost no cost to putting a Netmaker overlay network on top of any existing Network.

This is a sample of how some users use Netmaker in production today. Guided setup for many of these use cases can be found in the [How-To Guides](/how-to-guides) or on our [Blog](https://www.netmaker.io/blog) or [YouTube channel](https://www.youtube.com/channel/UCach3lJY_xBV7rGrbUSvkZQ).

* Automating and managing large WireGuard-based networks.
* Secure access to home or office networks.
* Remote management of servers, edge sites, robots, or drones.
* Site-to-site connectivity (e.g., customer to cloud).
* Testing and development environments with isolated, easily reconfigurable networks.
* Overlay networks for temporary projects, events, or pop-up infrastructures.
* Private IoT networking for secure device data transfer.
* Multi-cloud networking across AWS, Azure, GCP, or hybrid environments.
* Secure remote access for distributed teams and contractors.
* Connecting Kubernetes clusters across regions or cloud providers.
* Secure collaboration between branch offices and headquarters.


# Architecture

![Netmaker Architecture Diagram](/files/p2qH1wOn1CVQhgOQJOCB)

## Core Concepts

Familiarity with several core concepts will help when you encounter them later in the documentation.

### WireGuard

WireGuard is a relatively new but very important technology that was recently added to the Linux kernel. WireGuard creates very fast but simple encrypted tunnels between devices. From the [WireGuard](https://www.wireguard.com/) website, “it might be regarded as the most secure, easiest to use, and simplest VPN solution in the industry.”

Previous solutions like OpenVPN and IPSec are considerably more heavy and complex while being less performant. All existing VPN tunneling solutions will cause a significant increase in your network latency. WireGuard is the first to achieve near over-the-line network speeds, meaning you see no significant performance impact. With the release of WireGuard, there is little reason to use any other existing tunnel encryption technology.

### Mesh Network

When we refer to a mesh network in these documents we are typically referring to a “full mesh.”

![Full Mesh Network Diagram](/files/c8d66071a320d3f09a6017dd46765d266c4019ee)

A full [mesh network](https://www.bbc.co.uk/bitesize/guides/zr3yb82/revision/2) exists where each machine is able to directly talk to every other machine on the network. For example, on your home network, behind your router, all the computers are likely given private addresses and can reach each other directly.

This is in contrast to a hub-and-spoke network, where each machine must first pass its traffic through a relay server before it can reach other machines.

In certain situations, you may either want or need a partial mesh network, where only some devices can reach each other directly, and other devices must route their traffic through a relay/gateway. Netmaker can use this model in some use cases where it makes sense. In the diagram at the top of this page, the setup is a partial mesh because the servers (nodes A-D) are meshed, but then remote users come in via a gateway and are not meshed.

Mesh networks are generally faster than other topologies but are also more complicated to set up. WireGuard on its own gives you the means to create encrypted tunnels between devices, but it does not provide a method for setting up a full network. This is where Netmaker comes in.

### Netmaker

Netmaker is a platform built off of WireGuard enabling users to create full and partial mesh networks between their devices, setting up routes directly between peers, or gateways into and out of the network.

When we refer to “Netmaker”, we are typically referring to the Netmaker “server”, which is the coordination and configuration server for your networks.

From an admin perspective, they typically interact with the Netmaker Dashboard, while other components running the server are in the background.

Netmaker does a lot of work to set configurations for you so that you don’t have to. This includes things like WireGuard ports, endpoints, public IPs, keys, and peers. Netmaker works to abstract away as much of the network management as possible, so that you can just click to create a network, and click to add machines to networks. That said, every machine (node) is different, and may require special configuration. That is why, while Netmaker sets practical default settings, everything within Netmaker is fully configurable.

### Node

A device in a Netmaker network, which is running WireGuard. Either managed via our headless agent (netclient), by our user app (Netmaker Desktop / Mobile), or pure WireGuard. A Node can be a VM, a bare metal server, a desktop computer, a laptop, phone, an IoT device, or any other number of internet-connected devices. However, the client you use to attach the node will depend on the device type and use case. A node is simply an endpoint in the network, which can send traffic to other nodes, and receive traffic from other nodes (based on access controls).

## Components

Netmaker consists of several core components, which are explained in high-level technical detail below.

### Netmaker Server

The Netmaker server is, at its core, a golang binary. Source code can be found [on GitHub](https://github.com/gravitl/netmaker). The binary, by itself, can be compiled for most systems. If you need to run the Netmaker server on a particular system, it likely can be made to work. In typical deployments, it is run as a Docker container. It can also be run as a systemd service as outlined in the non-docker install guide.

The Netmaker server acts as an API to the front end and publishes messages to clients via an MQ broker. The Netmaker server also runs an embedded “netclient” for each network that is created. This is a special netclient that enabled “UDP Hole Punching” on the system. When nodes reach the server, Netmaker uses this netclient to determine a routable address for each machine, and sends this out to the network.

Most server settings are configurable via a config file, or by environment variables (which take precedence). If the server finds neither of these, it sets sensible defaults, including things like the server’s reachable IP, ports, and which “modes” to run in.

The Netmaker server interacts with either SQLite (default), postgres, or rqlite, a distributed version of SQLite, as its database. This DB holds information about nodes, networks, users, and other important data. This data is configuration data.

When the netmaker server needs to send an update to nodes, it publishes a message to the broker, MQ.

The components of the server are usually proxied via Traefik or an alternative like Nginx or Caddy. The proxy handles SSL certificates to secure traffic, and routes to the UI and API.

### Message Broker (Mosquitto)

The Mosquitto broker is the default MQTT broker that ships with Netmaker, though technically, any MQTT broker should work so long as the correct configuration is applied. The broker enables the establishment of a pub-sub messaging system, whereby clients subscribe to receive updates. When the server receives a change, it will publish that change to the broker that pushes out the change to the appropriate nodes.

The broker must be reachable over a public address.

### Netclient

The netclient is, at its core, a golang binary. Source code can be found in the Netclient [GitHub Repository](https://www.github.com/gravitl/netclient). The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems.

The netclient can be installed in one of two way: using package manager for your os/DE or by downloading the binary for your operating system/architecture from the netclient github repository and running ./netclient install.

After installation netclient commands can be executed to ‘join’ or ‘register’ with the netmaker server.

The ‘join’ and ‘register’ command attempts to add the machine to the Netmaker network using sensible defaults, which can be overridden with a config file or environment variables. Assuming the netclient has a valid key (or the network allows manual node signup), it will be registered into the Netmaker network, and will be returned necessary configuration details for how to set up its local network.

The netclient automatically registers with the MQTT server running with Netmaker, which will send it periodic updates when the network changes.

The netclient then sets up the system daemon (if running in daemon mode), and configures WireGuard. At this point, it should be part of the network.

The netclient will detect local changes and send them to the server when necessary. A change to IP address or port will lead to a network update to keep everything in sync. If the node is not running with the in daemon on, it is up to the operator to keep the netclient up-to-date by running regular “pulls” (netclient pull).

The MQ pub-sub system allows Netmaker to create dynamic mesh networks. As nodes are added to, removed from, and modified on the network, other nodes are notified and make appropriate changes.

### Database (SQLite, rqlite, postgres)

Netmaker uses embedded SQLite as the default database. It can also use PostgreSQL, or rqlite, a distributed (RAFT consensus) database. Netmaker interacts with the database to store and retrieve information about nodes, networks, and users.

Additional database support (besides SQLite and rqlite) is very easy to implement for special use cases. Netmaker uses simple key-value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.

### Netmaker UI

The Netmaker UI is a ReactJS-based static website which can be run on top of standard webservers such as Apache and Nginx. Source code can be found [here](https://github.com/gravitl/netmaker-ui-2). In a typical configuration, the Netmaker UI is run on Nginx as a Docker container.

Netmaker can be used in its entirety without the UI, but the UI makes things a lot easier for most users. It has a sensible flow and layout for managing Networks, Nodes, Access Keys, and DNS.

### Caddy

As of 0.17.0, Caddy is the default proxy for Netmaker if you set it up via Quick Start. Caddy is a simple and docker-friendly proxy, which can be compared to Nginx, Traefik, or HAProxy.

Caddy simplifies management because the configuration file is very short, several lines compared to dozens of lines for Traefik or Nginx. In addition, it can request certificates automatically.

Traefik was previously the default and is still a functioning option, but We are moving guidance towards Caddy by default. If you are maintaining an installation that relies on Traefik, you can continue to use it with Netmaker.

### DNS

#### Managed DNS in Netmaker

Managed DNS is an integral feature of the Netmaker system. This feature allows devices to communicate using **domain names** instead of IP addresses, streamlining network management and enhancing usability, especially in larger or more dynamic environments. Managed DNS is **supported on Windows, macOS, and Linux.** Here's how it works:

* Domain Name Format\
  Each device in the network will be assigned a domain name in the format `<device-name>.<network-name>`. For example, `deviceA.networkA`.
* Netclient Configuration\
  No manual configuration is needed on the netclient side. During startup, the netclient will automatically detect Managed DNS and configure the DNS components.
* Static Nodes Configuration\
  Managed DNS can also be used with static nodes; Netmaker automatically populates the WG config file with the correct DNS information.

By using Managed DNS, devices within your Netmaker network will communicate more intuitively and efficiently, making network management and device identification much easier.

#### Adding DNS Name-Servers

In addition to Managed DNS, you can also configure **DNS servers** to resolve external/internal domain names. This helps devices in your network access external domains/internal domains. Some common DNS servers include:

* **Google DNS**: `8.8.8.8`
* **Cloudflare DNS**: `1.1.1.1`
* **Quad9 DNS**: `9.9.9.9`

<figure><img src="/files/RsY8WLS2YSj2uVYmEBE1" alt=""><figcaption></figcaption></figure>

### Netmaker Apps for Secure Access

Netmaker offers both a [Desktop App](https://www.netmaker.io/download) (available for Windows, macOS, and Linux) and a [Mobile App](https://www.netmaker.io/download) (for iOS and Android) to make it easy for end users to securely connect to private networks. Once installed, users can sign in using their email or social accounts, and immediately see the networks and gateways they have access to—no need to deal with manual configuration or command-line tools. The interface is straightforward, showing available gateways and their types (like internet gateways for full traffic routing), and users can connect or disconnect with a single click. To maintain security, sessions automatically expire after a set period of inactivity, helping prevent unauthorized access if a device is left unattended. Whether you're accessing internal resources from home, traveling, or working in the field, Netmaker apps offer a consistent, secure, and hassle-free way to stay connected.

## Technical Process

Below is a high level, step-by-step overview of the flow of communications within Netmaker (assuming Netmaker has already been installed):

{% stepper %}
{% step %}

### Create network

Admin creates a new network with a subnet, for instance, 10.10.10.0/24
{% endstep %}

{% step %}

### Create registration key

Admin creates a registration key for signing up new nodes
{% endstep %}

{% step %}

### API routing

Both of the above requests are routed to the server via an API call from the front end
{% endstep %}

{% step %}

### Install netclient and join

Admin installs the netclient binary on any given node (machine) and runs netclient join or register command.
{% endstep %}

{% step %}

### Key decoding

Netclient decodes key, which contains the server location
{% endstep %}

{% step %}

### Local setup

Netclient gathers and sets appropriate information to configure itself as a node: it generates key pairs, gets public and local addresses, and sets a port.
{% endstep %}

{% step %}

### Send info to server

Netclient sends this information to the server, authenticating with its registration key
{% endstep %}

{% step %}

### Server verifies and creates node

Netmaker server verifies information and creates the node, setting default values for any missing information, and returns a response.
{% endstep %}

{% step %}

### Register with MQ

Netmaker also registers the client with MQ.
{% endstep %}

{% step %}

### Pull peers and setup WireGuard

Upon successful registration, Netclient pulls the latest peers list from the server and sets up a WireGuard interface.
{% endstep %}

{% step %}

### Subscribe to broker

Netclient subscribes to the MQ broker.
{% endstep %}

{% step %}

### Configure daemon

Netclient configures itself as a daemon (if joining for the first time).
{% endstep %}

{% step %}

### Monitor local changes

Netclient regularly retrieves local information, checking for changes in things like IP and keys. If there is a change, it pushes them to the server.
{% endstep %}

{% step %}

### Reconfigure on updates

If a change occurs in any other peer or peers are added/removed, an update will be sent to the Netclient via MQ, and it will re-configure WireGuard.
{% endstep %}
{% endstepper %}

## Compatible Systems for Netclient

To manage a node manually, the netclient can be compiled and run for most Linux distributions, with a prerequisite of WireGuard with kernel headers. If the netclient from the release pages does not run natively on your system, you may need to compile the netclient binary directly on the machine from the source code. This may be true for some installations of SUSE, Fedora, and some Debian-based systems. However, if the dependencies are installed on the machine, the netclient should run correctly after being compiled.

Simply clone the repo, cd to netmaker/netclient, and run “go build” (Golang must be installed).

The following systems should be operable natively with Netclient in daemon mode:

* Windows
* Mac
* FreeBSD
* OpenWRT
* Fedora
* Ubuntu
* Debian
* Mint
* SUSE
* RHEL
* Raspian
* Arch
* CentOS
* Fedora CoreOS

Systemd is a system service manager for a wide array of Linux operating systems, but not all Linux distributions have adopted systemd. If you need to run on a Linux distro without systemd, we recommend the following: Join “unmanaged” with netclient join -daemon=off on Linux systems that do not run systemd and use some other method to run the daemon like a cron job or custom script.

## Limitations

Install limitations mostly include platform-specific dependencies. A failed netclient install should display information about which command is failing, or which libraries are missing. This can often be solved via machine upgrade, installing missing dependencies, or setting kernel headers on the machine for WireGuard (e.x.: [Installing Kernel Headers on Debian](https://stackoverflow.com/questions/62356581/wireguard-vpn-how-to-fix-operation-not-supported-if-it-worked-before))

It is very helpful if an install fails to run “netclient join -t -v 4”. By default, the install runs with minimal logging. The -v flags will display any encountered errors. You can set the verbosity from 0-4.


# Client Types

## Netmaker Clients

Netmaker has three primary ways to add devices and users to the VPN. Each has specific uses depending on the networking scenario and target devices.

<figure><img src="/files/ZhUPOQiaTZzQFuiGs8Ic" alt=""><figcaption></figcaption></figure>

|                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong>Server Agent:</strong><br><strong>Netclient</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                      | **On-Demand User Access: Netmaker Desktop / Mobile**                                                                                                                                                                                                                                                                                                                                                                                                                                              | <p><strong>Always-On Static Config:</strong><br><strong>WireGuard Client</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                               |
| The [Netclient](broken://pages/6dd8b1ec772bcf61316d4351aec1318ab175831e) is meant to run on Linux and Windows servers that act as managed endpoints in the VPN. Servers added via the Netclient appear as **Nodes** in your dashboard, and can be configured as **gateways** to route endpoint traffic, such as Remote Access Gateways, Egress Gateway, and Relays. The netclient is an active, headless agent that runs in the background on devices, by default creating a peer-to-peer network with other netclients. | The [Netmaker Desktop and Mobile Apps](https://www.netmaker.io/download) are provided to users so they can log into the VPN from their devices (workstation, phone). Your server can be set up with either basic auth or any OIDC-compliant auth provider like Google or Azure AD, so users can log in with their credentials. After logging in, users have on-demand access to the VPN, selecting which networks they will connect to. This is how Netmaker provides **remote access** to users. | [Static WireGuard VPN config files](https://www.wireguard.com/) can be generated and customized on **Remote Access Gateways** within Netmaker. These files can be run on any device which supports WireGuard, and are typically used to integrate non-native devices such as routers and IoT devices. For access to and from sites, additional IP ranges can be added to these config files. These files can also be used to configure “always on” VPNs on user devices, managed by administrators. |

<table><thead><tr><th width="124.984375"></th><th width="207"></th><th></th><th></th></tr></thead><tbody><tr><td></td><td><strong>Netclient</strong></td><td><strong>Static WireGuard</strong></td><td><strong>User Apps</strong></td></tr><tr><td>Format</td><td>Headless Daemon</td><td>WireGuard Config File</td><td>GUI App for Desktop, Mobile</td></tr><tr><td>OS Support</td><td>Linux, Windows, Mac</td><td><a href="https://www.wireguard.com/install/">Many</a></td><td>Linux, Windows, Mac, iOS, Android</td></tr><tr><td>Connectivity</td><td><ul><li>Peer-to-Peer</li><li>Always-On</li></ul></td><td><ul><li>Via Gateway (Hub-And -Spoke)</li><li>Always-On</li></ul></td><td><ul><li>Via Gateway (Hub-And -Spoke)</li><li>On Demand or Always-On</li></ul></td></tr><tr><td>Capabilities</td><td><ul><li>Act as Hub for other Clients</li><li>Forward traffic to external envs</li></ul></td><td><ul><li>Can be used with many routers to support Site-to-Site</li><li>Deployable on any device that supports WireGuard.</li></ul></td><td><ul><li>User auth-based login</li><li>Session Expiry</li><li>GUI for Ease of Use.</li></ul></td></tr></tbody></table>


# How it Works

Netmaker automates secure WireGuard networks across any infrastructure. Follow the steps below to get your network up and running.

***

### [1. Define Networks →](#id-1.-define-networks)

### [2. Add Devices →](#id-2.-add-devices)

### [3. Configure Routing →](#id-3.-configure-routing)

### [4. Grant User Access →](#id-4.-grant-user-access)


# 0. Overview

Setting up networks in Netmaker consists of 4 stages:

{% stepper %}
{% step %}

### Create Networks

Networks are your VPNs. They are meant to separate different environments, scenarios, customers, or other use cases, and keep traffic segmented. You can define any number of distinct networks in Netmaker for any number of use cases.

![](/files/e7d7ff1973d9525d70d6efd1760b901e5d736fbf)
{% endstep %}

{% step %}

### Add Non-User Devices

Non-User Devices are the endpoints of your network. These are devices that:

* users will need to access
* need to access each other
* route traffic into, out of, or between endpoints in the VPN

Each receives a virtual address within the network.

![](/files/3a49eaf83d906f5f63a8fb7653016b467aa7bbb2)
{% endstep %}

{% step %}

### Configure Traffic Flow

After adding devices, you can determine how traffic routes between and through devices in the network. You can set up:

* Gateways into the network for users
* ACLs and Relays between devices of the network
* Gateways out of the network, to the internet or local networks
* Site-to-Site access

![](/files/5db8aa3f44fbc2168fa9114593255746b90fd259)
{% endstep %}

{% step %}

### Grant User Access

After you’ve set up your network, you can invite users, add them to groups, and set their network access permissions, allowing them to remotely access the network.

![](/files/03e2236f4a4df2b6a216032e994a410100fe7c6b)
{% endstep %}
{% endstepper %}

We’ll walk through setting up each of these, starting with networks.


# 1. Define Networks

Setting Up Your VPN Networks

## Overview

Networks are your VPNs. They are meant to separate different environments, scenarios, customers, or other use cases, and keep traffic segmented. You can define any number of distinct networks in Netmaker for any number of use cases.

A network in Netmaker has a defined subnet. All devices enrolled in the network will be assigned a virtual IP Address from this range, which is the private IP address over which encrypted traffic and communications occur between devices.

![](/files/379a451d63c731e53d16220bccdc146c18d749de)

## The Default Network

A network will usually already be set up when you log in for the first time, with the following settings:

* **Name:** netmaker
* **Subnet (ipv4):** 10.*.*.\*/24
* **Subnet (ipv6):** *:*:*\*:*\*::/64
* **Default** [**ACL**](https://www.netmaker.io/features/acls) **:** ALLOW

This is suitable for most standard use cases. In basic scenarios, you only need one network. You can always delete the default network if the settings do not suit your needs.

## How Many Networks Do You Need?

Here are a few reasons you may need or want multiple networks.

### You Manage Multiple Customers

If you work with multiple customers, you can set up multiple networks for each customer. You could also deploy multiple “tenants” aka “Netmaker servers”, but keeping everything on one server can simplify operations.

### You Have Multiple Environments or Use Cases

If you have multiple offices, clouds, testing environments, or just have vastly different use cases, you may want to manage these via different networks.

### You Want to Segment Access

If you have vastly different levels of access between user or device groups, it may be easier to segment access using multiple networks. This can also be done within a single network, but using multiple networks is often cleaner and easier to manage.

## Creating Networks

Once you have determined how many networks you need, making them is easy. Simply go to the networks page on your dashboard and click “Create a Network”:

<figure><img src="/files/qJWYDVgWj1gee1OAmCGb" alt=""><figcaption></figcaption></figure>

If you are unsure, or don’t care, about the subnets, you can simply “Autofill” the settings, which is fine for most users. However, take care to choose a network name that matches the use case. For instance, if setting up remote access to a customer’s environment, consider naming it .

It is important to note that **network settings are immutable** — you cannot change these after creation. Let’s walk through the network settings.

### Network Settings

![](/files/ed61734bf4ab773ceeb038274bac082adc24421b)

#### Network Name

The identifier of the network. You may want to consider labelling this according to the use case or environment, e.g. “my-office” or “edge-device-access”.

#### IPv4, IPv6 CIDRs

The virtual IP range(s) of the network. Usually you just need IPv4. IPv6 virtual addresses are usually not required. Devices can still use their ipv6 **public** endpoints to communicate, even if the virtual network is **ipv4**.

Follow these important rules when choosing CIDRs:

{% stepper %}
{% step %}

### Choose an appropriate network size

A /24 network (e.g. 10.10.10.0/24) will be able to include up to 254 distinct private IPs, whereas a /16 network (e.g. 10.10.0.0/16) will be able to include up to 65,534 distinct private IPs.
{% endstep %}

{% step %}

### Use a private address space

Use private address ranges to avoid conflicts with public (real world) IPs: <https://www.iana.org/help/private-addresses>
{% endstep %}

{% step %}

### Avoid overlap with local addresses

Use a private address space that does not overlap with any local addresses that may exist on your network. Example: LANs often use 192.168.*.*, so avoid that to prevent conflicts. Usually it is safe to use a private subnet with a prefix of 10.\*.
{% endstep %}
{% endstepper %}

#### Default Access Control

{% hint style="info" %}
Default Access Control determines the initial reachability assigned to hosts when they join the network.
{% endhint %}

* If set to “ALLOW”: All machines in the network can reach all other machines in the network by default. A network administrator can optionally disable connections in the “Access Controls” tab of network management.
* If set to “DENY”: No machines will be able to reach each other by default. Any machine added to the network will have no connections. A network administrator must specify which machines can reach each other in the “Access Controls” tab of network management.

![](/files/b856bd705a8c8f86f5d56c04edb071bdbb76d5ab)

## Next Steps

Once you’ve created your Network(s), it’s time to add the devices that will make up your network. See the following section on adding devices for details.


# 2. Add Devices

Adding Target Devices to act as Endpoints and to Forward Traffic for the Network

## Overview

Non-User devices are the devices that act as endpoints and routing nodes of the network. They are either the machines you wish to reach, or machines through which you will route traffic. Typically these are servers and routers.

![](/files/3a49eaf83d906f5f63a8fb7653016b467aa7bbb2)

Non-User devices can be added to the network in two ways:

* Using the Netclient
* Using WireGuard config files

## Adding Devices with the Netclient

The Netclient is supported on Linux, Docker, Windows, and MacOS. If a device runs one of these operating systems, it should be added using this approach.

Once a device is added to a network using the Netclient, it appears as a “Node.”

{% stepper %}
{% step %}

### Create an Enrollment Key

<figure><img src="/files/yxfSAM2Iu0BcVMrSU8Cl" alt=""><figcaption></figcaption></figure>

Keys determine which network a netclient will be able to access when it joins the server. If you are using the default network, there will be a pre-defined key you can use to join the network. Otherwise, go to the **Enrollment Keys** menu item to create a new key.

* **Name:** an identifier for the key
* **Type:** Define the number of uses (or for how long) the key is valid, to limit access
* **Networks:** The networks this key will grant access to
* **Relay:** If your network has a relay defined, add machines to it automatically.

{% hint style="info" %}
You can create an enrollment key **without** any network access. This will allow devices to enroll with your server, and an administrator can choose which networks they should have access to. This is helpful for use cases where you may want to allow unknown devices to register with your network, and allow an administrator to review before granting access to the VPN.
{% endhint %}
{% endstep %}

{% step %}

### Add Devices

In the **Nodes** screen of your network, click “add a new node”. This will give you instructions for installing the netclient and joining the network with the enrollment key.

#### Select an Enrollment Key

You can select the key from the previous step, or create a new one in the menu.

#### Install Netclient

Choose the target platform, and follow the installation steps for the netclient.

![](/files/u2GLcIZGQdyC6Ynuwesn)
{% endstep %}

{% step %}

### Join Network

Once the netclient is installed locally, join the server using the enrollment key and provided command.

![](/files/P0WczbMQzzAZsB0e1LGv)

{% hint style="info" %}
You can deploy multiple docker netclient containers on a single machine, but need to have distinct volume mounts and names. If you wish to do this, just increment the name and volume mounts like this:

```bash
sudo docker run -d --network host --privileged -e TOKEN=xxxx-v /etc/netclient:/etc/netclient-<x> --name netclient-<x> gravitl/netclient:v0.25.0
```

{% endhint %}
{% endstep %}
{% endstepper %}

## Adding Devices with WireGuard

For devices that do not support the Netclient, such as Routers and IoT devices, you can create WireGuard config files which can be run using any flavor of WireGuard on the device. This consists of four simple steps:

{% stepper %}
{% step %}

### Add a New Node

![](/files/oRHB0XMNZetA02wpqTsj)
{% endstep %}

{% step %}

### Choose Config Files Option

Choose the config files option, specify the node name, and select your gateway.

![](/files/P9NbvT5nK7LbNaBnzePN)

Even if your node is not configured as a Gateway in the Gateway list, it will be automatically created during this process.
{% endstep %}

{% step %}

### Select Config Files Filter and Download

Select Config files filter and click on your WG config file to download the WG configuration you created for the target device.

![](/files/ChdH5yXXaFWSMZkhraaE)
{% endstep %}

{% step %}

### Run WireGuard Config on the Target Device

Run the WireGuard configuration on the target device.
{% endstep %}
{% endstepper %}

Another option is to create the WG config client through the Gateways interface by following these steps:

1. Define a Gateway on your network
2. Generate a config file on the Gateway
3. Install WireGuard on the target device
4. Run the WireGuard configuration on the target device

### Define a Gateway and Create a wg config file

<figure><img src="/files/kIltNGDLsU8DnjWeBLjy" alt=""><figcaption></figcaption></figure>

### Generate WireGuard Config Files

Once you have a Gateway, you can generate config files on the gateway, which can be applied to any device. The gateway will forward traffic between the WireGuard client and the VPN network.

1. Click “Create Config”
2. Enter a Client ID to identify the device

<figure><img src="/files/7aP9khbrlr4kVgKejL6P" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For Routers: Under Advanced Settings, there is a field for Additional Addresses. If you are planning to put this config file on a device that acts as a router to a local network, specify the reachable local addresses here (for instance, a LAN with a subnet of 192.168.1.0/24). On the target device, you will need to add forwarding rules for the local network, but then your VPN will be able to reach the local network via this config file.
{% endhint %}

After creating the file, you can view, scan the QR code, copy, and download the file by clicking on it.

<figure><img src="/files/zTrSgHQRHnDZrrBI4RcT" alt=""><figcaption></figcaption></figure>

### Install WireGuard on Target Devices

Follow the steps at <https://www.wireguard.com/install/> to install WireGuard on the target device. For Routers, there is likely a WireGuard plugin that can be installed.

### Run WireGuard Config File on Target Devices

Download the created config file to the target device and run it using WireGuard. Depending on the way WireGuard is installed, you may need to enter the fields manually. For example, with router plugins, you will need to specify a new WireGuard interface, and enter the fields for the Address, the PrivateKey, and Peer manually.

After this is done, the device should have access to and from the VPN.

## Next Steps

After all Non-User devices have been added to the network, you may want to define some additional routing into, out of, and between devices in the network, which we will do next (and before granting users access).


# 3. Configure Routing

Getting Traffic Into, Out Of, and Between Devices in your Network

### Overview

Netmaker allows you to shape the way traffic routes into, out of, and between devices in the network. Here, we’ll show you some of these settings, depending on the type of network you wish to create.

![](/files/5db8aa3f44fbc2168fa9114593255746b90fd259)

Here is a quick overview of the routing features you may wish to use:

* Into the Network
  * Gateway: This was discussed in the previous section for generating static WireGuard config files. It is also how Users are granted access to the network, so at least one Gateway must be deployed for user access.
* Between Devices
  * Failover Node: A failover node is a device that will automatically route traffic between other devices if it detects that traffic is not flowing correctly.
  * Relay Node: A relay is a device that is set to always route traffic to and from a specified device. This should be used when a device is deployed in a very restrictive, unreliable, or roaming environment, ensuring it remains reachable at all times.
  * ACL Rules: ACL rules can be configured to specify which devices are allowed to communicate with one another. You simply enable or disable access between specific devices in the network.
* Out of the Network
  * Egress: Egress is configured on a device that routes traffic to a local network or specific IPs outside of the VPN, such as a LAN, VPC, or IoT devices on an edge network.
  * Internet Gateway: An Internet Gateway is a device that routes all traffic from specified devices. It acts as a “full tunnel” VPN for the selected devices.
  * Gateway: As noted in the previous section, when defining a config file, you can specify Additional Addresses outside the VPN. The Gateway will route traffic to the client, which is then responsible for forwarding the traffic to the specified address ranges.

Review this list and determine which configurations you want to set up, then proceed to the corresponding section for instructions on how to implement them.

Into the Network

#### Gateways

For users to reach the network, a Gateway must be defined.

<figure><img src="/files/ApdXUR5VH8zCcE8Ri56T" alt=""><figcaption></figcaption></figure>

Gateways will forward traffic from user devices into the network. Any Linux device (e.g. a netclient running on Linux or Docker) can act as a Gateway.

The Gateway should have a public endpoint that is not behind a NAT.

**Default Gateway**

Your Netmaker server will deploy a device that can act as a Gateway by default. In simple scenarios, we recommend using this device. It will be the first device you see in your Network, before you add any others.

There are a couple of reasons to use other devices as gateways:

* Multiple gateways to segment traffic
* Proximity to target devices, to decrease latency

If either of these apply to you, you can follow these steps.

{% stepper %}
{% step %}

### Deploy a node

Deploy a node using the previously mentioned steps for the Netclient. Reminder that this should be an easily reachable device. It should not be behind NAT or strict firewall. If it is, you will need to make sure port forwarding is set up correctly.
{% endstep %}

{% step %}

### Set as Gateway

Go to the “Gateways” interface of your network, click “Create Gateway” and select the device. There are some optional parameters which you may want to configure here:
{% endstep %}
{% endstepper %}


# 4. Grant User Access

Add users to platform, set access and permissions

### Overview

Users access the VPN using the Desktop and Mobile Apps, on-demand VPN clients that can run on Windows, Mac, Linux, iPhone, and Android. Users can authenticate via Basic Auth or OAuth, and can be segmented into groups to separate access.

![](/files/03e2236f4a4df2b6a216032e994a410100fe7c6b)

Setting up user access consists of three steps:

{% stepper %}
{% step %}

### Add Users

Users can be Created, Invited, or can Sign-Up (Pending Users).

For all these options, it is important to know the basic Access Level you want to assign:

**Admin:** Has access to all resources on the platform

**Platform User:** Will have access to specified resources on the platform

**Service User:** Will only have the ability to use the VPN via App (cannot log into the platform).

For this guide we are assuming you are configuring Service Users.

#### Create Users (basic auth)

Click on  “Create User” in User Management interface to create a new Basic Auth user. Set a username, password, and specify the access level.

<figure><img src="/files/GNHsFLCdvdmgY1pDDR32" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Set User Permissions

#### Invite Users

Click on  “Invite User” in User Management interface to invite new users by email. If OAuth is configured (or using SaaS) this should be a compatible email domain.

<figure><img src="/files/0xoBcSBAxpVOOSpbizdx" alt=""><figcaption></figcaption></figure>

#### Groups

User Groups let you organize members and manage network access at scale. Assign a group to one or more networks with a specific role in each network, and every member inherits those permissions automatically.

<figure><img src="/files/n2Ju97xc2jBGHZSKUkeP" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Secure Remote Access

Once users are added to the platform and permissions configured, they can download and install the Netmaker Desktop and log in to access the network.

**Install the Netmaker Desktop**

<figure><img src="/files/myjt3bGo3r5PcJh6CEOj" alt=""><figcaption></figcaption></figure>

To install the Netmaker Desktop, users should download the platform-specific installer at <https://www.netmaker.io/download>. They should then follow the platform-specific instructions to install the client.

**Logging In**

**Server:** Users will need to know the Tenant ID for SaaS Netmaker instances, or API URL for On-Prem:&#x20;

* Tenant ID: The SaaS Tenant ID
* Netmaker API URL: api.\<your netmaker base domain>

Users will then login via Basic Auth or OAuth depending on how they were added:

* **Basic Authentication: Enter Username and Password, click Log In**
* **OAuth: Click the “Login with SSO button and then go through the provider’s login process.**

<br>

<figure><img src="/files/oyOJoSZ5bRwbYPlTVNMP" alt=""><figcaption></figcaption></figure>

Upon successful login, the user will see the gateways for which they have access.

Use the toggle switch to connect or disconnect from a specific gateway and access the network.<br>

{% endstep %}
{% endstepper %}

<figure><img src="/files/bCUEEdHb3XPi2CQrI5Ok" alt=""><figcaption></figcaption></figure>


# Glossary

## Introduction

Netmaker uses a lot of terminology which may sound unfamiliar. The purpose of this page is to provide an overview of the various terms for components and features within Netmaker, which will be helpful to understand in the context of building your network.

## Netmaker Components

Regardless of your scenario, you will be plugging together different components of Netmaker, much like lego bricks. While there are many different scenarios, the same components of Netmaker are used to bring them all together. So, it is helpful to gain a general understanding of these components and how they work together.

### Netmaker Server

All scenarios start with having a Netmaker server. This can be deployed either On-Prem or in our Cloud environment (SaaS). For standard scenarios we recommend SaaS, since it is the easiest way to get started. If you have specific data privacy requirements or need custom [OAuth](broken://pages/9d08ce7b7781bc52900cedd924ef17dd17f857f7), then you will want to deploy On-Prem. We will cover this in more detail in the next section on server deployment.

### [Netclient](broken://pages/6dd8b1ec772bcf61316d4351aec1318ab175831e)

The netclient is the headless agent that runs on servers and manages VPN settings, receiving instructions from the coordination server (Netmaker). This is the “local VPN configurator” agent of Netmaker, and can be configured to forward traffic, acting as an [Egress](/features/egress) or Gateway, which is why we need it. All scenarios require at least one Netclient, but many basic scenarios require only one or two.

### Node

Netclients added to the network appear as “nodes” (or Nodes) in the system. A node can live in multiple networks, meaning, for example, a netclient running on a server in your cloud could function as a Gateway, for multiple networks, while keeping traffic segmented and secure between the two. Because of this, a node has two scopes, at the global level and network level. Global Node settings include things like the hostname and MTU, and take effect across networks. Network-Scoped settings include things like the virtual address on the network, and gateway settings (like setting it as a Gateway). This allows a single device to act as a gateway in multiple networks, while maintaining segmentation.

### Network

In all scenarios, you will need at least one network. A Network in Netmaker is a VPN. It’s a logical, virtual subnet, that represents a system of connections between devices, acting as a group. Each member of that group gets an IP within the virtual network. In Netmaker, you can have many networks, to manage different scenarios and keep them segmented.

A Network can be [IPv6](https://www.netmaker.io/glossary/ipv6-support), IPv4, or both (dual-stack). You will want multiple networks if you are setting up different network scenarios, providing access to different sites, or segmenting access between different groups of users or devices.

### Egress

Many scenarios require accessing a subnet at a site, which can be done using an Egress Gateway. This is done by setting a Node as an Egress Gateway, and specifying which IPs and CIDRs will be accessed via the node. The node will then begin to automatically forward traffic into the local network. Alternatively a static config file can be used, for situations like routers. There are pros and cons to be considered with both approaches, collectively referred to as “local gateways,” however, for most standard use cases, we recommend using an Egress Gateway to access local sites.

### Gateway

The Gateway is a powerful feature which can be applied to nodes in a network. All remote access scenarios, and many site-to-site scenarios, require a Gateway. The Gateway enables us to do several things:

* Allows users to authenticate and access the network from their devices.
* Allows access to and from **any** device that supports [WireGuard](https://www.netmaker.io/resources/wireguard) using a static VPN config file.
* Allows access to and from **sites** via routers configured with a WireGuard VPN config file.

At its core, the Gateway manages “VPN Config Files”, which are WireGuard-compatible config files that can be run on most devices. For users, these files are generated dynamically via the Remote Access Client, and for devices and routers, static files can be generated, customized, and applied to the devices.

The Gateway has several other powerful features, listed below.

#### Internet Gateway

The Internet Gateway is a configuration very similar to the Egress Gateway, with one key difference: it creates a **full tunnel** VPN. If you want your users to access the internet via a node on the network (for instance, routing internet traffic through the office), use the Internet Gateway feature.

#### Relay Server

In some scenarios, you will want an intermediary server to route traffic between particular devices. For example, if there is a restrictive CGNAT on the office network, routing traffic through a Gatway will make the network more reliable. By assigning a node to a Gateway, the Gateway acts as a dedicated relay for routing traffic to and from that node.

#### Auto Relay

The Auto Relay feature of a Gateway acts similarly to Relay, but works automatically. When Auto Relay is enabled, devices will detect if traffic is not being sent, and if there is a disruption, route via the Gateway instead.

## Additional Terminology

Outside of Netmaker, there are some standard components that come into play when configuring your network. It is important to have an understanding of these key components.

### Public Linux Server

Most scenarios will require at least one linux server which is public-facing. This means it is deployed in a cloud environment, or you have configured routing/firewall rules in a data center or office network so that the server has a reliable endpoint for the VPN at :. This server typically acts as Gateway, Egress, or Netmaker Server (for on-prem setups), or some combination of the four!

### Router Configuration

If you want traffic to go through a router, you will have to configure the router. The specifics will depend on your scenario, but most likely, the router will need to be configured with WireGuard and a VPN Config File, which is attached to a Gateway. Alternatively, you may need to set up rules on the Router to route traffic through a local device that is running the netclient.

### Routing Configuration

If you are configuring a network so that devices can route traffic through the VPN, without needing the VPN client, then they will need to have routing rules that tell them where to send traffic. This must either be done on the router (as explained above), or, if that is not an option, by configuring all devices on the network with additional routing rules. For instance, adding a routing rule to your [VPC](https://www.netmaker.io/glossary/vpc-virtual-private-cloud) to send VPN-bound traffic via the device in the environment running the VPN client.

### WireGuard

When integrating any device into the network, it must run WireGuard. Our installers install WireGuard automatically, but for non-native and router device integration, they must run WireGuard. Most devices support WireGuard, and you may need to learn how to configure WireGuard on specific target devices.


# Quick Start

Get your first Netmaker network up and running in minutes. Follow the guides below to install the platform, configure your setup, and connect your first remote user.

***

### [Platform Installation →](#platform-installation)

### [Setup Guide →](#setup-guide)

### [Remote Access Quick Start →](#remote-access-quick-start)


# Platform Installation

Fast and Easy Setup for Secure Network Management

{% embed url="<https://www.youtube.com/watch?v=BpU5mMsek00>" %}

## Netmaker Platform Quick Install Guide

This guide will help you set up your Netmaker server quickly using a virtual machine, physical server, or cloud. It covers prerequisites, installation, and firewall configuration. By the end, you'll have an operational Netmaker server using WireGuard.

As an alternative, and if you're just trying out Netmaker, you can sign up at <https://account.netmaker.io/signup> for a free 7 Day trial of our cloud version, and skip this part.

To obtain a pro/commercial license for your self-hosted setup, please follow these steps:\
<https://learn.netmaker.io/getting-started/server-and-client-management/server-installation/adding-a-pro-license-to-your-server>\
\
*You can also upgrade your server from the community edition later.*

## Prerequisites

### Operating System & Server Requirements

All components of Netmaker can run on a single server (VM or bare metal). Specifications:

* Ubuntu 24.04.
* Public static IP address (required for communication between nodes).
* Domain name (preferred) (e.g., <http://netmaker.example.com/>) with DNS management access.
* System resources:
  * Minimum: 1 GB RAM, 1 CPU, 2 GB storage.
  * Recommended (production): 2 GB RAM, 2 CPU, 10 GB storage.
* Recommendation: Use Netmaker in a dedicated network for optimal performance.

### Recommended Cloud Providers

* <https://www.digitalocean.com/> (preferred)
* <https://www.linode.com/>
* <https://aws.amazon.com/>, <https://azure.microsoft.com/>, <https://cloud.google.com/>

Note: Avoid using Oracle Cloud due to known issues with network configuration.

### Netmaker Firewall Rules

Ensure firewall settings are configured on the VM and cloud security groups (e.g., AWS, GCP) or on your router/firewall appliance to allow inbound and outbound for the following:

* 80/TCP (For Caddy Certificate requests)
* 443/TCP: For the UI, REST API, MQTT broker
* 51821/UDP: Netmaker agent default listen port

Firewall commands:

{% code title="UFW rules" %}

```bash
# Allow HTTPS traffic for secure web connections (Caddy, Dashboard, REST API)
sudo ufw allow 443/tcp

# Allow WireGuard VPN traffic on UDP port 443 for secure peer communication
sudo ufw allow 51821/udp

# Allow HTTP traffic for Caddy, which uses port 80 to generate SSL/TLS certificates automatically
sudo ufw allow 80/tcp
```

{% endcode %}

Make sure the server isn’t blocking traffic forwarding. To guarantee forwarding of traffic:

{% code title="Accept forwarding policy (iptables)" %}

```bash
iptables --policy FORWARD ACCEPT
```

{% endcode %}

For advanced debugging, view firewall logs (example using UFW):

{% code title="UFW logging and filtering" %}

```bash
# set the firewall to log only the blocked traffic
ufw logging low

# clear out the current logs
cat /dev/null | sudo tee /var/log/ufw.log

# reload ufw
ufw reload

# filter the logs
cat /var/log/ufw.log | grep -e <netmaker server IP> -e <other nodes' IPs>
```

{% endcode %}

### Domain

Your server hosts several services (netmaker server, UI, etc.) — each needs a dedicated, public subdomain. Recommendations:

* Use a publicly owned domain (e.g., <http://example.com/>, <http://mysite.biz/>)
* Designate a subdomain (e.g., \*.netmaker.example.com) for Netmaker’s services (e.g., dashboard.netmaker.example.com, api.netmaker.example.com)
* If you don’t want to use a wildcard domain (\*.netmaker.example.com): create individual DNS records (A for IPv4 and/or AAAA for IPv6) for each required subdomain:

| Purpose           | Required Subdomain              |
| ----------------- | ------------------------------- |
| Netmaker API      | `api.example.com`               |
| Dashboard UI      | `dashboard.example.com`         |
| MQTT Broker       | `broker.example.com`            |
| Prometheus        | `prometheus.example.com`        |
| Grafana           | `grafana.example.com`           |
| Netmaker Exporter | `netmaker-exporter.example.com` |

Make sure you have permission and access to modify DNS records (e.g., Route53).

{% hint style="warning" %}
Important Note on Cloudflare: Cloudflare’s proxying can interfere with MQTT functionality. You can disable proxying in the Cloudflare DNS dashboard. Cloudflare proxy configuration may lead to issues with Netmaker; Netmaker does not provide guidance for resolving these problems.
{% endhint %}

### Netmaker Commercial License

* Check these steps to obtain a pro/commercial license: <https://learn.netmaker.io/getting-started/server-and-client-management/server-installation/adding-a-pro-license-to-your-server>

## Quick Install Script

Execute the nm-quick script for a self-hosted/on-premises setup.

To install Community Edition:

{% code title="Install Community Edition" %}

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh
```

{% endcode %}

To install Pro Edition:

{% code title="Install Pro Edition" %}

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh -p
```

{% endcode %}

{% hint style="warning" %}
IMPORTANT: The auto-generated domain used by the installer has been rate-limited by the certificate provider. Strongly recommend using your own domain. Using the auto-generated domain may lead to failed installation due to rate limiting.
{% endhint %}

## Post-Installation: Accessing the Dashboard & Creating a Super Admin

Follow these steps after a successful Quick Install to create a Super Admin and verify access.

{% stepper %}
{% step %}

### Access the Netmaker Dashboard

* Open a web browser and navigate to your Netmaker dashboard URL:
  * Custom domain: `https://dashboard.example.com`
  * Auto-generated domain: `https://dashboard.nm.<your-server-ip>.nip.io` (format provided during installation)
    {% endstep %}

{% step %}

### Log In

* On the login screen, use the initial admin credentials created during installation.
  {% endstep %}

{% step %}

### Create a user

* Navigate to User Management in the left-hand sidebar.
* Click Add a User. In Netmaker Professional there are two ways to add users:
  * Basic Auth: create users with username, password, and assign groups/roles.
  * User Invite: send invitations via email (SMTP setup required for self-hosted — <https://docs.netmaker.io/docs/server-installation/advanced-options#setting-a-netmaker-server-up-for-emailing>). Invitees receive a link to create their account with pre-assigned roles/groups.

If you selected Create a User:

* Fill in Username, Password.
* Platform Access Level: select Admin.
* Click Create User.

If you selected Invite a User:

* Fill in Email address(es).
* Platform Access Level: select Admin.
* Click Create User Invite(s).
  {% endstep %}

{% step %}

### Test the Super Admin Access

* Log out of the current session.
* Log in using the new Super Admin credentials.
* Verify access to all administrative features in the dashboard.
  {% endstep %}
  {% endstepper %}

##


# Setup Guide

This guide will give you a short introduction to the functionalities of the Netmaker platform, after installing your control plane.

## First Time Log In (On-Prem Only)

On first login, you will need to create an Admin user.

{% stepper %}
{% step %}

### Go to Dashboard

After installing Netmaker, go to dashboard.\<yourdomain> to start using the platform.
{% endstep %}

{% step %}

### Create your admin user

Create your first admin user, with a username and password. If you'd like to configure MFA, you can do this from within the platform Settings after logging in.
{% endstep %}

{% step %}

### Log In

Log In with your new user.
{% endstep %}
{% endstepper %}

## Create a Network

Netmaker deploys a network by default (called "netmaker") which you can use. However, if you'd like to create your own, or have multiple, click on "Create network" in your Dashboard to add a new one.

![](/files/5qQxYAzBrV7xxRT4eLEw)

This network should have a sensible name.

More importantly, it should have a non-overlapping, private address range.

If you are running a small (less than 254 machines) network, and are unsure of which CIDR’s to use, you could consider:

* 10.11.12.0/24
* 10.20.30.0/24
* 10.99.98.0/24

#### Network Settings Description

The Network creation form has a few fields which may seem unfamiliar. Here is a brief description:

**IPv4:** Adds private IPv4 to all nodes in a network

**IPv6:** Adds private IPv6 to all nodes in a network

**Default Access Control:** Indicates the default ACL value for a node when it joins in respect to it’s peers (enabled or disabled).

Once your network is created, you should see the network (Wg Net here but it will be the name you chose when creating the network):

![](/files/82f9pVvcasYnY7Yklt6h)

When you click on the NetId and then the Nodes button (or go direct via the left-hand menu and then Nodes) you see that the netmaker server has added itself to the network. From here, you can move on to adding additional nodes to the network.

![](/files/etj6wzC2LMvo3sGBXCpa)

## Create a Key

Adding nodes to the network typically requires a key. Enrollment keys offer different ways to register with a server.

By default, Netmaker will create a key you can use with your network. However, you can create your own if you would like to specify certain settings.

Navigate to the Keys interface. You should see a create button in the top right corner.

![](/files/owGm1QCjsMa0koD4fVsg)

After clicking that, you should be brought to a window like this.

![](/files/zsqFVxEVHoDTFvsRyvmI)

This will give you a few different options on how you want to set up your enrollment key. you can set it up with unlimited uses, limited uses, or timebound uses. You can also setup one or multiple networks to join, or you can set it to no networks and then join a network through the UI in the devices interface. You can also create any tags you would like for that key.

![](/files/5Nd2c3XHfbHCfXREW1RO)

If an enrollment key runs out of uses, or is expired, the key will show as invalid like in the image below.

<figure><img src="/files/UUIZFWlhWVpn4NAQiIhD" alt=""><figcaption></figcaption></figure>

After your enrollment key is created, you can click on that key to get the registration token.

<figure><img src="/files/kxAKbEyCylVnk8ZV1LK1" alt=""><figcaption></figcaption></figure>

* The **Enrollment Key** value is the secret string that will allow your node to authenticate with the Netmaker network. This can be used with existing netclient installations where additional configurations (such as setting the server IP manually) may be required. This is not typical. E.g. `netclient register -k <enrollment key> -s grpc.myserver.com -p 50051`
* The **Registration Token** value is a base64 encoded string that contains the server IP and grpc port, as well as the enrollment key. This is decoded by the netclient and can be used with existing netclient installations like this: `netclient register -t <registration token>`. You should use this method for adding a network to a node that is already on a network. For instance, Node A is in the **mynet** network and now you are adding it to **default**.
* The **Register Command** value is a command that can be run on Linux systems after installing the Netclient. It will register with the server directly from the command line.

Other variations (eg Docker) are covered with the remaining values.

## Deploy Nodes

Nodes act as the endpoints of your network, and can perform special networking tasks such as relaying traffic and forwarding traffic to local environments. Nodes are deployed with the **Netclient.**

{% stepper %}
{% step %}

### Prerequisite

Every machine on which you install should have WireGuard and systemd already installed.
{% endstep %}

{% step %}

### SSH to each machine

SSH to each machine and become root:

```bash
sudo su -
```

{% endstep %}

{% step %}

### Prerequisite Check

Every Linux machine on which you run the netclient must have WireGuard and systemd installed.
{% endstep %}

{% step %}

### Install netclient

Follow the installation instructions for your operating system [here](broken://pages/6dd8b1ec772bcf61316d4351aec1318ab175831e#installation)
{% endstep %}
{% endstepper %}

You should get output similar to the below. The netclient retrieves local settings, submits them to the server for processing, and retrieves updated settings. Then it sets the local network configuration. For more information about this process, see the [client installation](broken://pages/6dd8b1ec772bcf61316d4351aec1318ab175831e#installation) documentation. If this process failed and you do not see your node in the console (see below), then reference the [troubleshooting](/references/troubleshooting) documentation.

![Output from Netclient Install](/files/91176395ff6c19384b245ba1aae6ddc5b1df4c95)

Repeat the above steps for every machine you would like to add to your network. You can re-use the same install command so long as you do not run out of uses on your access key (after which it will be invalidated and deleted).

Once installed on all nodes, you can test the connection by pinging the private address of any node from any other node.

![Node Success](/files/7f23606719bdc4684d75a42444c0ce58160a9d5c)

## Manage Devices

Your machines should now be visible in the control panel.

![](/files/JI1BjRmPsBt9ThYtxgos)

Each node has an associated device. Nodes represent the device **within a network,** while the device remains the same across networks. The device will have  settings like verbosity and listen ports which can be modified. The Device can be found in the Devices tab on the UI. You should be taken to a screen like this.

![](/files/KUyM6ialhIiaNbDmKp0n)

In here you can see the device's name, the endpoint of the server running netclient, the public key for that host, the version number, and a switch to set that host’s node as the default node. When this is switched on, that node will serve as the default node when a network is created. Clicking on a device will bring you to the device details.

![](/files/qJADOozLQXS00sE5uZB4)

This will give you more information like the firewall in use, MTUs, and listening port. You can also see networks associated with that device and options to edit or delete the device. If you are going to delete a device.

![](/files/qPkzVPQcyesTDkH9bPgy)

In the edit screen, you can make changes to the logging verbosity, listening port and proxy listening port, local range, MTU, and name. These fields will also update in the node, as the node gets this info from the device. If you want to change the endpoint, the associated node has to be static.

You can view/modify/delete any node by selecting it in the NODES tab. For instance, you can change the name to something more sensible like “workstation” or “api server”. You can also modify network settings here, such as keys or the WireGuard port. These settings will be picked up by the node on its next check-in. For more information, see Advanced Configuration in the [Using Netmaker](/how-to-guides) docs.

![](/files/UziRRVlm7wgekTUTIC53)

Nodes can be added/removed/modified on the network at any time. Nodes can also be added to multiple Netmaker networks. Any changes will get picked up by any nodes on a given network and will take about \~30 seconds to take effect.

## Uninstalling the netclient

{% stepper %}
{% step %}

### Remove node from network

To remove your nodes from a network (default here), run the following on each node:

```bash
sudo netclient leave default
```

Replace "default" with the actual name of the network (eg wg-net).
{% endstep %}

{% step %}

### Remove netclient entirely

To remove the netclient entirely from each node (after running the above step), run:

```bash
sudo systemctl stop netclient && sudo systemctl disable netclient && sudo systemctl daemon-reload && sudo rm -rf /etc/netclient /etc/systemd/system/netclient.service /usr/sbin/netclient
```

{% endstep %}
{% endstepper %}

## Uninstalling Netmaker

To uninstall Netmaker from the server, simply run:

```bash
docker-compose down
```

Or to remove the docker volumes for a future installation:

```bash
docker-compose down --volumes
```


# Remote Access Quick Start

Remote Access is the most common use case for Netmaker. Most of our users use Netmaker to access a local network, such as a LAN.

To do this requires just three steps in a new Netmaker instance:

{% stepper %}
{% step %}

### Install Netmaker Desktop/Mobile

Install the client for accessing your network on your local device.
{% endstep %}

{% step %}

### Deploy a Routing Node

Deploy the Netclient in the target environment, which will be used to forward traffic.
{% endstep %}

{% step %}

### Add Forwarding

Create Egress routes to route traffic into the local environment via the routing node.
{% endstep %}
{% endstepper %}

## 1. Install Netmaker Desktop/Mobile

To install Netmaker Desktop or Mobile, head to <https://www.netmaker.io/download> and select your operating system. Follow the installation steps, then log in as your admin user.&#x20;

At this point, there is nothing to access yet!

## 2. Deploy Routing Node

The Netclient is used to route traffic into a local environment. From your dashboard, head to the Nodes page. In the upper right will be a button to "+ Add device". Click this button and follow the instructions for installing the Netclient.

**To use this node to foward traffic, it must be deployed using Linux or Docker.**

Make sure you have a suitable VM deployed in the target environment you can use, and make sure the firewall is configured to allow both inbound and outbound 443 UDP and TCP.

## 3. Add Forwarding

Once installed, the device should appear in your Nodes panel. Next, go to the Egress page. In the upper right should be a button to "+ Add route". Click this button and follow the instructions:

* Give this route a name like "office LAN"
* Keep NAT enabled
* Specify the Route
* Click "Next"
* Select your Node

## 4. Access Your Network

Back on your local device, log into Netmaker Desktop/Mobile. The network should appear, with a toggle to connect and disconnect. You may need to click "Reload" before connecting in order for this to function properly.

## 5. (optional) Add DNS

If accessing a local network which has its own DNS server, you likely want to use these domain names when accessing the network. To do this, simply:

1. Go to DNS in your sidebar in the Dashboard
2. Click "+ Add Nameserver"
3. Follow the steps to add Custom DNS, specifying your nameserver location and the Match domains to use.


# Walkthrough

## Overview

This section provides a complete walkthrough of the Netmaker platform, including:

1. How to Install Netmaker
2. How to Create Networks
3. How to Add Devices
4. How to Add Egress
5. How to Create and Configure Gateways
6. How to Set DNS
7. How to Add Users
8. How to Manage Access
9. How to View Metrics and Audit Logs

On this page you'll find video walkthroughs for each of these overviews. In the following sections, you'll find written versions of these video walkthroughs.

## Video Walkthrough

{% stepper %}
{% step %}

### How to Install Netmaker

{% embed url="<https://youtu.be/BpU5mMsek00>" %}
{% endstep %}

{% step %}

### How to Create Networks

{% embed url="<https://youtu.be/2Wrafd-gIJo>" %}
{% endstep %}

{% step %}

### How to Add Devices

{% embed url="<https://youtu.be/kaLYZAK0ddg>" %}
{% endstep %}

{% step %}

### How to Add Egress

{% embed url="<https://youtu.be/CJVqDC_tXxU>" %}
{% endstep %}

{% step %}

### How to Configure Gateways

{% embed url="<https://youtu.be/_tYAauDrnSg>" %}
{% endstep %}

{% step %}

### How to Set DNS

{% embed url="<https://youtu.be/IN-FLdwVySg>" %}
{% endstep %}

{% step %}

### How to Add Users

{% embed url="<https://youtu.be/8sMID1iZIJE>" %}
{% endstep %}

{% step %}

### How to Manage Access

{% embed url="<https://youtu.be/DtPyhZJMv58>" %}
{% endstep %}

{% step %}

### How to View Metrics and Audit Logs

{% embed url="<https://youtu.be/arhvPJkm1zk>" %}
{% endstep %}
{% endstepper %}


# How to Install Netmaker

{% embed url="<https://youtu.be/BpU5mMsek00>" %}

### Purpose

How to Install and Configure Netmaker Pro On-Premise

### Introduction and Documentation

Netmaker provides a flexible networking platform that can be deployed as a managed SaaS solution or self-hosted on-premise. This guide focuses on the self-hosted on-premise deployment, specifically for the Netmaker Professional version, which utilizes an automated installation script for streamlined setup.

#### Official Resources and Documentation

Before beginning the installation, it is essential to familiarize yourself with the official resources provided by the Netmaker team. These resources contain the most up-to-date requirements and configuration options.

* Navigate to the official Netmaker GitHub repository at `github.com/gravitl/netmaker` or visit the primary documentation site at `learn.netmaker.io` to review the initial installation requirements and architecture overview.
* Open the **Quick Install** guide within the documentation to access the automated setup steps and verify infrastructure compatibility.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/bd8e2b6b-611e-4fc3-ab63-a8f55896c91f-screenshot_0_20.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182725Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d39f411bc37f3ee657e4447b8e349a5755853d0205599aacd37f55d58c8cf496" alt=""><figcaption></figcaption></figure>

#### Retrieving Professional License Credentials

If you are deploying Netmaker Professional on-premise, you must retrieve your unique licensing credentials before proceeding with the installation script. These credentials authenticate your instance with the Netmaker license server.

1. Log in to the Netmaker Account Manager portal at `account.netmaker.io`.
2. Identify your target tenant from the **Tenants** list and click the corresponding **Manage** button.
3. Within the **Tenant Details** section, navigate to the **Settings** tab to locate the **License Key** and **Tenant ID** fields. Copy these values, as they will be required during the command-line installation phase to enable Pro features.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/f3a32340-7451-4937-9498-cfd4f4d7982e-screenshot_1_58.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182725Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d1e5d555d1caed56dd39a67de75b365268ffb5ccc19b6ed85d4121fac311db08" alt=""><figcaption></figcaption></figure>

### Prerequisites and Server Requirements

Before initiating the installation process, it is essential to prepare a suitable environment that meets Netmaker's infrastructure and networking standards. This section outlines the necessary hardware, operating system, and firewall configurations required for a successful deployment.

#### Infrastructure and Hardware Specifications

Netmaker requires a clean server environment, preferably a cloud-hosted Virtual Machine (VM) with a dedicated public static IP address. While most Linux distributions are compatible, Ubuntu 24.04 is the recommended operating system for the most stable experience. The system must meet the following resource benchmarks:

* **Minimum:** 1 GB RAM, 1 CPU, and 2 GB of storage.
* **Recommended (Production):** 2 GB RAM, 2 CPUs, and 10 GB of storage.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/2c6f4c98-09b7-48a5-a359-4d122544dffc-screenshot_2_82.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182725Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=bf1b664fefcb19002e150b51a480d35a9c55b1584ad32389046de01ba711a3ff" alt=""><figcaption></figcaption></figure>

#### Network and Firewall Configuration

Proper network accessibility is vital for the coordination between the Netmaker server and its clients. You must configure your cloud provider's firewall or security groups to allow traffic through several specific ports. These rules ensure that core services like the Caddy web server, CoreDNS, and the MQTT broker can communicate effectively.

**Required Inbound Rules**

* **SSH (Port 22 TCP):** For remote server management and installation.
* **Web Traffic (Ports 80 & 443 TCP):** Essential for Caddy to manage HTTP/HTTPS traffic and dashboard access.
* **DNS (Port 53 TCP/UDP):** Required for CoreDNS to resolve internal network names.
* **WireGuard (Port 443 UDP):** This is the default port for WireGuard traffic; ensure UDP is specifically enabled.
* **WireGuard Backup (Port 51821 TCP/UDP):** Highly recommended as a secondary path to ensure connectivity under restrictive network conditions.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/1de6aedd-99cd-489b-9c23-2ba20997447b-screenshot_3_128.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182728Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d7e440a9bf7e5bdf6b27265b3877a298cc753dfeeb9f580993be8d8f9967f48c" alt=""><figcaption></figcaption></figure>

#### Professional Credentials

If you are deploying the Netmaker Professional version, you must retrieve your tenant credentials before running the installation script. Log in to the Netmaker Account Manager at `account.netmaker.io` and navigate to the **Tenant Details** section. Securely copy both the **License Key** and the **Tenant ID**, as these will be requested by the automated script during the setup phase.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/42cce503-543a-4f80-956d-c1cef38270cd-screenshot_4_60.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182727Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7eda055ab7e2a484f4c0557f2e19aac3047a476606a442a648e993eee9513f7b" alt=""><figcaption></figcaption></figure>

### DNS and Firewall Configuration

Proper networking is the foundation of a successful Netmaker installation. Before proceeding with the automated script, you must configure your infrastructure to handle incoming traffic for both the management interface and the underlying WireGuard tunnels.

#### Inbound Firewall Rules

Access your cloud provider's firewall management console (such as DigitalOcean) and verify that the following ports are open for inbound traffic:

* **Web and Certificates:** TCP 80 and TCP 443 for HTTP/HTTPS and SSL certificate issuance.
* **DNS:** Both TCP 53 and UDP 53 to support CoreDNS functionality.
* **WireGuard Connectivity:** UDP 443 and UDP 51821. Note that while TCP 443 is used for the web, UDP 443 is the default port for WireGuard traffic in Netmaker.
* **Redundancy:** TCP 51821 as a backup for WireGuard traffic.

**Security Note:** Ensure SSH (TCP 22) remains open for your administrative access throughout the installation process.

#### Setting Up Wildcard DNS

Netmaker requires multiple subdomains for various services, including the API, dashboard, and broker. The most efficient way to manage this is by creating a wildcard A record in your DNS settings.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/fb295733-adbe-4e54-9a5a-0633330d7998-screenshot_5_158.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182727Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=252991b624d712af1a1d2fa3b758d0ac318f4e052f32c45e2e7479cb2af77802" alt=""><figcaption></figcaption></figure>

To configure your DNS:

1. Navigate to the DNS management page for your domain.
2. Create a new **A Record**.
3. In the **HOSTNAME** field, enter a wildcard subdomain (e.g., `*.demo`).
4. In the **WILL DIRECT TO** field, select or enter the static IP address of your target server.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/b5078691-19c2-4bd8-b6c5-a762459b6fa5-screenshot_6_180.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182725Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=a61f00289ffc2a686ca278b115ad44aaff93b967f93946fbe9690d7372182366" alt=""><figcaption></figcaption></figure>

By using a wildcard such as `*.demo.example.com`, the system will automatically resolve required addresses like `api.demo.example.com` and `dashboard.demo.example.com` without requiring additional manual DNS entries during the installation script execution.

### Executing the Installation Script

Once your server prerequisites and DNS records are in place, the installation is handled by an automated script. This script orchestrates the deployment of Docker containers and configures the core Netmaker services.

#### Running the Setup Command

Access your server via SSH and execute the following command to download and run the Netmaker quick-install script. Note the use of the `-p` flag, which specifies a Professional installation:

`sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh -p`

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/978f517d-0b0e-4d5c-bb0a-2564f3545818-screenshot_7_212.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=2ed1ec65faad98f1d32acfe76f0d90dedc559944af0df62207b64877c18e40e4" alt=""><figcaption></figcaption></figure>

#### Configuring the Custom Domain

The script will prompt you to select a domain type. While an auto-generated domain is available, using your own custom domain is highly recommended to avoid potential availability or crowding issues with the default server. Select option **'2'** for a custom domain.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/f79fb458-be07-49e0-82da-e52180b027a7-screenshot_8_242.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=67dbd264a5f53eb7c5ac4b7618c5a2219089bd4b293714c0eb54194357382b60" alt=""><figcaption></figcaption></figure>

When prompted, enter your base domain (e.g., `demo.netmaker.io`). The script will automatically generate the necessary subdomains for the API, dashboard, and broker. Review the list of subdomains and type **'y'** to confirm they match your DNS wildcard configuration.

#### Entering Professional Credentials

Because this is a Professional installation, you must provide your license details. Return to the [Netmaker Account Manager](https://account.netmaker.io/) to retrieve your credentials from the **Tenant Details** section.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/0ad5a968-d795-4855-9c67-3c0bdbaa8104-screenshot_9_276.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182727Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=4e1ca44d0fa153d02a0bf8ad40679a6c09f00aeb921f815a891bcf6d9a47dd0b" alt=""><figcaption></figcaption></figure>

* **Registration Email:** Enter the email address associated with your domain registration for SSL certificate generation.
* **License Key:** Copy and paste your unique Pro license key.
* **Tenant ID:** Copy and paste your specific tenant ID.

#### Finalizing Installation

After entering your credentials, the script displays a **SETUP ARGUMENTS** summary. Verify that all values, including the domain and license information, are correct. Type **'y'** to initiate the container deployment.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/0f98a3ad-b269-4cbf-a9f1-d1582f64c5aa-screenshot_10_292.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=316ccaba46278db5779b92951c23bd435f5273fa679c910611df22dca8571808" alt=""><figcaption></figcaption></figure>

The script will begin pulling Docker images and starting services. This process typically takes 5 to 10 minutes depending on your server's performance and network speed. Monitor the terminal output for progress as the system creates the Netmaker networks and containers.

### Dashboard Setup and Admin User

After the automated installation script concludes, the terminal will display the specific URL for your Netmaker dashboard. It is important to wait until the process is fully complete, which typically takes between 5 and 10 minutes depending on your server resources.

#### Initial Admin Registration

Open the provided dashboard link in your web browser. You will be directed to the Sign Up page to establish the primary administrator account. Enter a username, such as **admin**, and provide a secure password in the required fields. Click the **Sign up** button at the bottom of the form to create your credentials and initialize the system.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/23d873b7-c686-428d-b3bc-50337f1f4964-screenshot_11_332.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=e59277b22e9245196c107c9e68a077c69352907fddbe9bd7cbef4ebad41fedb8" alt=""><figcaption></figcaption></figure>

#### Security Notifications and Dashboard Access

Following the sign-up process, Netmaker offers an optional prompt to register for important security updates and version notifications. You may choose to provide your contact information for these notices or skip this step to proceed directly to the interface.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/8f3226ef-4e9e-4b4e-a9f3-679a3c666821-screenshot_12_340.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=fdd319a54c4d2c9da7f155d8c2eadd4450f336e8e6643edb00efda7f876774b9" alt=""><figcaption></figcaption></figure>

Upon completion, you will be redirected to the main Netmaker Pro dashboard. Verify that the **Welcome, admin!** header is visible and that the navigation sidebar contains the Networks, Devices, and Users tabs, indicating a successful installation and login.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/26f2dc0c-b3d5-4916-8432-7a86deec871f-screenshot_13_354.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=798a60e15936e4540444acd72c75badfe96547a1733b36d4fc36ea08bbda705a" alt=""><figcaption></figcaption></figure>

### Advanced Settings and Conclusion

Once the Netmaker Pro dashboard is operational and the initial administrative account is created, you can access advanced configuration options to harden security and integrate the server into your existing infrastructure.

#### Configuring Security and Identity Providers

To begin customizing your server, navigate to the **Settings** icon located at the bottom of the left sidebar. Within this menu, select the **Security & Authentication** tab to manage how users access the platform.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/bc785ad7-8dd3-402d-8f28-d92ed94d63fe-screenshot_14_368.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=c31e8b8f4cb8ab99a6011e43fd25d411b0dcb6bcca8e512e7cb5cd3b91dec3f2" alt=""><figcaption></figcaption></figure>

Under this section, you can configure **Identity Providers Integration** by connecting services such as Google, Microsoft Entra ID (formerly Azure AD), or GitHub. This allows for OAuth and IDP synchronization, which is essential for enterprise deployments. Additionally, you can manage more granular security parameters, such as:

* Toggling **Basic Authentication** on or off.
* Defining **Allowed Email Domains** to restrict access to specific organizations.
* Enforcing **Multi-factor Authentication (MFA)** for all users.

#### Monitoring and Server Diagnostics

For ongoing maintenance, navigate to the **Monitoring & Debugging** tab. Here, administrators can adjust the **Verbosity Level** of server logs to troubleshoot connectivity issues, toggle **Telemetry** data sharing, and verify the **Metrics Port** (defaulting to 51821) for integration with external monitoring tools.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/15a00c2a-627b-494f-8b44-3a40a6e7f764/1fe39d6e-b359-4b27-8444-b55ab4ab9b26-screenshot_15_379.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182726Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=1d155c03efa0cbf912560e9440e7bec0e4a2623b7d4f15b047a457698cfacddd" alt=""><figcaption></figcaption></figure>

#### System Notifications and Conclusion

Finally, set up the **Email Configuration** tab to enable system-generated notifications. You will need to provide your SMTP details, including the **Host**, **Port**, **Sender Address**, and **Sender Username**. These settings ensure that administrative alerts and security notices are delivered successfully.

With these settings configured, your Netmaker Pro installation is complete. For more complex deployment scenarios or deep-dives into specific server-side parameters, consult the advanced server installation documentation available at docs.netmaker.io.


# How to Create Networks

{% embed url="<https://youtu.be/2Wrafd-gIJo>" %}

### Purpose

Managing Networks in Netmaker

### Introduction and the Default Network

Netmaker networks serve as segmented overlay networks, essentially acting as virtual subnets that allow you to isolate traffic for different use cases, environments, or customers. This segmentation is a fundamental architectural component for managing secure communications between distributed nodes.

#### The Default Network

Immediately following the installation of the Netmaker server, the system automatically provisions an initial network for your environment. This default configuration allows you to begin connecting nodes without manually defining address ranges or access policies right away.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/dcc94c56-36c4-4a37-aa9d-c27011f27165-screenshot_0_18.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182900Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=c737050246bf8bf5176cf0b55cc60fa26316ea3d3821d0f42fca1d391bbbad15" alt=""><figcaption></figcaption></figure>

* **Locating the Network:** Access the Netmaker dashboard and find the entry named **Netmaker** in the central networks list.
* **Viewing Network Details:** To inspect the specific configuration or manage devices within this segment, click on the **Netmaker** network name. This view will display all associated nodes and their status.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/1f149fb2-c6cd-476f-925a-5c81047e922f-screenshot_1_24.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=bf1f679ef0a29bb6e746e0fb621a8cb3b973b54e546a290bc1dff966de44ed38" alt=""><figcaption></figcaption></figure>

#### Purpose of Network Segmentation

While the default network is fully functional for general use, creating multiple networks is a best practice for organizational security and clarity. Using distinct networks allows administrators to:

* **Segment Use Cases:** Separate production traffic from development or edge device management.
* **Tenant Isolation:** Create unique network environments for different clients or departments.
* **Address Management:** Assign specific IPv4 or IPv6 CIDR blocks to different logical groups of devices.

### Creating a Custom Network

Creating custom networks in Netmaker allows for effective segmentation of use cases, such as managing edge devices or isolating specific customer environments. Each network acts as a unique subnet or segmented overlay network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/951681ea-2f1d-458b-8c18-13c59d4f3172-screenshot_2_38.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182900Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=82d6b3fe46e90facde3777b632568ac5ff2337984ae5c753948c624ff7dffc6c" alt=""><figcaption></figcaption></figure>

#### Initiating Network Creation

To begin, navigate to the **Networks** dashboard. Locate and click the blue **+ Create network** button positioned above the main network list. This action opens the configuration modal where you will define the parameters for your new segment.

#### Configuring Network Details

In the creation modal, you must provide a descriptive name and define the address space for the network:

* **Network Name:** Enter a specific identifier, such as **Edge Access**, in the name field to distinguish this segment from the default network.
* **IP Address Ranges:** Toggle the **IPv4** switch to enable it. It is recommended to use the **Auto-fill** feature to automatically generate a CIDR address range (for example, `100.92.191.0/24`). If your environment requires it, you can also enable **IPv6** to assign virtual IPv6 addresses to your devices.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/a68d91ff-0e12-4fa6-8ab3-28ab7548ce20-screenshot_3_82.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=3fb428e58c360101cbfbfeec420c6bd34b08cc9dc2e1dccab6a61616cd2fb765" alt=""><figcaption></figcaption></figure>

#### Defining Access Control

Before finalizing the network, you must determine how devices within this segment will interact by default:

* **Default Access Control:** Select the dropdown menu and set the policy to **ALLOW**. This ensures that nodes can communicate with each other immediately upon joining the network. Alternatively, you can choose to disable default connections if you prefer to manually authorize every peer-to-peer link.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/d701e839-8261-444e-98a1-fd144606d1a2-screenshot_4_104.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=fd57578af51ca3d87fc635eb80c3ef8b149b564d9f9b95cd808d906dac22e49a" alt=""><figcaption></figcaption></figure>

#### Finalizing the Setup

Once the naming, addressing, and access controls are configured, click the **Create Network** button at the bottom of the modal. This saves the configuration and adds the new **Custom Network** to your dashboard, making it ready for device enrollment.

### Segmenting with Multiple Networks

Netmaker allows you to create multiple segmented overlay networks to isolate different environments such as corporate offices, edge infrastructure, or cloud environments. This section demonstrates how to build out these specific use cases to keep traffic logically separated.

#### Adding a Use Case Specific Network

To create a network dedicated to a use case, for example employee office access, navigate to the main dashboard and click the **+ Create network** button.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/64765e20-5c5a-445b-8af5-ae21e7bb9a6a-screenshot_5_114.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ff31b942533061567218906bb215db857e48a23f53e7e060aef7602473de5f61" alt=""><figcaption></figcaption></figure>

In the network creation modal, enter **Office** as the network name. This network is typically used for employees to access internal office resources securely. While the system can automatically assign an IP range, you can customize the subnet mask to fit your organization's scale.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/10b47ed8-3788-4ef2-a8ff-7cf1a8953725-screenshot_6_128.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=18f9de3d8d4357f019a4613ad69a9e954b0a8dd1c487cfb380f29a54d29301f1" alt=""><figcaption></figcaption></figure>

* **IPv4 Configuration:** Enable the **Auto-fill** switch.
* **Subnet Adjustment:** If you anticipate a large number of employees, manually change the CIDR suffix from `/24` to `/16` (e.g., `100.77.15.0/16`) to increase the available IP address pool.

#### Creating a Cloud Overlay

For scenarios involving the connection of disparate cloud or data center environments, you can establish a separate **Cloud Overlay**. This keeps infrastructure-to-infrastructure traffic separate from user-to-office traffic.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/e0ccde61-a8e2-475d-8db6-c38fc796e70a-screenshot_7_144.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d396744689c650ae13e86df4a55d64e2ff47b0a9f3aef2b7be056215d108ef04" alt=""><figcaption></figcaption></figure>

1. Click **+ Create network** again from the network list.
2. Input **Cloud Overlay** in the **Network Name** field.
3. Enable **Auto-fill** for the IPv4 range and, similar to the office network, adjust the CIDR to `/16` to ensure plenty of address space for various cloud nodes.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/3bd7c946-2505-4435-a6d6-dba2b388828c-screenshot_8_148.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=f256843645bd7fc21a17f49f2ee66c5828e651b7e1e27bf02d3263dd885c3a27" alt=""><figcaption></figcaption></figure>

Once finished, return to the main **Networks** dashboard to view your new segments. You should now see a list of all active networks, including the default, edge, office, and cloud segments, each functioning as an isolated subnet.

### Deleting a Network

When a network segment is no longer required or was created for temporary use, it can be permanently removed from the Netmaker dashboard to maintain a clean workspace.

#### Navigate to the Networks List

To begin, return to the main dashboard by selecting **Networks** from the breadcrumb navigation or the sidebar menu. This view provides an overview of all currently active segments, such as the default "Netmaker" network or any custom overlays like "Office" or "Edge Access."

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/91222d56-5306-4b66-9747-2edaf0e8401d-screenshot_9_152.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182902Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=4c3424a366c37358c20f687f4309fc08a3484655b89d9dc3f780ac424e2f61cb" alt=""><figcaption></figcaption></figure>

#### Initiate Network Destruction

Locate the row for the network you wish to remove. On the right-hand side of the entry, click the **Destroy** button. Because deleting a network is an irreversible action that disconnects all associated nodes, Netmaker requires a safety confirmation.

#### Verify and Confirm Deletion

A confirmation modal titled **Destroy network \[Network Name]** will appear. To finalize the process, follow these steps:

1. Type the exact name of the network (e.g., `Netmaker`) into the validation input field.
2.

```
<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/26351b16-5fdd-4643-90c5-36a0f4e8492c-screenshot_10_160.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182902Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=1030fdf285b702013011973e942b1bc00367c976aafed0939011366d460c5e9f" alt=""><figcaption></figcaption></figure>
```

3. Once the name is correctly entered, click the red **Destroy** button at the bottom of the modal.

After clicking destroy, the network and its configuration will be permanently purged from the server, and the dashboard list will update to reflect the change.

![Final execution of the destroy command](https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/ebb880b6-7b55-49dc-9d09-79b3765f738d-screenshot_11_162.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request\&X-Amz-Date=20260121T182902Z\&X-Amz-Expires=3600\&X-Amz-SignedHeaders=host\&X-Amz-Signature=2f85877fa85aa433693e8b4d88191faba5cc842bd1878e7533ad48746aa33db3)

### Conclusion and Next Steps

This tutorial has outlined the essential process of configuring and managing networks within the Netmaker dashboard. By creating segmented overlay networks such as "Edge Access," "Office," and "Cloud Overlay," you can effectively isolate traffic and simplify administrative oversight for distinct environments or client projects.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/85aa936b-0e6d-46a6-b8f8-1bfdb558a740/76c98d02-4e97-4d92-9cc0-c6a3664107ac-screenshot_12_165.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182901Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=07e8f60b6082b1b5cf1cd7552bf9777c674e6fa424559f1fd908b5c2fc5655a3" alt=""><figcaption></figcaption></figure>

#### Next Tutorial: Device Integration

Now that the network segments are established, the next stage of the setup is to populate these subnets with active nodes. In the upcoming video in this series, we will focus on how to add devices to these networks to begin building out your secure, peer-to-peer infrastructure.


# How to Add Devices

{% embed url="<https://youtu.be/kaLYZAK0ddg>" %}

### Purpose

Three Methods to Add Devices to a Netmaker Network

### Introduction to the Netmaker Dashboard

The Netmaker dashboard serves as the central command center for managing your virtual software-defined networks. Upon logging in, you can view all existing networks under the **Networks** tab. This interface allows you to monitor connectivity and initiate the process of expanding your infrastructure.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/3e1e54c4-fc62-4e2a-934f-2e786412e8f2-screenshot_0_0.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182933Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=52097746fbdee60569415b91949a0e4121ee3dc0447620f43d1cef62b0006286" alt=""><figcaption></figcaption></figure>

#### Understanding the Default Network Structure

When managing a specific network, such as the **Cloud Overlay**, you will notice that at least one device is usually already present. This is the server running the Netmaker instance itself (e.g., "demo-server").

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/5bf60a52-f1f4-4d05-81be-18e135806c39-screenshot_1_18.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182933Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=03fa3ccff4b3f0157e3f7645d36ffcff676ea1fc62e5effca85768d77559660e" alt=""><figcaption></figcaption></figure>

It is highly recommended to keep the default server node within the network. This node handles core networking functions, acting as the default GATEWAY, which facilitates traffic flow between network segments and acts as a backup to ensure continuous connectivity if other paths fail.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/ee1b60ff-1bae-4567-ac89-7a674a240316-screenshot_2_36.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182934Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=1ee61d37338c60047af2f4a3baf1db7d88b0b89c9ebb1b30aad72c64c48e1f31" alt=""><figcaption></figcaption></figure>

#### Endpoint Management Tabs

The dashboard organizes network endpoints into three distinct categories, accessible via tabs at the top of the node list:

* **Devices:** Displays nodes running the Netclient agent.
* **Config files:** Shows devices connected via standard WireGuard configuration files.
* **Active Users:** Lists users connected through desktop or mobile applications using managed access.

To scale your network, click the blue **+ Add device** button in the top-right corner. This opens the **Add new node** modal, which presents the three primary methods for integration: the Netclient agent, manual Config files, or User Access based on identity providers.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/21e4ae74-d2b3-4cfe-aeb5-e078774fb131-screenshot_3_54.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182934Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=f483f8fd8322e7adfbb2a2e87482e03bd0c8c09ef2034444c343696c80feed15" alt=""><figcaption></figcaption></figure>

### Method 1: Using the Netclient Agent

The Netclient agent is Netmaker's native binary designed for automated network management on servers and persistent nodes. It is compatible with Windows, Mac, Linux, and Docker environments, providing a seamless way to maintain encrypted connections between devices.

#### Accessing the Installation Commands

To begin adding a device via the Netclient, navigate to the **Add device** modal in the Netmaker dashboard. By default, the **Netclient** method is selected, which displays the firewall requirements and connection options.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/c11ae46a-15e4-4a47-a4f9-17216c492099-screenshot_4_60.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182933Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7d9ff56f096e490b713b9ccce0ab972ab9df1b7cd62907f886479aa70a7e3937" alt=""><figcaption></figcaption></figure>

* Select the **Linux** tab to retrieve the specific commands for Linux systems.
* The dashboard provides two critical code blocks: the installation script (utilizing `wget`) and the join command (containing the unique network token).

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/f8dc5bcc-c8f1-4b87-b947-f163c21feeaa-screenshot_5_74.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182934Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6b8a8a54f3f56a1360d6e56c274100bc18540f3499cd1ca542209638644ea2ce" alt=""><figcaption></figcaption></figure>

#### Installing and Joining the Network

Once you have access to the target Linux cloud VM's terminal or command-line interface, follow these steps to deploy the agent:

1. **Install the Netclient:** Copy and paste the installation command from the dashboard. This multi-part command downloads the Netclient binary, updates file permissions, and installs the service on your system.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/77ef0feb-e0b9-4a76-aad7-b715685e2e94-screenshot_6_102.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182933Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=1ffdf56479a9d6bf78351523293076485e13020d9cae44864d581f1871a41308" alt=""><figcaption></figcaption></figure>

2. **Register the Node:** Execute the join command provided in the dashboard (for example, `sudo netclient join -t <token>`). This command registers the device with the Netmaker server and configures the encrypted WireGuard interface.

After execution, the terminal will confirm the device has successfully joined. You can verify the connection by checking the **Devices** list in the Netmaker dashboard, where the new node will appear with its assigned private network address.

### Method 2: WireGuard Config Files

For devices that do not support the Netmaker agent (Netclient) or the specialized desktop and mobile applications, Netmaker provides a manual integration method using standard WireGuard configuration files. This approach is ideal for legacy systems, IoT devices, or specific edge hardware where installing third-party binaries is not feasible.

#### Generating the Node Configuration

To initiate a manual connection, navigate to the **Add new node** modal within the Netmaker dashboard and select the **Config files** tab. This method creates a static configuration that relies on an existing network node to act as its entry point.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/caa0018e-e403-42a7-ba53-8cab48e43d30-screenshot_8_120.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182934Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ac3c21afbfe57c558b4d342a12b3e0028d273feced21187c112cf9fb6a89df74" alt=""><figcaption></figcaption></figure>

Follow these steps to generate the configuration:

* **Node Name:** Enter a descriptive identifier for the device, such as "edge-server".
* **Gateway Selection:** Select an existing node from the **Select node as gateway** dropdown (e.g., "demo-server") to handle the routing for this manual connection.
* **Create Config:** Click the **Create Config** button to finalize the settings.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/2c8affcc-1deb-41c6-bdf7-dd439e44c9dd-screenshot_9_138.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182933Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=b632a0c4b47845f525f9d457454775d41569a35cb74fa280c8685eb9c948067c" alt=""><figcaption></figcaption></figure>

#### Applying the Configuration Manually

Once the configuration is generated, you must manually apply it to the target device. Locate the newly created node in the **Config files** list, select it, and click **View/Download config**. Copy the provided WireGuard configuration text to your clipboard.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/da2bfc50-e1a8-46e9-b912-638b78bbb6a2-screenshot_10_164.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182934Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=af2153a3c5924adbbfdd393ae30202654cc16496e06a7dcc5219eb3085e76329" alt=""><figcaption></figcaption></figure>

On the target remote device, perform the following steps via the terminal to establish the link:

1. **Create the File:** Use a command like `touch wg-config.conf` to create a new configuration file on the local filesystem.
2. **Edit and Paste:** Open the file using a text editor (e.g., `vim wg-config.conf`) and paste the configuration text copied from the dashboard.
3. **Deploy to System Directory:** Move the file to the standard WireGuard directory using `mv wg-config.conf /etc/wireguard`.
4. **Activate Interface:** Bring the connection online by executing `wg-quick up wg-config`.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/efd986c6-0e24-4665-aca2-a475786fd891-screenshot_11_182.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182934Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=112bd05f43d76bafae30c91e918bf0fd4c271c2556c6b014bb4056a8b6c9f333" alt=""><figcaption></figcaption></figure>

Once the interface is active, the Netmaker dashboard will update the status of the "edge-server" to **Online**, indicating it is successfully routing traffic through the designated gateway.

### Method 3: Netmaker Desktop Application

The third method for adding devices to your network is designed specifically for end-users on workstations or mobile devices using the Netmaker Desktop application. This approach is ideal for managing active user access rather than persistent server nodes.

#### Accessing User Setup

To begin, navigate to the **Nodes** section of your network and click on the **Active Users** tab. This area allows you to manage connections for users authenticated via OAuth, invites, or IDP integration.

* Click the **+ Add device** button and select the **User Access** method.
* Select the appropriate operating system (Windows, Mac, Linux, or Mobile) to see the specific installation instructions for the Netmaker Desktop app.
* Take note of the **Server Domain** or **Tenant ID** (e.g., `api.demo.netmaker.io`) provided in the setup instructions, as this is required for the application configuration.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/eb893150-fb22-4ac7-967a-85a46eda101c-screenshot_12_222.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182933Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7b52d030d616c816da2b7d32b9358e0639960116fd3661b16776c3b372b8bfe4" alt=""><figcaption></figcaption></figure>

#### Configuring the Desktop Client

Once you have installed the Netmaker Desktop application on your local machine, you must point it to your Netmaker server.

1. Open the **Netmaker Desktop** application and click the **Settings** (gear icon) in the top-right corner.
2. Enter the **Server URL** or **Tenant ID** you noted earlier into the designated field and click **Save**.
3. Return to the main screen and log in using your network credentials (username and password).

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/b45166fb-ee7a-4bab-8f16-9a0879fcebc5-screenshot_13_232.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182935Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=f9757a543202c079a6f3a7ede53a7a9069230c2ad11d38f7ddc804db552fec46" alt=""><figcaption></figcaption></figure>

#### Joining the Network

After logging in, the application will display a list of all networks your user account has permission to access. To connect your device to the overlay:

* Locate your target network (e.g., **cloud-overlay**).
* Click the toggle switch next to the network name.
* The switch will turn green, indicating that the device has successfully joined the network and established a secure connection.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/e76dc643-4f81-4a1d-8566-64472361c9e0-screenshot_14_244.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182935Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=0d521b74e493114b0b927bae712e820f4e23eb2ce73ba803af16617acfa533a9" alt=""><figcaption></figcaption></figure>

#### Verifying Connection Status

To confirm the connection from the administrator's perspective, return to the Netmaker Dashboard in your web browser. Under the **Nodes** management view for your network, navigate back to the **Active Users** tab. You should now see the user listed with an **Online** status and a designated **Private Address** within the overlay network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/eb0b9d86-592a-4cea-b01d-4b4a308b6ce3/da0eae72-ffa5-4c38-8be2-2e354907c55d-screenshot_15_252.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T182935Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ba175a539a39be19ac742235472ea1f5c3f93ce0fb6ac28c18efe0cb8d9f5f0b" alt=""><figcaption></figcaption></figure>


# How to Add Egress

{% embed url="<https://youtu.be/CJVqDC_tXxU>" %}

### Purpose

How to Configure Egress Routes in a Netmaker Network

### Introduction to Egress Networking

Egress networking is a powerful feature in Netmaker that enables secure remote access to entire local networks (LANs) through a single gateway device. This eliminates the need to install Netclient endpoints on every individual device at a remote location, such as printers, IP cameras, or legacy servers. Instead, one or more Netmaker nodes act as a router, forwarding traffic from the overlay network into the local site's infrastructure.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/11f906de-1dfc-4ff5-a8ef-84becc15eee7-screenshot_0_0.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183216Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=80ff9c779d2d9b2cfc86d2184a10241218a0086863dd7d281bcbf88ec7dbc49f" alt=""><figcaption></figcaption></figure>

#### Core Concepts and Use Cases

By designating a node as an egress gateway, you can facilitate connectivity for various environments, including:

* **Office Networks:** Providing remote employees access to local file shares and internal resources.
* **Edge and Retail Sites:** Managing IoT devices or point-of-sale systems at distributed locations.
* **Factories:** Accessing industrial equipment on specialized subnets.

#### Prerequisites for Egress Setup

To begin setting up egress, you must first identify the nodes that will serve as the traffic gateways. These nodes must be physically located at the site and have reachability to the local network you wish to expose.

1. Navigate to the Netmaker dashboard and select the appropriate network from the **Networks** menu.
2. Click on the **Nodes** section in the left sidebar to manage your network endpoints.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/a830c600-9980-4606-96de-b319561fc70f-screenshot_1_8.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183216Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6f307a1162dfe8e026deaa682c3ead3a97772f744baf9ddbc93eb55228e46409" alt=""><figcaption></figcaption></figure>

3. Ensure the **Devices** tab is selected at the top of the dashboard to view the connected hardware.
4. Identify the target nodes (e.g., **site-linux-1** and **site-linux-2**) and verify their **STATUS** is **Online**. Having multiple nodes allows for redundant routing if one gateway fails.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/8e525665-22a9-482f-8071-63b0010d4c2e-screenshot_2_56.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183217Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=0adb84bf64bc2321992b0defb611031d81c93e3e067d7d5c3f1e2eff832ddb39" alt=""><figcaption></figcaption></figure>

### Configuring Egress Routes for Netclient Nodes

Egress gateways allow your Netmaker network to reach remote local networks—such as office LANs, retail sites, or factory floors—using a single installed device as a router. This eliminates the need to install Netmaker endpoints on every individual device at the remote site.

#### Initiating the Egress Route

To begin, identify the nodes that will act as the gateway. Ensure they are online and connected to your network. Navigate to the Netmaker dashboard and select the **Egress** section from the left-hand sidebar menu.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/0fe557e6-8981-4fbd-acb8-c633ba3620b7-screenshot_3_70.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183216Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=9fadb34307a2b239fcd58a6f36f77c0f34826fe9ab1f951b86a29784825a1bdd" alt=""><figcaption></figcaption></figure>

1. Click the blue **+ Add route** button located in the top-right corner of the dashboard.
2. In the **Name** field, enter a descriptive label for the route, such as `Remote Site Network`.
3. Provide additional context in the **Description** field, for example, `Edge Location`.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/7a5876fb-8f3b-43d7-8021-c5ca1cd9dbbf-screenshot_4_76.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183217Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=b03e2dd737db666471317fc61e46fc61a515a52a7c0be0f929164e1be8e3d77c" alt=""><figcaption></figcaption></figure>

#### Network and Routing Configuration

After naming the route, you must define the technical parameters for traffic forwarding and target addresses.

* **Enable NAT:** Ensure the **Enable NAT for egress traffic** toggle is switched to the **ON** position. This is the standard setting for most environments unless you have established custom NAT rules manually.
* **Define Subnet:** In the **Egress** field, enter the CIDR range of the local network you wish to reach (e.g., `192.168.57.0/24`).

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/42f8f60a-8f15-4140-b5cc-61befd75e9f4-screenshot_5_100.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183216Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=c1fb7d819b9cf12108e67ae71d35108786680c5c18b5c0b235702221619a03a0" alt=""><figcaption></figcaption></figure>

#### Assigning Nodes and Redundancy

Click **Next** to proceed to node assignment. Netmaker allows you to assign multiple nodes to a single egress route to ensure high availability.

1. From the **Select node** dropdown, choose your primary node (e.g., `site-linux-1`).
2. To implement redundancy, click the **+ Add node** button.
3. Select a secondary node (e.g., `site-linux-2`) from the additional dropdown. If the primary node fails, the secondary node will automatically take over the routing tasks for that traffic.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/95ca9769-5f10-43af-8d6b-d68eaf724369-screenshot_6_110.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=3d6a73ef652176f3cf0658c61ff6b6303a55c2cd5e12370c115d590f09218b77" alt=""><figcaption></figcaption></figure>

### Access Policies and Granular IoT Routes

After defining the target network and assigning gateway nodes, Netmaker allows you to refine who can actually use these routes through access control policies. This ensures that only authorized users or groups can reach the remote infrastructure.

#### Configuring Egress Access Policies

By default, access can be restricted to specific user groups. Within the **Create new egress route** wizard, navigate to the **Egress access policies** step. Toggle the **Users Policy** switch to the **Enabled** position. From the **Source** dropdown, you can select specific groups, such as the **All Networks User Group**, to grant broad access to all network members.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/d6a5a6ae-8c37-499c-847f-ac55e462f4d6-screenshot_7_120.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183216Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=efa108696c98830461faedab3396b99a2f41e6962935c0f45df7e3c7922e7449" alt=""><figcaption></figcaption></figure>

Once the policy is defined, clicking **Finish** will finalize the route. A notification confirming 'Egress Route Created' will appear, and the route will be active immediately.

#### Adding Granular Routes for IoT Devices

Egress routes are not limited to entire subnets; they can be configured for individual IP addresses to provide granular access to specific hardware, such as an IoT camera or a single server.

1. Click the **+ Add route** button on the Egress dashboard.
2. Provide a descriptive name and description, such as **'IoT Device On Site'** and **'Camera running on site'**.
3. In the **Egress** field, instead of a CIDR range, enter the specific IP address of the device (e.g., `192.168.57.45`).
4.

```
<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/8a0f5e43-4fc7-4c9f-9e90-95e691d2f5d7-screenshot_8_164.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=41c2613f75803d1f1c4ea56b02f1df869b0ea0de67cb35d2784dbf90875b76df" alt=""><figcaption></figcaption></figure>
```

5. Assign a gateway node (e.g., **site-linux-1**) to handle the traffic for this specific device.
6. Set a more restrictive access policy if necessary. For instance, you may choose to grant access only to an **'admin'** user rather than a whole group.

After clicking **Finish**, the new granular route will appear in the **Egress** tab alongside your broader network routes, allowing for precise management of remote device access.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/c4477f96-7c61-440a-a6d9-e0e17d31c85e-screenshot_9_192.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d50d5b16bc49e40fc2abf6f5885c2d9ce9d56aeab074c677ed5d70239400615e" alt=""><figcaption></figcaption></figure>

### Configuring Egress via WireGuard Static Configs

For devices where the Netclient cannot be installed—such as hardware routers or specialized IoT appliances—Netmaker allows you to configure egress routing using static WireGuard configuration files. This method involves manually defining additional network addresses and routing scripts within the dashboard before deploying the configuration to the target device.

#### Accessing Configuration Files

To begin, navigate to the **Nodes** section from the left-hand sidebar. Unlike standard nodes, static configurations are managed under a separate view.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/40af32e1-7619-4786-943f-e04c96061855-screenshot_10_206.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ef06f3da95e0e2f4336659cff066753314186a329cb2a743364d11e610c76cf0" alt=""><figcaption></figcaption></figure>

1. Select the **Config files** tab at the top of the Nodes dashboard.
2. Identify the configuration file for your target device (e.g., **'edge-server'**).
3. Click the three-dot menu icon on the right and select **Edit** to open the **Update Config File** modal.

#### Defining Egress Networks

Once inside the configuration editor, you must define which remote networks the device should provide access to. This is handled through the **Advanced Settings** menu.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/0ef6d62e-0526-434a-9a4b-b723c1109ece-screenshot_11_222.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183216Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7175ba9934ec884fd7d3543aaf835d29fdf3e8c1672c5d2502cd1a80afe40e49" alt=""><figcaption></figcaption></figure>

In the **Additional Addresses (Optional)** field, enter the CIDR range of the local network you wish to expose (e.g., `10.45.0.0/16`). These addresses will be automatically added to the `AllowedIPs` section of the generated WireGuard configuration.

#### Implementing Routing and Forwarding Scripts

Because static WireGuard nodes do not benefit from NetClient's automated routing management, you must manually define traffic forwarding rules using **Post Up** and **Post Down** scripts. These are typically implemented via `iptables` to enable NAT masquerading.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/ab371f0c-40ab-4256-a955-f11d3efcbedb-screenshot_12_258.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183217Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=efa57c1855b894a7a680ad2cb23ae664549008c8b68c1a213167075b384aeb2b" alt=""><figcaption></figcaption></figure>

* **Post Up:** Enter the command to enable traffic forwarding when the interface starts. For example:\
  `iptables -t nat -A POSTROUTING -o eth1 -j MASQUERADE`
* **Post Down:** Enter the command to remove the rule when the interface stops to keep the host routing table clean:\
  `iptables -t nat -D POSTROUTING -o eth1 -j MASQUERADE`

*Note: Replace `eth1` with the actual WAN or local interface of your device.*

#### Saving and Verification

After finalizing the settings, click the **Update Config File** button. The dashboard will refresh to show the updated status.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/0fc942bb-e26c-4e1d-a6b9-9ff8bb82f24c-screenshot_13_286.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=0a8cc8f98a980865dbc5589638388bf652284bea7ece7552f067fa3468e05497" alt=""><figcaption></figcaption></figure>

Verify that the new CIDR ranges appear in the **EGRESS** column for that node. Because this is a static configuration, you must now click **View/Download config** to retrieve the updated `.conf` file and manually apply it to your device to finalize the routing path.

### Deploying Updated Configs on Local Devices

When using static WireGuard configuration files instead of the NetClient, updates made within the Netmaker dashboard do not synchronize automatically. You must manually retrieve the updated configuration and apply it to your local edge server or router to activate new egress routes or routing rules.

#### Retrieving the Updated Configuration

To begin, navigate to the **Config files** tab in the Nodes section and click on the specific node name. In the **Client Information** window that appears, select **View/Download config** at the bottom of the screen.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/600d265c-b932-4575-a659-47376e22545b-screenshot_14_292.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6d4dbd33ae6ff6d11d40fa805921bd02681185aa77452a3ceda17cd697af650a" alt=""><figcaption></figcaption></figure>

Copy the generated WireGuard configuration text. It is critical to verify that the `AllowedIPs`, `PostUp`, and `PostDown` lines are included, as these contain the necessary CIDR ranges and NAT masquerading rules for your egress traffic.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/83f43df7-8906-436f-b1c1-ef9cc84c1197-screenshot_15_298.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=5a0a57a97a455e8a45a570e6c12ae20d970a91130a3f2ec712c59be986f6364a" alt=""><figcaption></figcaption></figure>

#### Applying Changes via the Terminal

Once you have the new configuration, access the command-line interface of your gateway node. You must replace the existing configuration file and restart the interface for the changes to take effect.

1. **Shut down the interface:** Disable the current WireGuard connection by running `wg-quick down [config_name]`.
2. **Clean the network device:** If necessary, ensure the device is fully removed by executing `ip link delete dev [config_name]`.
3. **Replace the configuration file:** Remove the outdated file using `rm /etc/wireguard/[config_name].conf`.
4. **Update the file:** Create a new configuration file at the same path using a text editor like **vim** and paste the updated content into it.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/f2fa2c68-3729-46bf-9d88-febf367fef5d-screenshot_16_310.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=702e47326972be711f4f92fff5302cd126894a25b916d246861c345ec093758c" alt=""><figcaption></figcaption></figure>

#### Verifying Egress Parameters

Before finalizing, inspect the file within your text editor. Confirm that the `AllowedIPs` field under the `[Peer]` section includes the remote network CIDR ranges you defined in the dashboard. Additionally, ensure the `PostUp` and `PostDown` scripts correctly reference your local network interface (e.g., `eth1`) for iptables forwarding.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/f56eda8b-1ab6-4546-abf6-7b645845dcbf-screenshot_17_332.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183218Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=23b18820c63a7950c502d5ce2e642e09fb08a308a76e406a114a3940435bc688" alt=""><figcaption></figcaption></figure>

#### Creating New Static Configs

If you are deploying a new node rather than updating an existing one, you can use the **+ Add config file** button in the Nodes view. During the setup wizard, navigate to the **Egress (Optional)** section to define external routes and traffic forwarding rules before the file is generated for download.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/57f5ef7b-1ec3-423a-9e7e-68b8b0c1cb77/daf709ec-8091-4329-b3d7-b821fc54306d-screenshot_18_362.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183219Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=4357f43370b4217a85f1321b2e517ae3884b1aa867226353b6f6561a902ce466" alt=""><figcaption></figcaption></figure>


# How to Create and Configure Gateways

{% embed url="<https://youtu.be/_tYAauDrnSg>" %}

### Purpose

Understanding and Configuring Gateways in Netmaker

### Introduction to Netmaker Gateways

Netmaker Gateways serve as the essential routing points within an overlay network, acting as hubs that facilitate traffic flow between the core Netmaker network and various endpoint devices. They are fundamental to ensuring that devices across different environments can reach the internal network and vice versa.

Additionally, when a direct P2P connection cannot be forged between devices, Netmaker automatically initiates connection over Gateways which have been set as "Auto Relay", their default setting.

#### Gateway Architecture and Supported Endpoints

At its core, a gateway functions as a router. It manages the communication between the Netmaker Network and three specific types of endpoints:

* **User Devices:** Personal devices connecting to the network through client software.
* **WireGuard Configurations:** Standard configuration files that allow non-Netclient devices to participate in the network.
* **Netclients:** Specific nodes where routing through a gateway is preferred over a standard peer-to-peer connection.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/b7ca845d-3229-4dfc-91e7-390d098224c1-screenshot_0_10.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=e9295d212ec1da6f4e4416ff479d0a2a52f6f020c405ebe57e972a25a73296ac" alt=""><figcaption></figcaption></figure>

In addition to internal network routing, a gateway can be configured as an **Internet Gateway**. This capability enables "full-tunnel" traffic, allowing connected devices to route all their public internet traffic through the gateway, providing a secure egress point for the entire network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/a870b560-777d-493d-bd61-ea9e3d6c46fa-screenshot_1_32.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183250Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6d5535a48525b94bbbbe43b00b72eb57304b7af35ac61168095b75345852ee0c" alt=""><figcaption></figcaption></figure>

#### Identifying Gateways in the Netmaker Dashboard

To view and manage the routing points in your network, you must navigate to the dashboard interface. Every network requires at least one enabled gateway to properly route traffic from user devices and WireGuard configuration files.

1. Open the Netmaker Dashboard and navigate to the **Nodes** section using the sidebar menu.
2. Locate specific machines, such as a **demo-server**, to check their current status.
3. Identify active gateways by looking for a blue **GATEWAY** tag appearing beneath the device name.
4. Hover over the tag to confirm that the node is ready to serve as a routing point for other devices in the network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/df60bfa8-ba7a-496b-b7aa-13236564e919-screenshot_2_52.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=3f931005aac1cc10b7b3d76252b4f0d9a1d8496f45c9734bf5af091f103b9d89" alt=""><figcaption></figcaption></figure>

### Attaching WireGuard Configs and Nodes

In Netmaker, gateways act as routing hubs for various network entities. To ensure traffic flows correctly between your overlay network and external devices, you must attach WireGuard configuration files and network nodes to a designated gateway.

#### Creating and Attaching WireGuard Config Files

When generating a new WireGuard configuration file, you must specify which gateway will handle its traffic. This is essential for devices that do not run the native netclient but still need to participate in the network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/5ae23064-d6bc-4fb5-a5a8-d79a8c992087-screenshot_3_74.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d12749e8e25b19d6d153043aa4c0e64172ef2ff7a24ab18df5e3b6ccc6ee19e1" alt=""><figcaption></figcaption></figure>

1. Navigate to the **Nodes** section in the sidebar and select the **Config files** tab.
2. Click **Add device** and ensure the **Config files** method is selected.
3. Enter a unique **Node name** (e.g., 'my-router-1').
4. Use the **Select node as gateway** dropdown to choose an active gateway, such as 'cloud-linux'.
5. Click **Create Config** to finalize the attachment.

Once created, you can verify the association by navigating to the **Gateways** section and expanding the specific gateway to view its attached configuration files.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/3883f415-adcf-4aac-a236-6f88d5012728-screenshot_4_94.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=caf069dd8c9af18f0b6ff85922add6dbfcfdf9d8b0e217246861a839a8b56efb" alt=""><figcaption></figcaption></figure>

#### Assigning Gateways to Existing Nodes

Beyond configuration files, standard Netmaker nodes (netclients) can also be routed through a specific gateway. This is particularly useful for site-to-site connectivity or when certain nodes require a centralized exit point.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/f1db9140-fd2f-4a08-9255-78a665122dd0-screenshot_5_112.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=cbc15a73049ceb883cbb784dd9c9339f5e2628f78d26c319c4350256344f3e8a" alt=""><figcaption></figcaption></figure>

1. In the **Nodes** dashboard, switch to the **Devices** tab.
2. Identify the target node (e.g., 'site-linux-1') and click the **Assign Gateway +** button in its row.
3. In the modal, select the checkbox for the desired gateway (e.g., 'demo-server').
4. Click **Assign Gateway** to apply the routing changes.

After assignment, the gateway management page will reflect the new connection under the **Connected Nodes** sub-tab for that gateway.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/1d2f6920-470a-4920-be12-bfd6b990be58-screenshot_6_124.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=72f3a5a19d9414e4def681a8c431973f0d372365655a0f70ff456b4b8b620e04" alt=""><figcaption></figcaption></figure>

### Auto-Relaying Traffic

By default, Gateways will relay traffic between your devices, in case peer-to-peer connections cannot be established. When editing the Gateway, you can choose to disable this feature by toggling the Auto Relay feature:

<figure><img src="/files/0nrBbv3sy6twdMiJfjxI" alt=""><figcaption></figcaption></figure>

### Connecting User Devices through Gateways

For end-users, the Netmaker Desktop application provides a streamlined interface for connecting to overlay networks. Instead of manual configuration, users can dynamically select which gateway routes their traffic directly from the client interface.

#### Authenticating the Desktop Client

To begin, launch the Netmaker Desktop application on your local machine. You will be prompted to authenticate using your network credentials. Enter your **Username** and **Password** to access the list of available networks and resources.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/9b32ca93-be5a-4b33-a210-0c3930a932ac-screenshot_7_138.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183252Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d07347e9f7e71fed5f0495471c16a5c9b0c50755e5f0687fe291a2750306a1b0" alt=""><figcaption></figcaption></figure>

#### Selecting Networks and Gateways

Once logged in, the application displays the networks you are authorized to join. To configure a connection:

1. Identify your target network (e.g., **cloud-overlay**) from the network list.
2. Expand the network details to reveal connection settings.
3. Use the **Gateway** dropdown menu to select the specific routing node you wish to use, such as the **demo-server**.&#x20;

By default, without selecting a Gateway, the application will automatically select the fastest route amongst the available Gateways.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/fd05e72d-c29e-4eca-affb-70a665f06ff5-screenshot_8_142.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=4c429fcc310e03ecc8182070c77ff008244ea0a430a76f84c16ddee4eeb45553" alt=""><figcaption></figcaption></figure>

#### Establishing the Connection

After selecting the desired gateway, click the toggle switch next to the network name. The client will establish a secure WireGuard tunnel to the selected gateway, integrating the device into the virtual overlay network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/93bdd25f-e913-4ba6-8ce5-e731aaf9ab91-screenshot_9_152.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183252Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7f1b9c131f88343f807e7530255706b94c2df2644ad4b8f1c3343a720e73fc35" alt=""><figcaption></figcaption></figure>

#### Verifying Connection Status

Administrators can monitor these active user sessions from the Netmaker Dashboard. By navigating to the **Gateways** management page and expanding the specific gateway used (e.g., **demo-server**), you can view the **Connected Users** tab. This section provides real-time confirmation of the user's presence, displaying their assigned private IP address and connection status.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/68720a37-8b9e-4eaf-ba46-4641d9191955-screenshot_10_156.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183252Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=a1d1299bd5c1530931b9c13a2c23f41bd2827b83e8011fef97302e6aa56896db" alt=""><figcaption></figcaption></figure>

### Advanced Gateway Options and DNS Configuration

For more granular control over network traffic, Netmaker allows you to configure advanced gateway settings, including full-tunnel internet routing and customized DNS resolution. These settings are typically configured during the gateway creation process or by modifying an existing gateway node.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/fbf5d8e4-b0ec-4abb-880c-0d2e2da4227f-screenshot_11_174.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183251Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=2912873a32f5881cb98e3125c74c8b38bc5b4b955f8d194bb0b2ee90bb66e2bb" alt=""><figcaption></figcaption></figure>

#### Setting Up an Internet Gateway

To enable a node to act as an internet gateway, you must toggle the **Set as an Internet Gateway** option during setup. This configuration enables "full tunnel" mode, where all traffic from connected devices is routed through the gateway node before reaching the public internet. This is particularly useful for establishing secure internet access VPNs.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/1c6b877f-5db6-48ca-a98d-302dd007b948-screenshot_12_186.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183252Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=9830050fe9199581e7ebcb821eab90d3eba743862cd7e3d0d1ce6edcd1d0039e" alt=""><figcaption></figcaption></figure>

1. In the **Gateways** management tab, locate the node you wish to configure.
2. If the node is already a gateway, you may need to delete and recreate the gateway entry to access all configuration options.
3. In the **Create Gateway** modal, select your target Linux node from the dropdown.
4. Toggle the **Set as an Internet Gateway** switch to the **ON** position.

### Conclusion and Summary

Netmaker gateways provide a flexible routing architecture that centralizes traffic management for various network entities. By acting as a primary router, a gateway facilitates communication between the Netmaker Network and external endpoints, ensuring that traffic is directed efficiently and securely.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/0522ff4c-5b4b-4047-a282-273c9770a47e-screenshot_15_300.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183252Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d2cdfe0481d14e873c84ae0cb9b260ac5796022022c87a8d715d93c1a213b24c" alt=""><figcaption></figcaption></figure>

#### Key Gateway Use Cases

A Netmaker gateway supports three primary routing scenarios for devices within or connected to your overlay network:

* **User Devices:** Managing secure access for remote users connecting via the desktop application.
* **WireGuard Config Files:** Routing traffic to and from standard WireGuard configuration files (non-netclient devices).
* **Netclients and Nodes:** While Netmaker defaults to a peer-to-peer model, you can optionally configure specific netclient nodes to route their traffic through a gateway.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/c38a0761-dc3c-4f36-acff-d21b1c573d36-screenshot_16_304.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183252Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=9601fea7d0c2968a887a69bb4102d935bdc9bf8e72befc6b6556a9f268fdaf9e" alt=""><figcaption></figcaption></figure>

#### Full Tunnel Internet Access

Beyond internal network routing, gateways can be configured for Internet access. This "Full Tunnel" setup enables all traffic from a connected device to be routed through the gateway out to the public internet, effectively acting as a professional VPN service for your infrastructure.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b10b72d3-a81d-4eb5-89f2-7447f9adcece/e9bc92c8-f004-464b-99a0-fae49d69dac9-screenshot_17_318.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183253Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=443aa384d55cb1fc3e5395159bcd9c11383350f66f4978fe264cbd5a09fe1064" alt=""><figcaption></figcaption></figure>

Whether managing internal site-to-site connectivity or providing secure internet egress, the gateway system provides the necessary control to scale network architecture according to specific organizational needs.


# How to Set DNS

{% embed url="<https://youtu.be/IN-FLdwVySg>" %}

### Purpose

How to Configure DNS Settings in Netmaker

### Introduction to DNS Levels

Netmaker provides a flexible approach to DNS management, ensuring that name resolution is both automated for internal networking and customizable for specific infrastructure needs. DNS can be configured in three different ways:

**1. Netmaker Private DNS**

This is the built-in, managed DNS solution. It automatically generates DNS entries for every node added to the network. It also supports manual custom IP entries, providing a seamless way to manage internal domain names without external dependencies.

**2. Your Private DNS (Internal Infrastructure)**

For organizations with existing internal DNS servers (e.g., in a physical office or data center), Netmaker can be configured to bridge these services. This typically involves setting up an **Egress** point to the internal nameserver and assigning that server's address to the Network or Gateway level.

**3. Public DNS**

When utilizing the Internet Gateway feature to route traffic to the open web, it is essential to configure public DNS providers (such as Google 8.8.8.8 or Cloudflare 1.1.1.1). This ensures that clients connected to the gateway can resolve public internet addresses effectively.

#### Accessing the DNS Management Interface

To begin managing these records, navigate to the **DNS** section using the left sidebar menu in the Netmaker dashboard. Upon entering this section, you will see the **DNS Records** table.

<figure><img src="/files/kblYraszU0SFaeb6iBdC" alt=""><figcaption></figcaption></figure>

This table displays the automatically generated internal domain names for your nodes. These entries are created the moment a node joins the network, providing immediate connectivity via hostnames rather than raw IP addresses.&#x20;

This table also contains any **custom entries** that you create.&#x20;

### Adding Custom DNS Entries

Beyond automatic records, you can manually create entries to point to specific services or internal servers. This is particularly useful for establishing friendly names for applications running on specific nodes.

1. Navigate to the **DNS** section using the left sidebar menu.
2. Observe the **DNS Records** table to see existing auto-generated records.
3. Click the **+ Add DNS Record** button to open the manual entry dialog.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/7fae7bec-2ec9-4cef-8ea4-1c0ae6db6f8e/b590771a-3ad5-4bdb-8757-7060bcdf1cca-screenshot_4_104.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183310Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=be6cdd4aaf7bbc7a73e43c8cac3ff7fc6ca8613aadc219acc0d51e658f6fcccc" alt=""><figcaption></figcaption></figure>

In the **Create a DNS Entry** modal, define your custom record:

* **DNS name:** Enter the desired hostname (e.g., `app.server`).
* **Address to alias:** Type the target IP address (e.g., `192.168.57.37`) or select a node from the dropdown.
* Click **Create DNS** to save the record.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/7fae7bec-2ec9-4cef-8ea4-1c0ae6db6f8e/96e361b6-0bed-4928-af95-2a18a4872210-screenshot_5_120.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183310Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ec311bf670ea084e56e92064571178a6e9e8648a561eed635d08b296cf93d906" alt=""><figcaption></figcaption></figure>

#### Configuring Name Servers

If your infrastructure includes a dedicated internal DNS server (for example, at a remote office or data center reachable via an Egress gateway), you can configure your resources to use that specific nameserver for specific match domains. You can also specify public nameservers here.

1. Ensure you have identified the IP address of your DNS server, and ensure it is reachable from your network. Gor private nameservers, this is typically accomplished via **Egress**.
2. From the **DNS** dashboard, navigate to the **Nameservers tab** and click the **Add Nameserver** button in the top-right corner.
3. From here, you have many options to configure your nameserver, including:
   1. Name: identify the nameserver
   2. nameservers: the IP address(es) for this configuration
   3. Match domains: which domains this nameserver should work for
   4. Peers: Specifies which groups of resources this will be applied to

<figure><img src="/files/shg3z0U9oale41XP6HsO" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/M2Zx10u1R7BwXbSWJFfF" alt=""><figcaption></figcaption></figure>

Click **Create** to apply the nameserver settings to the network.

Applying these settings ensures that all devices within the network use the specified servers for their DNS queries, allowing for seamless integration with existing private infrastructure.

### Device-Level DNS Settings

Device-level DNS configuration provides the most granular control within Netmaker, allowing administrators to toggle DNS management for individual nodes or define specific nameservers for WireGuard configuration files. This is particularly useful for troubleshooting or for devices that require specialized DNS routing.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/7fae7bec-2ec9-4cef-8ea4-1c0ae6db6f8e/b028bfcd-1114-4147-9448-9dbc157d1fed-screenshot_10_240.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183311Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=80744c67de67de363c9a4d54d49898eddbade2227929d814cad7cc1fcf3aea69" alt=""><figcaption></figcaption></figure>

#### Managing DNS on Individual Nodes

For devices running the Netclient, you can manually enable or disable the software's ability to manage the system's DNS settings. This is handled through the node edit interface.

* Navigate to the **Nodes** section in the left sidebar and select the device you wish to configure.
* In the **Update device** modal, locate the **DNS** toggle switch. Enabling this allows the NetClient to configure the node's local DNS to resolve internal network names.
* Click **Update Device** to save the preference.

#### Custom DNS for WireGuard Configurations

When generating manual WireGuard configuration files for external clients, you can specify a custom DNS server that the client will use once the tunnel is active.

1. From the **Nodes** screen, click on the **Config files** tab at the top of the page.
2. Find the specific configuration file (e.g., **edge-server**) and select **Edit** from the options menu.
3. Expand the **Advanced Settings** section to reveal additional parameters.
4. Locate the **DNS (Optional)** field and enter the desired DNS server IP address. This ensures that any client using this specific configuration file will resolve queries through the defined provider.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/7fae7bec-2ec9-4cef-8ea4-1c0ae6db6f8e/06f190c4-154a-4d85-b1b7-2448823a0a42-screenshot_11_250.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T183310Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=cf9b39cdf427c56d67f3fde548f610b85776d0cb50eae08f4f314c3c8fb02886" alt=""><figcaption></figcaption></figure>


# How to Add Users

{% embed url="<https://youtu.be/8sMID1iZIJE>" %}

### Purpose

Adding and Managing Users in the Netmaker Platform

### Identity Provider (IDP) Integration

Integrating an external Identity Provider (IDP) is the most efficient method for managing access at scale within Netmaker. By synchronizing with a provider like Google Workspace, you automate user onboarding and group management, ensuring that users have appropriate access levels based on their organizational roles.

#### Configuring Google Workspace Synchronization

To begin the integration, navigate to the **Settings** gear icon in the bottom-left corner of the sidebar and select the **Security & Authentication** tab.

In the **Identity Providers Integration** section, locate the Google option. Netmaker offers two levels of integration: a basic **Setup OAuth only** option for external login and a full **Integrate** option for automated synchronization. To enable full synchronization, click the **Integrate** button.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/3c483309-c4d9-4ec5-ac8e-5b601581b514-screenshot_1_32.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184141Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=94e8a6d23705ef7f37e9c6daaec7afcee1f7100efd3a998155a4b119a72f0a43" alt=""><figcaption></figcaption></figure>

A configuration wizard will guide you through the connection process. Review the **Required Permissions** listed in the modal and click **Get Started**. You will be prompted to follow on-screen instructions for the Google Cloud Console, including creating a project and configuring the OAuth consent screen. Once the Google Cloud project is ready, enter the **OAuth client ID** and **OAuth client secret** into the provided fields in Netmaker to finalize the connection.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/d3fe821e-81ea-40ac-b839-d1e490a9b86e-screenshot_2_46.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184140Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=01d74a443d9ff1c8a31659426f6288a02b6a3001ed6f5d07e5f4831ec7763eea" alt=""><figcaption></figcaption></figure>

#### Authentication Security Policies

Beyond IDP integration, you can manage global platform security via the **Authentication Security** panel. Here, you can toggle **Basic Authentication** to enable or disable manual credential-based logins. For organizations requiring high security, you can toggle the **Enforce Multi-factor Authentication** switch to require MFA for every user on the platform.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/b3c65342-3bc3-475e-a2ad-38b70ee482ce-screenshot_3_66.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184141Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=825a281b7d8a98fb7c157910b325433a7535d240ecde388593616b024b4b32eb" alt=""><figcaption></figcaption></figure>

Additionally, you can manage the **JWT Validity Duration**, which determines how long a user session remains active before a re-authentication is required. The default is set to 720 minutes but can be adjusted to meet your organization's security posture.

### Authentication Security Settings

Beyond external identity provider integration, Netmaker provides a dedicated panel for managing core security protocols, including manual login permissions and session persistence. These settings are critical for defining the baseline security posture of your network management platform.

#### Access and MFA Controls

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/266bd70d-a34c-4e89-886b-03681a3cabe2-screenshot_4_66.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184141Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6ca24731dccdb680601c6930629e6a05c266f5aa6a029a89c75e708ff4e266a3" alt=""><figcaption></figcaption></figure>

Within the **Authentication Security** panel, administrators can govern how users access the platform. This includes a toggle for **Basic Authentication**, which allows or restricts the use of manual username and password credentials. For environments requiring higher security standards, you can toggle **Enforce Multi-factor Authentication**. When enabled, this requires all platform users to provide a second form of verification before they are granted access.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/9dbf5421-cb4e-4039-998f-bf298490a7eb-screenshot_5_70.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184141Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d8240df38e9277f20d332a6da91d658ccaed7c0836f5704f79fdb69d2a909bae" alt=""><figcaption></figcaption></figure>

#### Session Management

Session persistence is managed via JSON Web Tokens (JWT). The **JWT Validity Duration** setting determines how long a user remains logged into the dashboard or application before their session expires and they are required to re-authenticate.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/9ff940aa-905a-4d4d-909c-46ba267d68ba-screenshot_6_76.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184141Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=f6f819aa107c95ce95d716ab13356f1472710c1c3a97ef2681d99b0ecfd3f311" alt=""><figcaption></figcaption></figure>

The default session length is set to **720 minutes** (12 hours). To adjust this duration to better suit your organizational security policies, click the **Edit** button next to the value and enter the desired time in minutes. This ensures a balance between user convenience and the risk of unauthorized access via stale sessions.

#### Reviewing Integration Status

Once your security settings are configured, you can verify your active integrations by returning to the **Security & Authentication** tab. This view allows you to see the details of configured providers, such as Google Workspace, including the Client ID and admin contact information, ensuring all security layers are correctly aligned.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/97836bd3-f028-4fd4-8936-3108d74c503a-screenshot_7_94.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=5a7ba865bfc9bd64fe5beb69e6192dded0c7b1b1d0157e61da378cb09963a110" alt=""><figcaption></figcaption></figure>

### Manual User Creation and Access Levels

While automated Identity Provider (IDP) synchronization is efficient for large organizations, Netmaker provides a robust manual user management system for creating local accounts and defining granular access controls.

#### Creating a New User

To manually add a user, navigate to the **User Management** page from the left-hand sidebar and click the **+ Create User** button in the top-right corner. This opens a modal where you must define the user's primary credentials and permission scope.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/033c1b9b-8b2a-4fbd-80a3-dbdc0543e4f9-screenshot_8_118.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=262763a26fe7d285c5f7a4f253e58666135ce88457ff45851d1965fcd343e47a" alt=""><figcaption></figcaption></figure>

1. **Identify the User:** Enter a unique identifier in the **Username** field and set a secure password.
2. **Assign Access Level:** Select the appropriate radio button to define the user's global platform permissions.
3. **Finalize:** Once details are entered and roles are assigned, click **Create User**. A confirmation toast will appear in the top-right corner.

#### Understanding Platform Access Levels

Netmaker utilizes three distinct access levels to ensure the principle of least privilege is maintained across the network infrastructure.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/55c00a86-a38c-4b2a-889b-8bfc19891e79-screenshot_9_124.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184141Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=c44227296d84d60902156ce410f64f953cd290b7eb2bc8bd724030481d6cf3ee" alt=""><figcaption></figcaption></figure>

**1. Admin**

Admins hold full system-wide permissions. They can manage all users, add or remove devices, configure global settings, and oversee every network within the platform. This level is intended for primary infrastructure maintainers.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/31150c12-d5a7-49c9-933c-47e887cbf4ca-screenshot_10_130.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ba4ddf978999ba0796de8b04508bd9cf2ee05ef8f29234184be7bf581f822c4e" alt=""><figcaption></figcaption></figure>

**2. Platform User**

Platform Users are granted dashboard access but are restricted to specific network administration duties. Their access is dictated by group membership. For example, assigning a Platform User to a 'cloud-overlay Admin Group' allows them to act as an administrator only for that specific network environment.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/4219d13a-ab39-4fe9-8aba-72c6b4f2a63a-screenshot_11_136.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=38ec74d0c8e2fd7459b7c931376ea760b93964dc71db21dda447b1d52e62ae9d" alt=""><figcaption></figcaption></figure>

**3. Service User**

Service Users are restricted accounts designed for standard end-users who do not require dashboard access. These users cannot log into the web UI; instead, they use the Netmaker Desktop application to connect to their assigned networks. Access is managed by adding them to specific user groups, such as an 'Office User Group'.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/10ced52a-bbec-4dea-9f80-484a65832cb9-screenshot_12_142.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=4c5bd2ff07f21d181ff7ca2942e445ca9018193febb4e0b2ddd53fc2cbf1b7cb" alt=""><figcaption></figcaption></figure>

**4. Auditor**

The Auditor role will gain full **read-only** access to the platform on the specified networks.

#### Post-Creation Management

Once created, users appear in the User Management table. From here, you can monitor their **Status** (Enabled/Disabled) and **Auth Type**. If you need to manage network-specific roles more granularly, you can navigate to the **Groups** tab to create custom groups and assign roles like 'admin' or 'user' to specific networks.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/ff159af8-58e6-4c5f-8e72-b56bd7059e82-screenshot_13_156.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184143Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=fdda3a150798e4c9893b93175321937f5b01366f54f253b6df5719f6fc689d0c" alt=""><figcaption></figcaption></figure>

### Group and Role Management

Netmaker utilizes a group-based system to manage granular access permissions across various networks. This allows administrators to define whether a user acts as an administrator or a standard user for specific network segments, ensuring the principle of least privilege.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/1a935877-9a18-41b4-8037-7c0210c6f389-screenshot_14_202.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184144Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=f6c74ba782417415561f434d5e066e0761232e824b5b211fdff83b1fd7e6ca12" alt=""><figcaption></figcaption></figure>

#### Configuring Default and Custom Groups

While the platform automatically generates default groups for basic administrative and user roles, you can create custom groups for more specific use cases. To create a new group, navigate to the **Groups** dashboard and click the **+ Create Group** button. In the resulting modal, provide a unique **Group Name** and a description to identify the group's purpose.

The core of group management lies in the **Associated Network Roles**. Within this section, you can use a dropdown menu for each specific network to assign roles. Currently, these roles include:

* **Admin:** Grants full management rights over the specific network.
* **User:** Grants standard access to the network without administrative privileges.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/813d76a6-ecaf-4ec0-b8f6-7409c768b29f-screenshot_15_208.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ff7329465594167cefe4b534513b29329eb609ac8bbb4eb23c428f202c872b4c" alt=""><figcaption></figcaption></figure>

#### User Onboarding via Invitations

Beyond manual user creation, Netmaker supports an invitation workflow that streamlines onboarding. By clicking the **Invite User** button from the main dashboard, you can enter multiple email addresses to invite users in bulk. This system requires a configured SMTP server to send automated email invites.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/93883508-effb-4ef5-bfb6-7bd5d0ab675e-screenshot_16_224.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=baafaae1113bd43189fa39bfd3ca05fc76313efeec56b07b4ad8521f921ba52f" alt=""><figcaption></figcaption></figure>

When sending invitations, you must define the **Platform Access Level** (Admin, Platform User, or Service User). This sets the global permission for the invited user before they are assigned to specific network groups. Once configured, clicking **Create User Invite(s)** initiates the delivery of the invitation tokens.

You can monitor the status of sent invitations and manage pending enrollment sign-ups by navigating to the **Invites & Requests** tab at the top of the interface.

### Email Invites and Pending Requests

Netmaker provides streamlined methods for onboarding users through automated email invitations and a self-service sign-up queue. These features allow administrators to manage growth without manually creating every individual account.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/1765d725-d7e9-4af4-a4ed-3dbc050627b9-screenshot_17_240.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184143Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=79b117f598f41c43a939d920d1403f3494007723b4baadf2062449cc49f6c029" alt=""><figcaption></figcaption></figure>

#### Sending Email Invitations

To invite new members to the platform via email, navigate to the **User Management** section and select the **+ Invite User(s)** button. This workflow leverages your configured SMTP server to send automated onboarding emails.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/2d3c679f-a49d-4dd5-aff0-4bb08144bd24-screenshot_18_260.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184142Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=47e83cc6a38254d17451717e9aa35033d02c9bc38ced3233272aa8cf34671214" alt=""><figcaption></figcaption></figure>

* **Recipient Entry:** In the invitation modal, enter one or more email addresses. Multiple addresses should be separated by commas.
* **Set Access Level:** Choose the initial **Platform Access Level** (Admin, Platform User, or Service User) that the invitees will receive upon joining.
* **Finalize:** Click **Create User Invite(s)** to dispatch the emails.

#### Managing Pending Sign-Up Requests

Users who have initiated a sign-up through the Netmaker Web UI or the Netmaker Desktop application without an invitation will appear in the **Requests** section. This acts as an approval queue to ensure only authorized individuals gain access to the network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/c649691e-6add-48fc-97c0-685f72515a7d-screenshot_19_244.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184144Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=2c364dfa12fa3228ba91d85afeb9f998142f9743218e2a978ddc7fbfd399a038" alt=""><figcaption></figcaption></figure>

To manage these users, navigate to the **Invites & Requests** tab and scroll to the **Requests** table at the bottom of the interface. Here, you can review the pending list and approve users individually. Once approved, you can assign them to specific network groups and define their platform permissions.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/b3daad90-eb99-4a97-99d2-0c0b17fc5a23/5743e31a-0082-4196-a0a5-b65742a07b81-screenshot_20_250.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184143Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=cc86314712a8d4c38a397391c53888bf29f0b4e697b334e20e9a8b8e84202986" alt=""><figcaption></figcaption></figure>


# How to Manage Access Controls - ACLs

{% embed url="<https://youtu.be/DtPyhZJMv58>" %}

### Purpose

How to Configure Access Controls and Zero Trust Policies in Netmaker.

### Introduction to NetMaker Access Controls

Netmaker Access Controls provide a robust mechanism for managing communication across your virtual network. This feature allows administrators to define granular rules governing how devices, users, and network routes interact with one another.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/56aa5b31-9a57-49bc-8bcb-217223c9e507-screenshot_0_0.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184229Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=3c082c5127ef06dfecb54390f8611300ca4e18d711c342608005a2d581df8972" alt=""><figcaption></figcaption></figure>

#### Navigating the Access Control Pane

To begin managing your network permissions, navigate to the **Access Control** section in the NetMaker dashboard. This pane displays the current list of policies and general network communication settings.

#### Default Connectivity Settings

In a fresh installation, NetMaker typically includes default controls that permit broad access, effectively allowing any device to communicate with any other resource. These default settings ensure that the network is functional immediately upon deployment. However, to achieve a secure, Zero Trust environment, these broad rules are intended to be replaced with specific, least-privileged access policies that you define based on your security requirements.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/04890e7f-a0a5-4ec5-ba12-92aaebe750e6-screenshot_1_15.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184229Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=a1a06c4e75ac8fc5f589aa79adc021583204ca94f106b6c605ca46be38ce0d5e" alt=""><figcaption></figcaption></figure>

### Creating Custom User Policies

Netmaker allows for the creation of specific user-based policies to control how different user groups interact with network resources. This granular control is essential for moving away from broad default permissions toward a Zero Trust security architecture.

#### Initiating a New Policy

To begin creating a rule, navigate to the Access Control pane and click the **+ Add Policy** button located in the top-right corner of the interface.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/a870536a-45f0-4c8f-9f13-785fe600f349-screenshot_2_34.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184230Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=aa45526c9a974e305e6c3f69b095da90cfe8d2f0100505d4c6bbc7788b152569" alt=""><figcaption></figcaption></figure>

In the **New policy** modal, locate the **Policy for** section and select the **Users** button. This designates that the access rule will apply to specific user identities or groups rather than device tags.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/f4b36c21-81bb-47d8-9eeb-4fb24915f265-screenshot_3_44.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184230Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=f190d72a6d60dbf7b636dfcdcf6611b07e42afd70df8ce5886f2f444d432b678" alt=""><figcaption></figcaption></figure>

#### Configuring Service and Identity

Provide a clear, descriptive **Policy name**, such as `ssh-site-1-access`, to identify the rule's purpose. For the **Service**, select **SSH** from the dropdown menu; notice that the **Port** field automatically updates to the standard port 22.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/1fb85e35-273c-4ac6-b412-07e6b91c57e5-screenshot_4_64.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184231Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=2852ee01903a68ef3b0088b0b078fda2788679bfb2f50b40f8ad16c34b9e65ab" alt=""><figcaption></figcaption></figure>

#### Defining Source and Destination

To complete the policy, you must define the flow of traffic:

* **Source:** Click the Source dropdown and select the relevant group, such as the `cloud-overlay User Group`.
* **Destination:** Click the Destination dropdown, switch to the **Egress Routes** tab, and select the target network (e.g., `Remote Site Network 192.168.57.0/24`).

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/44d893dc-b60c-4644-9ccc-db4b4f59b249-screenshot_5_82.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184230Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d6b3375b0335b5f7658fc838c8f7331ef5976f3ff720fdf62081f8a6fbcfd62c" alt=""><figcaption></figcaption></figure>

After clicking **Save**, the new policy will be listed in the dashboard. To fully secure the network, identify broad default rules—such as those granting "All Users" access to "All Resources"—and click the trash can icon to delete them. This ensures that only the specific permissions you have defined are active.

### Grouping Devices with Tag Manager

NetMaker's Tag Manager allows you to create custom labels for groups of devices, significantly simplifying the management of access control policies. By grouping resources under a single tag, you can apply security rules to multiple nodes simultaneously instead of configuring each one individually.

#### Creating a Custom Device Tag

To begin organizing your infrastructure, navigate to the **Tag Manager** section in the left-hand sidebar of the NetMaker dashboard.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/9bd73511-df0a-4209-9d58-cd1b853372fb-screenshot_6_98.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184230Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=2e5b69c31f482b08965b607c619d7bee95f64be9f8b2cbe91182ee935f8a3780" alt=""><figcaption></figcaption></figure>

Inside the Tag Manager, click the **+ Add Tag** button located in the top-right corner to open the creation modal. Follow these steps to define your new device group:

* **Visual Identification:** Select a color tile (e.g., red) to help visually distinguish this group in the dashboard.
* **Naming:** Type a descriptive name into the **Name** field, such as `site-devices`.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/cbb02f12-10bf-4dcb-8689-3b367df8c99c-screenshot_7_108.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184230Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=96ba29c3864fae5f6f01b6cbde17b623a97a94b8b2b3f5f37a0cbf2581130dcd" alt=""><figcaption></figcaption></figure>

Next, use the **Grouped Devices** dropdown menu to select the specific nodes you want to include in this group. For example, you might select `site-linux-1` and `site-linux-2` to group devices located at a specific physical site.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/19971ca9-f23e-4aa6-9c34-aee7444d3073-screenshot_8_112.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184231Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6a7f9166d84682269b665d86fb7cccfc0cbb0ccd71a424ba2b8fa7a42125e207" alt=""><figcaption></figcaption></figure>

Once your devices are selected, click the **Create Tag** button to finalize the group. You can now return to the **Access Control** pane to use this tag as a destination or source in your network policies, enabling streamlined management of communication rules across your entire deployment.

### Advanced Policy Features and Zero Trust

Netmaker provides advanced policy controls that allow for granular device-to-device communication, moving beyond simple user-to-resource rules. By leveraging these features, administrators can implement a Zero Trust architecture where only the minimum required permissions are granted.

#### Applying Policies to Tagged Resources

Instead of creating individual rules for every machine, you can apply policies to entire groups of devices using the Tag Manager. When creating a new policy, navigate to the **Destination** selection and select the **Tags** tab.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/858bb7d2-828a-4f57-bddd-bb0ca5acb734-screenshot_9_122.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184231Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=420e23e2c8a93ac77f16130983bd6b8eed4e487fb822e90b921b11ff3749a971" alt=""><figcaption></figcaption></figure>

By selecting a tag, such as `# site-devices`, the policy automatically applies to all nodes currently assigned to that tag. You can then define the origin by selecting a specific node from the **Devices** tab under the **Source** menu.

#### Configuring Traffic Directionality

A key feature for device-level policies is the ability to define the flow of traffic. Within the policy configuration window, you can toggle the directionality icons located between the source and destination selections.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/0c98ec07-dc65-4d0e-8177-e1a86788c3f8-screenshot_10_138.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184230Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=c7f772813ea9d8ec11413fdd61284382cc8064b24a9933b20e6902a1c0cd5646" alt=""><figcaption></figcaption></figure>

* **Bi-directional:** Allows traffic to flow freely between both the source and destination.
* **One-way:** Restricts communication so that only the source can initiate connections to the destination, which is ideal for isolating sensitive infrastructure.

#### Granular Service and Port Control

To further harden the network, policies should be restricted to specific services. NetMaker offers a pre-defined list of common protocols like SSH, HTTP, and HTTPS. Selecting these will automatically populate the standard port associated with that service.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/d8aa093b-f083-4b48-be32-d2c87d40b6fa-screenshot_11_148.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184231Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=da659db7d04d78f48baf5445bce1c61cb6d15913f2e1678cbc910af08e095350" alt=""><figcaption></figcaption></figure>

If a service is not listed, select the **Custom** option. This allows you to manually define a specific port number, ensuring that only the intended application traffic is permitted through the overlay network.

#### Transitioning to a Zero Trust Model

By default, Netmaker may allow broad access to facilitate initial setup. To achieve a Zero Trust state, it is recommended to define specific policies for every required communication path and then remove default wide-access rules. You can manage these rules directly from the **Access Control** dashboard using the toggle switches in the **Active** column.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/f35242ec-cb1e-4e41-8595-4fb25edf03b4/38f3b1e4-664f-426f-9371-148c81c5fc08-screenshot_12_162.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184231Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7ecd07c712577a10a3050820317cdb1f3f38778ba65e772a30917b363b8675a8" alt=""><figcaption></figcaption></figure>


# How to View Metrics and Audit Logs

{% embed url="<https://youtu.be/arhvPJkm1zk>" %}

### Purpose

Netmaker Tutorial: Network Analytics and Auditing Overview

### Monitoring Node Performance and Connectivity

Netmaker provides a dedicated Analytics pane to help administrators monitor the health, performance, and reliability of their network nodes in real-time. This interface is essential for identifying connection failures and tracking data throughput across the overlay network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/9289356d-abf5-4d1d-88c5-31b6f6f14940-screenshot_0_16.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184204Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=d047a692c5df4c67a89406477fdcf4b31204bbed1597eeab20a5b3f0b1a8b1bb" alt=""><figcaption></figcaption></figure>

#### Accessing the Analytics Dashboard

To begin monitoring your devices, navigate to the **Analytics** section by clicking the corresponding icon located in the bottom-left sidebar of the Netmaker dashboard. By default, the interface opens to the **Metrics** tab, which serves as the primary hub for node-specific performance data.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/43fa131f-6999-4777-ab9f-c8ad02fff52f-screenshot_1_24.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184204Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=0206630a50e33083a4b2379992cb7e68b02c9709c7e9153e01c08de1705e249c" alt=""><figcaption></figcaption></figure>

#### Evaluating Peer-to-Peer Metrics

To view detailed telemetry for a specific device, select a node from the **Nodes** list on the left-hand side (for example, *'cloud-linux'*). This will populate the dashboard with metrics relative to its peer connections, allowing you to audit the following:

* **Connectivity Status:** The **Connectivity** column provides an immediate visual indicator of connection health. A green checkmark indicates an active, live connection, while a red 'X' signals a connection failure between peers.
* **Data Throughput:** Monitor the **Bytes Sent** and **Bytes Received** columns to track the volume of traffic moving between specific devices, which is useful for identifying high-bandwidth consumers or network bottlenecks.
* **Reliability and Uptime:** Review the **Uptime** column to evaluate the percentage of time a connection has remained stable. This metric is critical for assessing the overall reliability of your network infrastructure.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/d0006175-a271-4481-9009-2aee4b933964-screenshot_2_34.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184205Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=7afe25ec1ecb9c94584ae57ede31b7bc02b91ff89fd5a2f3c0bd771a486d4e4a" alt=""><figcaption></figcaption></figure>

### Visualizing Network Topology and Geography

Netmaker provides several ways to visualize the structure and physical distribution of your network nodes. These tools allow administrators to verify network configuration at a glance and understand the physical and logical relationships between devices.

#### Accessing Network Configuration

To review the foundational settings of your current network, navigate to the **Network Info** tab within the Analytics pane. This section displays essential metadata including the network name, assigned IPv4 ranges, and IPv6 configurations.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/61c24a2c-c942-49a2-9cf0-e1c2da307e59-screenshot_3_50.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184204Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=ee580780c4fb1180fc38bd6a97d8398f3d16d94725b29fc24bc95d5fb29c1178" alt=""><figcaption></figcaption></figure>

#### Geographic Device Mapping

Introduced in version 1.0, the **Graph** tab provides a geographic visualization of your infrastructure. By selecting this tab, you can view a global map that plots the physical locations of your network devices based on their connection data.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/94cffe8d-ccc1-49f3-a8be-c4bff60f042c-screenshot_4_52.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184205Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=aa4e016f891b14bd08a18c07d09a4d88ec02522a064b753f91faafb8b0e36636" alt=""><figcaption></figcaption></figure>

#### Legacy Connection Topology

For a more technical view of device interconnectivity, use the **Switch to Graph** button located in the top-right corner of the map view. This legacy graph displays a traditional network topology diagram. This visualization is particularly useful for identifying which specific devices are establishing peer-to-peer connections and verifying the overall health of the mesh network architecture.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/bb1b3eb8-001b-4570-8c7e-1299dd5e64f7-screenshot_5_56.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184205Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=10d998f9f639c04c2c4782bc5fde2774362b543d57d5b41182bdeea3a4ae2a25" alt=""><figcaption></figcaption></figure>

### Auditing Platform and Connection History

Netmaker provides a dedicated suite of auditing tools designed to help administrators monitor both configuration changes and the real-time connectivity status of the network. This ensures high visibility into who is accessing the network and what changes are being made to the platform infrastructure.

#### Visualizing Device Connections

To understand the current state of your network before reviewing historical logs, navigate to the **Graph** tab within the **Analytics** pane. This visualization allows you to identify the physical and logical topology of your network, showing exactly which devices are currently connecting to one another.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/1249b34e-cd82-4cd7-a75a-2bb968272e7a-screenshot_6_60.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184204Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=aaa1b3af7f375dd09b0aeee12f53d1cc0e8aa4a0e0db5bf170efb0aafdef426b" alt=""><figcaption></figcaption></figure>

#### Accessing the Activity Logs

For detailed auditing, switch to the **Activity** tab located next to the Graph tab. This section serves as the primary ledger for all significant platform events.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/acbc6a87-0156-4f71-98a2-a84d9ec1a822-screenshot_7_64.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184205Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=b582a2d7329023a5c7e8ab2947b75b11b7fdd75e7c1260ddf42cbf638dd1136b" alt=""><figcaption></figcaption></figure>

The Activity page provides a timestamped record of platform interactions, allowing you to audit the following:

* **Administrative Actions:** Review the creation of tags, updates to access policies, and other high-level configuration changes to see "what was created, by whom, and when."
* **Connection History:** Track user and device connectivity, including specific timestamps for when a device joined or left the network.
* **System Events:** Monitor general platform actions to ensure compliance and security standards are maintained across the network.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/2811132c-e538-44a1-93c8-c5c710594a5d-screenshot_8_66.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184206Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=6013c89a0120323a39db6a3a196d50c66eb10778fbe1bf1b82fbda6a286e03ce" alt=""><figcaption></figcaption></figure>

### External Data Export and Advanced Monitoring

While the Netmaker dashboard provides built-in tools for real-time monitoring, advanced users may require external tools for long-term data retention, custom alerting, and complex visualization. Netmaker supports exporting network analytics data to industry-standard monitoring stacks.

#### Prometheus Integration

For comprehensive server-side monitoring, you can export your network analytics to **Prometheus**. This allows you to collect and store time-series data related to your network's health and performance. Because this feature is configured on the server side, it provides a centralized way to aggregate metrics from all nodes across your overlays.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/967de0e9-e88f-4550-8541-504e7fa3e9f5-screenshot_9_86.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184205Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=b7e660fbd9f14098f9624dae12c2031748332f652a85d4d583c5b5b4ad5a1b15" alt=""><figcaption></figcaption></figure>

#### Advanced Visualization with Grafana

To complement the Prometheus data export, Netmaker offers a pre-configured **Grafana dashboard**. By using the provided metrics exporter, you can gain deeper insights into network activity through detailed charts and graphs that go beyond the standard dashboard views. This is particularly useful for identifying trends in data transfer or connection stability over long periods.

<figure><img src="https://limesync-general-production.000da24485a2eb1df827157d23f74fdc.r2.cloudflarestorage.com/c0d109fb-1725-4769-a8ed-443da5e18a40/6681c732-5ec0-44f2-a03e-ba3f00c20d36/d699ebcd-6b72-4951-abb9-a8e9c0f6094c/afc39e64-806c-465b-9ed9-f0a598fa43ee-screenshot_10_105.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&#x26;X-Amz-Credential=934e8b232ee153ba21e195ef724a2066%2F20260121%2Fauto%2Fs3%2Faws4_request&#x26;X-Amz-Date=20260121T184205Z&#x26;X-Amz-Expires=3600&#x26;X-Amz-SignedHeaders=host&#x26;X-Amz-Signature=867559947420829d0abec92cfcecee60a92dec4c06f052f88109f0a8e31c1d65" alt=""><figcaption></figcaption></figure>

#### Implementation and Setup

To implement advanced monitoring, follow these high-level requirements:

* **Consult Documentation:** Refer to the official Netmaker Documentation for the specific configuration parameters required for the metrics exporter.
* **Server-Side Configuration:** Ensure you have access to the server environment, as Prometheus exporting is handled at the infrastructure level rather than through the client UI.
* **Import Dashboards:** Use the default Grafana dashboard templates provided by the Netmaker team to quickly visualize your exported metrics.


# Server and Client Management


# Server Installation


# Advanced Options

This section provides in-depth installation and configuration options for Netmaker, including the Netmaker Server, Netmaker UI, MQ Broker, and Reverse Proxy.

## System Compatibility

Netmaker requires elevated privileges on the host machine to perform network operations. Netmaker must be able to modify interfaces and set firewall rules using iptables.

Typically, Netmaker is run inside of containers, using Docker or Kubernetes.

Netmaker can be run without containers, but this is not recommended. You must run the Netmaker binary, CoreDNS binary, database, and a web server directly on the host.

Each of these components has its own individual requirements and the management complexity increases exponentially by running outside of containers.

For first-time installs, we recommend the quick install guide. The following documents are meant for more advanced installation environments and are not recommended for most users. However, these documents can be helpful in customizing or troubleshooting your own installation.

## Server Configuration Reference

Netmaker sets its configuration in the following order of precedence:

{% stepper %}
{% step %}

### Environment Variables

Typically values set in the Docker Compose. This is the most common way of setting server values.
{% endstep %}

{% step %}

### Config File

Values set in the `config/environments/*.yaml` file.
{% endstep %}

{% step %}

### Defaults

Default values set on the server if no value is provided in configuration.
{% endstep %}
{% endstepper %}

In most situations, if you wish to modify a server setting, set it in the netmaker.env file, then run:

* docker kill netmaker
* docker-compose up -d

### Variable Description

NM\_EMAIL\
Default: “”\
Description: Email used for SSL certificates

NM\_DOMAIN\
Default: “”\
Description: Public IP of machine

SERVER\_HOST\
Default: (Server detects the public IP address of machine)\
Description: The public IP of the server where the machine is running.

MASTER\_KEY\
Default: “secretkey”\
Description: The admin master key for accessing the API. Change this in any production installation.

MQ\_USERNAME\
Default: “”\
Description: The username to set for MQ access

MQ\_PASSWORD\
Default: “”\
Description: The password to set for MQ access

INSTALL\_TYPE\
Default: ce\
Description: The installation type to run on the server. “ce” will run community edition. “pro” will run professional edition if you have an on-prem tenant.

LICENSE\_KEY\
Default: “”\
Description: The license key from your on-prem tenant needed to validate your professional installation

NETMAKER\_TENANT\_ID\
Default: “”\
Description: The ID of your on-prem tenant used to validate your professional installation.

SERVER\_IMAGE\_TAG\
Default:\
Description: The tag used for the server docker image. You can set it to “latest” to get the most up to date version. To stay on a certain version set the tag to the version you would like. ex: v0.24.2. if using a pro image, add “-ee” after the version. ex: v0.24.2-ee.

UI\_IMAGE\_TAG\
Default: “”\
Description: The tag used for the netmaker ui docker image. You can set it to “latest” to get the most up to date version. To stay on a certain version set the tag to the version you would like. ex: v0.24.2.

METRICS\_EXPORTER\
Default: off\
Description: This is a pro feature that exports metrics to the netmaker server.

PROMETHEUS\
Default: off\
Description: This is a pro feature. Prometheus is an open-source systems monitoring and alerting toolkit originally built at SoundCloud. It is used in our metrics collection.

DNS\_MODE\
Default: on\
Description: Enables DNS Mode, meaning all nodes will set hosts file for private dns settings.

NETCLIENT\_AUTO\_UPDATE\
Default: enabled\
Description: Enable/Disable auto update of netclient.

API\_PORT\
Default: 8081\
Description: The HTTP API port for Netmaker. Used for API calls / communication from front end. If changed, need to change port of BACKEND\_URL for netmaker-ui.

EXPORTER\_API\_PORT\
Default: 8085\
Description: The API port to set for the metrics exporter.

CORS\_ALLOWED\_ORIGIN\
Default: “\*”\
Description: The “allowed origin” for API requests. Change to restrict where API requests can come from with comma-separated URLs. ex: [https://dashboard.netmaker.domain1.com,https://dashboard.netmaker.domain2.com](https://dashboard.netmaker.domain1.com,https//dashboard.netmaker.domain2.com)

DISPLAY\_KEYS\
Default: on\
Description: Show keys permanently in UI (until deleted) as opposed to 1-time display.

DATABASE\
Default: sqlite\
Description: Database to use - sqlite, postgres, or rqlite

SERVER\_BROKER\_ENDPOINT\
Default: ws\://mq:1883\
Description: The address of the mq server. If running from docker compose it will be “mq”. Otherwise, need to input address. If using “host networking”, it will find and detect the IP of the mq container. For EMQX websockets use SERVER\_BROKER\_ENDPOINT=ws\://mq:8083/mqtt

VERBOSITY\
Default: 1\
Description: Logging verbosity level - 1, 2, 3, or 4

REST\_BACKEND\
Default: on\
Description: Enables the REST backend (API running on API\_PORT at SERVER\_HTTP\_HOST).

DISABLE\_REMOTE\_IP\_CHECK\
Default: off\
Description: If turned “on”, Server will not set Host based on remote IP check. This is already overridden if SERVER\_HOST is set.

TELEMETRY\
Default: on\
Description: Whether or not to send telemetry data to help improve Netmaker. Switch to “off” to opt out of sending telemetry.

ALLOWED\_EMAIL\_DOMAINS\
Default: “\*”\
Description: only mentioned domains will be allowed to signup using oauth, by default all domains are allowed

AUTH\_PROVIDER\
Default: “”\
Description: You can use azure-ad, github, google, oidc

CLIENT\_ID\
Default: “”\
Description: The client id of your oauth provider.

CLIENT\_SECRET\
Default: “”\
Description: The client secret of your oauth provider.

FRONTEND\_URL\
Default: “”\
Description: <https://dashboard>.

AZURE\_TENANT\
Default: “”\
Description: only for azure, you may optionally specify the tenant for the OAuth

OIDC\_ISSUER\
Default: “”\
Description: <https://oidc.yourprovider.com/> - URL of oidc provider

JWT\_VALIDITY\_DURATION\
Default: 43200\
Description: Duration of JWT token validity in seconds

RAC\_AUTO\_DISABLE\
Default: false\
Description: Auto disable a user’s connected clients based on JWT token expiration

CACHING\_ENABLED\
Default: true\
Description: if turned on data will be cached on to improve performance significantly (IMPORTANT: If HA set to false )

ENDPOINT\_DETECTION\
Default: true\
Description: if turned on netclient checks if peers are reachable over private/LAN address, and choose that as peer endpoint

SMTP\_HOST\
Default: ""\
Description: The address of the host SMTP service

SMTP\_PORT\
Default: 587\
Description: The port of the SMTP service

EMAIL\_SENDER\_ADDR\
Default: ""\
Description: The email address to send from

EMAIL\_SENDER\_USER\
Default: “”\
Description: The sender’s SMTP user. If empty, EMAIL\_SENDER\_ADDR would be used

EMAIL\_SENDER\_PASSWORD\
Default: ""\
Description: The password for the email sender

Starting from version v0.90.0, the following parameters are now configured directly from the Netmaker Settings interface:

* Allowed Email Domains
* Dashboard JWT Validity Duration
* Client JWT Validity Duration
* Restrict Simultaneous Network Connections
* Managed DNS
* DNS Base Domain
* LAN Routing
* Netclient Auto Update
* STUN Servers
* Verbosity Level
* Telemetry
* Metrics Port
* Metrics Collection Interval
* Email Configuration Parameters

### Compose File - Annotated

All environment variables and options are enabled in this file. It is the equivalent to running the “full install” from the above section. However, all environment variables are included and are set to the default values provided by Netmaker (if the environment variable was left unset, it would not change the installation). Comments are added to each option to show how you might use it to modify your installation.

As of v0.18.0, netmaker now uses a stun server (Session Traversal Utilities for NAT). This provides a tool for communications protocols to detect and traverse NATs that are located in the path between two endpoints. By default, netmaker uses publicly available STUN servers. You are free to set up your own stun servers and use those to augment/replace the public STUN servers. Update the STUN\_LIST to list the STUN servers you wish to use. Two resources for installing your own STUN server are:

* <https://ourcodeworld.com/articles/read/1175/how-to-create-and-configure-your-own-stun-turn-server-with-coturn-in-ubuntu-18-04>
* <https://cloudkul.com/blog/how-to-install-turn-stun-server-on-aws-ubuntu-20-04/>

There are also some environment variables that have been changed, or removed. Your updated docker-compose and .env files should look like this.

```yaml
version: "3.4"

services:

  netmaker:
    container_name: netmaker
    image: gravitl/netmaker:$SERVER_IMAGE_TAG
    env_file: ./netmaker.env
    restart: always
    volumes:
      - dnsconfig:/root/config/dnsconfig
      - sqldata:/root/data
    environment:
      # config-dependant vars
      - STUN_LIST=stun1.netmaker.io:3478,stun2.netmaker.io:3478,stun1.l.google.com:19302,stun2.l.google.com:19302
      # The domain/host IP indicating the mq broker address
      - BROKER_ENDPOINT=wss://broker.${NM_DOMAIN}
      # The base domain of netmaker
      - SERVER_NAME=${NM_DOMAIN}
      - SERVER_API_CONN_STRING=api.${NM_DOMAIN}:443
      # Address of the CoreDNS server. Defaults to SERVER_HOST
      - COREDNS_ADDR=${SERVER_HOST}
      # Overrides SERVER_HOST if set. Useful for making HTTP available via different interfaces/networks.
      - SERVER_HTTP_HOST=api.${NM_DOMAIN}

  netmaker-ui:
    container_name: netmaker-ui
    image: gravitl/netmaker-ui:$UI_IMAGE_TAG
    env_file: ./netmaker.env
    environment:
      # config-dependant vars
      # URL where UI will send API requests. Change based on SERVER_HOST, SERVER_HTTP_HOST, and API_PORT
      BACKEND_URL: "https://api.${NM_DOMAIN}"
    depends_on:
      - netmaker
    links:
      - "netmaker:api"
    restart: always

  caddy:
    image: caddy:2.6.2
    container_name: caddy
    env_file: ./netmaker.env
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./certs:/root/certs
      - caddy_data:/data
      - caddy_conf:/config
    ports:
      - "80:80"
      - "443:443"

  coredns:
    container_name: coredns
    image: coredns/coredns
    command: -conf /root/dnsconfig/Corefile
    env_file: ./netmaker.env
    depends_on:
      - netmaker
    restart: always
    volumes:
      - dnsconfig:/root/dnsconfig
  mq:
    container_name: mq
    image: eclipse-mosquitto:2.0.15-openssl
    env_file: ./netmaker.env
    depends_on:
      - netmaker
    restart: unless-stopped
    command: [ "/mosquitto/config/wait.sh" ]
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
      - ./wait.sh:/mosquitto/config/wait.sh
      - mosquitto_logs:/mosquitto/log
      - mosquitto_data:/mosquitto/data

volumes:
  caddy_data: { } # runtime data for caddy
  caddy_conf: { } # configuration file for Caddy
  sqldata: { }
  dnsconfig: { } # storage for coredns
  mosquitto_logs: { } # storage for mqtt logs
  mosquitto_data: { } # storage for mqtt data
```

The corresponding example .env entries:

```
# Email used for SSL certificates
NM_EMAIL=

# The base domain of netmaker
NM_DOMAIN=

# Public IP of machine
SERVER_HOST=

# The admin master key for accessing the API. Change this in any production installation.
MASTER_KEY=

# The username to set for MQ access
MQ_USERNAME=

# The password to set for MQ access
MQ_PASSWORD=
INSTALL_TYPE=
NETMAKER_TENANT_ID=
LICENSE_KEY=
SERVER_IMAGE_TAG=
UI_IMAGE_TAG=
NETCLIENT_ENDPOINT_DETECTION="disabled"

# used for HA - identifies this server vs other servers
NODE_ID="netmaker-server-1"
METRICS_EXPORTER="off"
PROMETHEUS="off"

# Enables DNS Mode, meaning all nodes will set hosts file for private dns settings
DNS_MODE="on"

# Enable auto update of netclient ? ENUM:- enabled,disabled | default=enabled
NETCLIENT_AUTO_UPDATE="enabled"

# The HTTP API port for Netmaker. Used for API calls / communication from front end.
# If changed, need to change port of BACKEND_URL for netmaker-ui.
API_PORT="8081"
EXPORTER_API_PORT="8085"

# The "allowed origin" for API requests. Change to restrict where API requests can come from with comma-separated
# URLs. ex:- https://dashboard.netmaker.domain1.com,https://dashboard.netmaker.domain2.com
CORS_ALLOWED_ORIGIN="*"

# Show keys permanently in UI (until deleted) as opposed to 1-time display.
DISPLAY_KEYS="on"

# Database to use - sqlite, postgres, or rqlite
DATABASE="sqlite"

# The address of the mq server. If running from docker compose it will be "mq". Otherwise, need to input address.
# If using "host networking", it will find and detect the IP of the mq container.
SERVER_BROKER_ENDPOINT="ws://mq:1883" # For EMQX websockets use `SERVER_BROKER_ENDPOINT=ws://mq:8083/mqtt`

# The reachable port of STUN on the server
STUN_PORT="3478"

# Logging verbosity level - 1, 2, or 3
VERBOSITY="1"
DEBUG_MODE="off"

# Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST).
# Change to "off" to turn off.
REST_BACKEND="on"

# If turned "on", Server will not set Host based on remote IP check.
# This is already overridden if SERVER_HOST is set. Turned "off" by default.
DISABLE_REMOTE_IP_CHECK="off"

# Whether or not to send telemetry data to help improve Netmaker. Switch to "off" to opt out of sending telemetry.
TELEMETRY="on"
###

#
# OAuth section
#
###

# "<azure-ad|github|google|oidc>"
AUTH_PROVIDER=

# "<client id of your oauth provider>"
CLIENT_ID=

# "<client secret of your oauth provider>"
CLIENT_SECRET=

# "https://dashboard.<netmaker base domain>"
FRONTEND_URL=

# "<only for azure, you may optionally specify the tenant for the OAuth>"
AZURE_TENANT=

# https://oidc.yourprovider.com - URL of oidc provider
OIDC_ISSUER=

# config for sending emails

# mail server host
SMTP_HOST=smtp.gmail.com

# mail server port
SMTP_PORT=587

# sender email
EMAIL_SENDER_ADDR=

# sender smtp user, if unset sender email will be used
EMAIL_SENDER_USER=

# sender smtp password
EMAIL_SENDER_PASSWORD=
```

Caddyfile example:

```
{

    email YOUR_EMAIL
}

# Dashboard
https://dashboard.NETMAKER_BASE_DOMAIN {
    # Apply basic security headers
    header {
            # Enable cross origin access to *.NETMAKER_BASE_DOMAIN
            Access-Control-Allow-Origin *.NETMAKER_BASE_DOMAIN
            # Enable HTTP Strict Transport Security (HSTS)
            Strict-Transport-Security "max-age=31536000;"
            # Enable cross-site filter (XSS) and tell browser to block detected attacks
            X-XSS-Protection "1; mode=block"
            # Disallow the site to be rendered within a frame on a foreign domain (clickjacking protection)
            X-Frame-Options "SAMEORIGIN"
            # Prevent search engines from indexing
            X-Robots-Tag "none"
            # Remove the server name
            -Server
    }

    reverse_proxy http://netmaker-ui
}

# API
https://api.NETMAKER_BASE_DOMAIN {
        reverse_proxy http://netmaker:8081
}

# MQ
wss://broker.NETMAKER_BASE_DOMAIN {
        reverse_proxy ws://mq:8883
}
```

### Available docker-compose files

The default options for docker-compose can be found here: <https://github.com/gravitl/netmaker/tree/master/compose>

The following is a brief description of each:

* docker-compose.yml — This maintains the most recommended setup at the moment, using the caddy proxy. (<https://github.com/gravitl/netmaker/blob/master/compose/docker-compose.yml>)
* docker-compose.pro.yml — This is the compose file needed for Netmaker Professional. You will need a licence and tenant id from Netmaker’s licence dashboard. (<https://github.com/gravitl/netmaker/blob/master/compose/docker-compose.pro.yml>)

## Setting a Netmaker server up for emailing

Starting from version v0.90.0, the Email Configuration Parameters are now configured directly from the Settings interface.

Since v0.25.0, the Netmaker server can now send email notifications to users, when relevant actions are effected on the server (e.g., inviting a user to join the server).

To enable emailing, the server administrator must correctly provide the below environment variables (in the netmaker.env file), and restart the server if needed:

* SMTP\_HOST
* SMTP\_PORT
* EMAIL\_SENDER\_ADDR
* EMAIL\_SENDER\_USER
* EMAIL\_SENDER\_PASSWORD

Refer to the Variable Description section above for more information on what values to assign.

## EMQX

Netmaker offers an EMQX option as a broker for your server. The main configuration changes between mosquitto and EMQX occur in the docker-compose.yml, netmaker.env and the Caddyfile.

You can find the EMQX docker-compose file in the netmaker repo: <https://github.com/gravitl/netmaker/blob/master/compose/docker-compose-emqx.yml>

You should not need to make any changes to the docker-compose-emqx.yml file. Just download this file using the command provided below in the same directory as your netmaker.env file — it will grab information from netmaker.env:

```
wget https://raw.githubusercontent.com/gravitl/netmaker/master/compose/docker-compose-emqx.yml
```

In your Caddyfile, change the mq block to:

```
# MQ
wss://broker.{$NM_DOMAIN} {
    reverse_proxy ws://mq:8083
}
```

Update netmaker.env:

Replace:

```
SERVER_BROKER_ENDPOINT="ws://mq:1883"
```

with:

```
SERVER_BROKER_ENDPOINT=ws://mq:8083/mqtt
```

In your docker-compose.yml, update BROKER\_ENDPOINT and add broker type entries:

```
- BROKER_ENDPOINT=wss://broker.${NM_DOMAIN}/mqtt
- BROKER_TYPE=emqx
- EMQX_REST_ENDPOINT=http://mq:18083
```

If using a professional server, update netmaker-exporter in docker-compose.override.yml:

```
netmaker-exporter:
    container_name: netmaker-exporter
    image: gravitl/netmaker-exporter:latest
    restart: always
    depends_on:
        - netmaker
    environment:
        SERVER_BROKER_ENDPOINT: "ws://mq:8083/mqtt"
        BROKER_ENDPOINT: "wss://broker.nm.${NM_DOMAIN}/mqtt"
        PROMETHEUS_HOST: "https://prometheus.${NM_DOMAIN}"
```

Bring up the services:

```sh
docker-compose down && docker-compose up -d && docker-compose -f docker-compose-emqx.yml up -d
```

Your `docker logs mq` should show listeners similar to:

```
Listener ssl:default on 0.0.0.0:8883 started.
Listener tcp:default on 0.0.0.0:1883 started.
Listener ws:default on 0.0.0.0:8083 started.
Listener wss:default on 0.0.0.0:8084 started.
Listener http:dashboard on :18083 started.
EMQX 5.0.9 is running now!
```

You can view your EMQX dashboard at `http://<serverip>:18083/`. Sign-in credentials are the EMQX\_DASHBOARD\_\_DEFAULT\_USERNAME and EMQX\_DASHBOARD\_\_DEFAULT\_PASSWORD located in your netmaker.env file.

## Nginx Reverse Proxy Setup with HTTPS

The Swag Proxy (<https://github.com/linuxserver/docker-swag>) makes it easy to generate a valid SSL certificate for the config below. Here is the documentation: <https://docs.linuxserver.io/general/swag>

An example config for Netmaker as a subdomain (adapted from swag):

./netmaker.subdomain.conf:

```
server {
    # Redirect HTTP to HTTPS.
    listen 80;
    server_name *.netmaker.example.org; # Please change to your domain
    return 301 https://$host$request_uri;
    }

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name dashboard.netmaker.example.org; # Please change to your domain
    include /config/nginx/ssl.conf;
    location / {
        proxy_pass http://<NETMAKER_IP>:8082;
        }
    }

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name api.netmaker.example.org; # Please change to your domain
    include /config/nginx/ssl.conf;

    location / {
        proxy_pass http://<NETMAKER_IP>:8081;
        proxy_set_header            Host api.netmaker.example.org; # Please change to your domain
        proxy_pass_request_headers  on;
        }
    }
```

## Nginx Proxy Manager Setup

To use Netmaker with Nginx Proxy Manager, add three proxy hosts, one for each subdomain used by Netmaker. Each subdomain should have SSL enabled and be configured as follows:

api.netmaker.example.com:

* Forward Hostname/IP: netmaker
* Forward Port: 8081

dashboard.netmaker.example.com:

* Forward Hostname/IP: netmaker-ui
* Forward Port: 80

grpc.netmaker.example.com:

* Forward Hostname/IP: netmaker
* Forward Port: 50051
* Custom Locations:
  * Add location /
  * Forward Hostname/IP: netmaker
  * Forward Port: 50051
  * Custom config: grpc\_pass netmaker:50051;

A cleaned-up config generated by Nginx Proxy Manager (does not include SSL configuration):

```
# dashboard.netmaker.example.com
server {
  set $forward_scheme http;
  set $server         "netmaker-ui";
  set $port           80;
  listen 80;
  listen [::]:80;
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name dashboard.netmaker.example.com;
  location / {
    include conf.d/include/proxy.conf;
    # proxy_pass       $forward_scheme://$server:$port$request_uri;
  }
}

# api.netmaker.example.com
server {
  set $forward_scheme http;
  set $server         "netmaker";
  set $port           8081;
  listen 80;
  listen [::]:80;
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name api.netmaker.example.com;
  location / {
    include conf.d/include/proxy.conf;
    # proxy_pass       $forward_scheme://$server:$port$request_uri;
  }
}

# grpc.netmaker.example.com
server {
  set $forward_scheme http;
  set $server         "netmaker";
  set $port           50051;
  listen 80;
  listen [::]:80;
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name grpc.netmaker.example.com;
  location / {
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Scheme $scheme;
    proxy_set_header X-Forwarded-Proto  $scheme;
    proxy_set_header X-Forwarded-For    $remote_addr;
    proxy_set_header X-Real-IP          $remote_addr;
    proxy_pass       http://netmaker:50051;
    grpc_pass netmaker:50051;
  }
}
```

## Security Settings

It can be useful to secure your web dashboard behind a firewall while keeping the API available for nodes. Below are examples for Caddy and Traefik reverse proxies.

### For Caddy

In your /root/Caddyfile, in the Dashboard section where `reverse_proxy http://netmaker-ui` appears, add above it:

```
@blocked not remote_ip <ip1> <ip2> <ip3>
respond @blocked "Nope" 403
```

Replace the placeholders with your whitelist IP ranges.

### For Traefik

1. In the labels section, add:

```
traefik.http.middlewares.nmui-security-1.ipwhitelist.sourcerange=YOUR_IP_CIDR
```

2. Update the router middlewares line from:

```
traefik.http.routers.netmaker-ui.middlewares=nmui-security@docker
```

to:

```
traefik.http.routers.netmaker-ui.middlewares=nmui-security-1@docker,nmui-security@docker
```

Replace YOUR\_IP\_CIDR with the whitelist IP range (can be multiple ranges).

After changes are made for your reverse proxy, run:

```sh
docker-compose down && docker-compose up -d
```

This keeps your dashboard secure while keeping the API available without changing netmaker-ui ports.

## Setup Netmaker on an IPv6-only Machine

This is not a guide on adding an overlay network (with IPv6) in Netmaker; see the setup page for that. This guide covers getting Netmaker to run on an IPv6-only machine.

### About the install script nm-quick.sh

At the time of writing, the install script nm-quick.sh only supports IPv4. For installation, IPv4 needs to be enabled temporarily.

### Add AAAA record for domain name resolution

Netmaker client communicates with the Netmaker server by domain name. Add an AAAA record to resolve the domain name to the server's IPv6 address.

### Enable IPv6 support for Docker

{% stepper %}
{% step %}

1. Add/Edit the Docker daemon config at /etc/docker/daemon.json:

```json
{
  "experimental": true,
  "ip6tables": true
}
```

{% endstep %}

{% step %}
2\. Restart the Docker daemon:

```sh
sudo systemctl restart docker
```

{% endstep %}

{% step %}
3\. Create a new IPv6 Docker network, for example:

```sh
docker network create --ipv6 --subnet 2001:0DB8::/112 ip6net
```

Here “ip6net” is the network name and “2001:0DB8::/112” is the network range.
{% endstep %}
{% endstepper %}

### Enable IPv6 support for Netmaker

{% stepper %}
{% step %}

1. Edit your docker-compose.yml and add the external network declaration at the bottom:

```
networks:
  ip6net:
    external: true
```

{% endstep %}

{% step %}
2\. In docker-compose.yml, add the networks field for every service that should attach to the IPv6 network:

```
networks:
  - ip6net
```

{% endstep %}

{% step %}
3\. Restart Netmaker:

```sh
docker-compose down
docker-compose up -d
```

{% endstep %}
{% endstepper %}


# Adding a Pro License to your Server

Learn how to set up Netmaker Professional and take advantage of advanced business-focused features not included in the Community Edition. Check out our [pricing page](https://www.netmaker.io/pricing) for a full comparison and pricing details.

#### Unlock advanced business capabilities with Netmaker Professional, which builds on the Community Edition with additional features and functionality. Key differences are outlined below.

## Key Differences

The **Community Edition (CE)** offers a solid, open-source foundation for VPN deployments under the Apache 2.0 license, with no usage limits. It includes features like an integrated private DNS server, network relays, full-tunnel internet gateways, egress to external networks, basic access controls, basic user management, and MFA. It's self-hosted and well-suited for developers and teams looking for flexibility and control in their setup.

The **Professional Edition** extends these capabilities with features designed for teams and enterprises. It includes advanced user management with role-based access, advanced access controls with both device and user policies, SSO login (Google, GitHub, Microsoft, and custom OIDC), dedicated traffic relays, zero-touch NAT traversal, network metrics and analytics exportable to Prometheus and Grafana, and the Desktop & Mobile App for remote access. Higher tiers further add audit logging, HA traffic routing, posture checks, device approvals, SCIM-based IDP provisioning, just-in-time access, and more.

For a detailed overview of features across the Pro and Community Editions, check it out here

**Pro-Specific Functionalities**

**User Management**

* In the Community Edition (CE), only basic user management is available.
* The Professional Edition unlocks advanced user management, enabling role-based access, user groups and roles, and more granular control — ideal for managing teams and remote access gateways.
* Higher Pro tiers additionally support SCIM-based provisioning for automated user and group sync from identity providers like Okta, Google Workspace, and Microsoft Entra ID.

**Remote Access Clients**

* Seamless remote connectivity via the Netmaker Desktop App and Mobile App.
* Enables secure access to your network from any laptop or mobile device — perfect for remote work scenarios.

**Dedicated Traffic Relays**

* Automatically relays traffic for machines in hard-to-reach locations, improving overall network health and enabling more flexible network designs.

**Enhanced Access Control Lists (ACLs)**

* Allows you to define detailed communication rules using both device and user policies.
* Combine with user-level permissions to enhance network security and segmentation.

**Network Metrics**

* Collects key performance data such as latency, throughput, and connection status.
* Viewable directly in the Netmaker UI and exportable to Grafana via Prometheus for custom dashboards.

**SSO / OAuth Integration**

* Supports SSO login via Google, GitHub, Microsoft, and custom OIDC providers.
* Allows users to authenticate using their existing organizational credentials for seamless and secure access.

**Audit Logs**

* Tracks user activity and system events across key components.
* Essential for security monitoring, compliance audits, and issue resolution.

**High Availability (HA) Traffic Routing**

* Ensures resilient, uninterrupted traffic routing across your network infrastructure.

**Posture Checks & Device Approvals**

* Enforce security posture requirements before granting device access, and require approval for new devices joining the network.

**SCIM & IDP Provisioning**

* Automates user and group lifecycle management through SCIM integration with Entra ID, Google Workspace, and Okta.
* Available in the Enterprise tier.

## Obtain License

{% stepper %}
{% step %}

### Sign up

Go to <https://account.netmaker.io/signup> and enter your email address and set a password. You also have the option to continue using your Google, GitHub, or Microsoft account.

We recommend taking advantage of the 7-day free trial. For business emails, no credit card is required: <https://account.netmaker.io/signup#business>
{% endstep %}

{% step %}

### Verify your email

After signing up you will receive a verification link sent to your email address. Open your inbox and click on **Verify My Email** to complete the process.
{% endstep %}

{% step %}

### Tenant creation (on-premise setups)

After verification, you will be redirected to the deployment page. For on-premise setups, tenants are created only upon request. To request a tenant, please fill out the form at <https://www.netmaker.io/contact>

Once your tenant has been created, click **Manage Tenant**, then click **Manage** to view its details.
{% endstep %}
{% endstepper %}

## Set Up Your Netmaker Pro Server

Initially, you will need the License Key and Tenant ID, which can be found under the Settings tab.

Once you have your license key and tenant ID, you can get the nm-quick installer and run it:

{% code title="Install Netmaker Pro (interactive installer)" %}

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh -p
```

{% endcode %}

Follow the prompts for a pro edition server and provide the License Key and Tenant ID when prompted.

## Upgrade from Community Edition to Pro

You can upgrade from an existing community server to a pro server using the same script, or upgrade manually.

{% stepper %}
{% step %}

### Automatic upgrade (recommended)

Fetch the latest installer and run it to upgrade:

{% code title="Automatic upgrade" %}

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh -u
```

{% endcode %}

Follow the prompts to set up a pro server. The script will make the necessary changes to your netmaker.env file and grab the pro docker-compose.override.yml file.
{% endstep %}

{% step %}

### Manual upgrade

1. On your netmaker server, add the following to your netmaker.env file:

{% code title="netmaker.env additions" %}

```
LICENSE_KEY=<license key>
NETMAKER_TENANT_ID=<tenant id>
```

{% endcode %}

2. Change `SERVER_IMAGE_TAG` in netmaker.env to `<version>-ee`, for example:

```
SERVER_IMAGE_TAG=v0.25.0-ee
```

3. Change the `INSTALL_TYPE` from `ce` to `pro`.
4. Download the docker-compose pro override file:

{% code title="Fetch docker-compose.pro.yml" %}

```bash
wget -O /root/docker-compose.override.yml https://raw.githubusercontent.com/gravitl/netmaker/master/compose/docker-compose.pro.yml
```

{% endcode %}

No changes need to be made to that file; it uses the configs listed in your netmaker.env file.

5. Restart Netmaker services:

{% code title="Restart Netmaker" %}

```bash
docker compose down && docker compose pull && docker compose up -d
```

{% endcode %}

When you browse to your self-hosted Netmaker via dashboard.\<YOUR\_BASE\_DOMAIN>, you should see the professional UI and a new Dashboard.
{% endstep %}
{% endstepper %}

## (Optional) Setup your server for Prometheus and Grafana

If you would like to use Netmaker’s custom Prometheus exporter and Grafana dashboard, your docker-compose.override.yml file will already include those sections.

In netmaker.env, enable the following:

{% code title="Enable metrics in netmaker.env" %}

```
METRICS_EXPORTER=on
PROMETHEUS=on
```

{% endcode %}

This will enable the metrics exporter and Prometheus integration for use with Grafana dashboards.


# HA installation on Kubernetes

## Highly Available Installation (Kubernetes)

Netmaker comes with a Helm chart to deploy with High Availability on Kubernetes:

```plaintext
helm repo add netmaker https://gravitl.github.io/netmaker-helm/
helm repo update
```

### Requirements

To run HA Netmaker on Kubernetes, your cluster must have the following:

* RWO and RWX Storage Classes
* An Ingress Controller and valid TLS certificates

This chart can currently generate ingress for:

* Nginx Ingress + LetsEncrypt/Cert-Manager

To generate automatically, make sure one of the two is configured for your cluster.

* Ability to set up ingress route for Secure Web Sockets

Nginx Ingress supports Secure Web Sockets (WSS) by default. If you are not using Nginx Ingress, you must route external traffic from broker.domain to the MQTT service, and provide valid TLS certificates.

One option is to set up a Load Balancer which routes broker.domain:443 to the MQTT service on port 8883.

We do not provide guidance beyond this, and recommend using an Ingress Controller that supports websockets.

Furthermore, the chart will by default install and use a postgresql cluster as its datastore:

| Repository                           | Name          | Version |
| ------------------------------------ | ------------- | ------- |
| <https://charts.bitnami.com/bitnami> | postgresql-ha | 7.11.0  |

### Example Installations

{% stepper %}
{% step %}

### Annotated install command

```plaintext
helm install netmaker/netmaker --generate-name \ # generate a random id for the deploy
--set baseDomain=nm.example.com \ # the base wildcard domain to use for the netmaker api/dashboard/mq ingress
--set server.replicas=3 \ # number of server replicas to deploy (3 by default)
--set ingress.enabled=true \ # deploy ingress automatically (requires nginx and cert-manager + letsencrypt)
--set ingress.kubernetes.io/ingress.class=nginx \ # ingress class to use
--set ingress.cert-manager.io/cluster-issuer=letsencrypt-prod \ # LetsEncrypt certificate issuer to use
--set postgresql-ha.postgresql.replicaCount=2 \ # number of DB replicas to deploy (default 2)
```

{% endstep %}

{% step %}

### Install with two server replicas, CoreDNS, and ingress

CoreDNS will be reachable at 10.245.75.75 and will use NFS to share a volume with Netmaker (to configure DNS entries).

```plaintext
helm install netmaker/netmaker --generate-name --set baseDomain=nm.example.com \
--set replicas=2 --set ingress.enabled=true --set dns.enabled=true \
--set dns.clusterIP=10.245.75.75 --set dns.RWX.storageClassName=nfs \
--set ingress.className=nginx
```

{% endstep %}

{% step %}

### Install with three server replicas (default), no CoreDNS, and Traefik ingress

There will be one UI replica and one DB instance. Traefik will look for a ClusterIssuer named “le-prod-2”.

```plaintext
helm3 install netmaker/netmaker --generate-name \
--set baseDomain=netmaker.example.com --set postgresql-ha.postgresql.replicaCount=1 \
--set ui.replicas=1 --set ingress.enabled=true \
--set ingress.tls.issuerName=le-prod-2 --set ingress.className=traefik
```

{% endstep %}
{% endstepper %}

### Recommended Settings

Ingress must be configured on your cluster, with a cluster issuer for TLS certificates. DNS will be disabled by default unless explicitly enabled.

Below are considerations for Ingress, Kernel WireGuard, and DNS.

### MQ

The MQ Broker is deployed either with Ingress (Nginx) preconfigured, or without. If you are using an ingress controller other than Nginx, Netmaker’s MQTT will not be complete. broker.domain must reach the MQTT service at port 8883 over WSS (Secure Web Sockets).

### Ingress

To run HA Netmaker, you must have ingress installed and enabled on your cluster with valid TLS certificates (not self-signed).

If you are running Nginx as your Ingress Controller and LetsEncrypt for TLS certificate management, you can run the helm install with the following settings:

* \--set ingress.enabled=true
* \--set ingress.annotations.cert-manager.io/cluster-issuer=

If you are not using Nginx and LetsEncrypt, we recommend leaving ingress.enabled=false (default), and then manually creating the ingress objects post-install. You will need three ingress objects with TLS:

* dashboard.
* api.
* broker.

There are some example ingress objects in the kube/example folder.

### DNS

By default, the helm chart will deploy without DNS enabled. To enable DNS, specify:

* \--set dns.enabled=true

This will require specifying a RWX storage class, e.g.:

* \--set dns.RWX.storageClassName=nfs

This will also require specifying a service address for DNS. Choose a valid IPv4 address from the service IP CIDR for your cluster, e.g.:

* \--set dns.clusterIP=10.245.69.69

This address will only be reachable from hosts that have access to the cluster service CIDR. It is only designed for use cases related to k8s. If you want a more general-use Netmaker server on Kubernetes for use cases outside of k8s, you will need to do one of the following:

* Bind the CoreDNS service to port 53 on one of your worker nodes and set the COREDNS\_ADDRESS equal to the public IP of the worker node.
* Create a private Network with Netmaker and set the COREDNS\_ADDRESS equal to the private address of the host running CoreDNS. For this, CoreDNS will need a node selector and will ideally run on the same host as one of the Netmaker server instances.

{% hint style="warning" %}
Ingress must be configured with valid TLS certificates (not self-signed) for HA Netmaker to function correctly.
{% endhint %}

### Values

To view all options for the chart, please visit the README in the netmaker-helm chart repo here: <https://github.com/gravitl/netmaker-helm?tab=readme-ov-file#values>


# UI Branding

## Modifying the UI with whitelabeling

Netmaker UI allows resellers to whitelabel and customize branding by building a custom docker image with the environment variables below set.

Recommended: use logos with an aspect ratio of 4:3.

{% stepper %}
{% step %}

### VITE\_PRODUCT\_NAME

The name of the product. This is the name that will appear in the UI.
{% endstep %}

{% step %}

### VITE\_TENANT\_LOGO\_DARK\_URL

Logo to be used in dark mode.
{% endstep %}

{% step %}

### VITE\_TENANT\_LOGO\_LIGHT\_URL

Logo to be used in light mode.
{% endstep %}

{% step %}

### VITE\_TENANT\_LOGO\_DARK\_SMALL\_URL

Small variant of the logo to be used in dark mode (e.g., when the sidenav is collapsed). Optional.
{% endstep %}

{% step %}

### VITE\_TENANT\_LOGO\_LIGHT\_SMALL\_URL

Small variant of the logo to be used in light mode (e.g., when the sidenav is collapsed). Optional.
{% endstep %}

{% step %}

### VITE\_TENANT\_LOGO\_ALT\_TEXT

Alternative text for the logo.
{% endstep %}

{% step %}

### VITE\_TENANT\_FAVICON\_LOGO

Favicon to use in the web browser’s tab. Defaults to the light logo if not specified. Recommended to use a 32x32px .ico image.
{% endstep %}

{% step %}

### VITE\_TENANT\_PRIMARY\_COLOR

UI primary color. Replace this with your brand color (examples: red, green, "#F00", "#00FF00"). Note: hex values need quoting.
{% endstep %}
{% endstepper %}

You can use URLs to host the logos, or place the logos in the /public directory before building the docker image.

Reference: <https://github.com/gravitl/netmaker-ui-2/blob/master/Dockerfile.standalone>

For more information on how to go about whitelabelling, reach out to us at <https://www.netmaker.io/contact>


# Client Installation

When deploying Netmaker to your devices, you will need a client-side application, of which we have various options. In general, this is what we recommend:

* Use the Netclient for endpoints and routing points in your network (e.g. a server)
* Use the Mobile and Desktop apps for end users (e.g. phones and laptops)
* Use Native WireGuard wherever the other clients are not supported (e.g. routers, IoT)

<table><thead><tr><th width="105.2890625">Client Type</th><th width="129.8515625">Agent Type</th><th width="83.34375">Auth</th><th width="137.75390625">Connectivity</th><th width="128">OS</th><th width="124.609375">Guide</th></tr></thead><tbody><tr><td>Netclient</td><td>Headless</td><td>Key</td><td>Always-On</td><td>Mac, Windows, Linux</td><td><a href="/pages/2c8ef69b3dc32bece37fb8491e9703f65d245c8e" class="button primary">Docs</a></td></tr><tr><td>Netmaker Desktop</td><td>GUI</td><td>Identity</td><td>On-Demand  / Always On</td><td>Mac, Windows, Linux</td><td><a href="/pages/f169a78f6e8f463983b91bf57a45815be35842fa" class="button primary">Docs</a></td></tr><tr><td>Mobile App</td><td>GUI</td><td>Identity</td><td>On-Demand /  Always On</td><td>iOS, Android</td><td><a href="/pages/0de8ca18aa5c43023b5916ec5e468a3228979758" class="button primary">Docs</a></td></tr><tr><td>Native WireGuard</td><td>Headless / GUI</td><td>Key</td><td>Always On</td><td>Most Operating Systems</td><td><a href="/pages/563fa1de3db877586e1d5a7b407d0110e660581b" class="button primary">Docs</a></td></tr></tbody></table>


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

![](/files/TDCaVj39xSpYO2dwgfgc)

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


# 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 <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 (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: <https://github.com/gravitl/netclient/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: <https://docs.netmaker.io/docs/server-installation/quick-install#prerequisites\\_\\_netmaker-firewall-rules>

## 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 <token> // join using token
server: netclient join -s <server> // join a specific server via SSO if Oauth configured
net: netclient join -s <server> -n <net> // attempt to join specified network via auth
all-networks: netclient join -s <server> -A // attempt to register to all allowed networks on given server via auth
user: netclient join -s <server> -u <user_name> // 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 <enrollment key>
```

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 <network>
```

* To connect with a network previously disconnected:

```
netclient connect <network>
```

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 <enrollment key>
```

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: <https://github.com/gravitl/netclient/releases>
* Firewall rules for machines running netclient: <https://docs.netmaker.io/docs/server-installation/quick-install#prerequisites\\_\\_netmaker-firewall-rules>


# Stabilize Netclient Connections Behind NAT

For sites behind NAT routers, you can stabilize the connection to the netclient by setting up port forwarding, and setting a static port for the Netclient.

## Port Forwarding

Set up port forwarding rules to forward traffic from the WAN to the machine with Netclient installed. Use custom ports such as 55555.

Here is an example of setting up port forwarding to a generic Linux machine that uses an iptables firewall.

{% stepper %}
{% step %}

### Enable IP forwarding at the kernel level

By default, most systems have forwarding turned off. To turn port forwarding on permanently, edit the /etc/sysctl.conf file with sudo privileges:

{% code title="/etc/sysctl.conf" %}

```
```

{% endcode %}

```
sudo nano /etc/sysctl.conf
```

Inside the file, add this line at the bottom:

```
```

```
net.ipv4.ip_forward=1
```

Save and close the file.
{% endstep %}

{% step %}

### Apply sysctl settings

Apply the settings you added:

```
```

```bash
sudo sysctl -p
```

Then load the system-wide settings:

```
```

```bash
sudo sysctl --system
```

{% endstep %}

{% step %}

### Identify WAN and LAN interfaces

Find the WAN and LAN interfaces on the machine using:

```
```

```bash
ip a
```

&#x20;<img src="/files/9e1d9ba672c17df47d00e8df85f896a532c9536a" alt="" data-size="original">
{% endstep %}

{% step %}

### Add DNAT rule to forward incoming traffic

Use the -j DNAT target of the PREROUTING chain in the nat table to forward incoming packets to the internal IP and port. Replace {PUBLIC\_IP} and {INTERNAL\_IP} with your values:

```
```

```bash
iptables -t nat -A PREROUTING -i eth0 -p udp -d {PUBLIC_IP} --dport 55555 -j DNAT --to {INTERNAL_IP}:55555
```

{% endstep %}

{% step %}

### Configure IP masquerading (SNAT)

Allow LAN nodes with private IP addresses to communicate with external public networks by masquerading outbound traffic on the external interface (e.g., eth0):

```
```

```bash
iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
```

{% endstep %}

{% step %}

### Result

Now the port forwarding rule for UDP port 55555 is set on the Linux machine and can be used for WireGuard/Netclient connections.
{% endstep %}
{% endstepper %}

## Assign Static Port

To stabilize connections for sites behind NAT routers, set each Netclient host port to "static" and specify the custom port from above (for example, 55555). You can configure this in the Netmaker web UI by going to "Hosts" and then "Edit Host" on the specific netclient hosts.

![](/files/XoO1eTnPtVCSaR1zr935)


# Native WireGuard Installation

## Overview

Your network is now configured with Hosts, acting as Endpoints, Relays, Egress, and Remote Access Gateways. Before we move on to adding Users to your network, let’s take care of any of the devices which are not user-managed, and do not support the Netclient, using Client (WireGuard) Configuration Files.

These static WireGuard configuration files will allow you to add devices to your network such as Routers and other non-standard devices. They can also be used to run a privileged, always-on VPN on user devices, which is managed by administrators.

There are three primary reasons you may want to use Static Clients with your network:

### Admin-Managed, Always On VPN for User Devices

The Remote Access Client is typically used to give users access to the VPN. However, this client is “on-demand” and requires user authentication to run. You may find yourself in a situation where you want the VPN to run every time the device is booted. Perhaps you are configuring fresh user workstations with VPN access which should be “always-on.” This is a good use case for Static Clients.

### Site-to-Site Connectivity via Routers

There are other ways to configure site-to-site connectivity with Netmaker, but one easy way is to utilize the WireGuard plugins which are supported on a large number of Routers today. You can generate a Static Client, configure them with additional routes (for the local network behind the router), and apply the configuration to routers via the supported plugin, to give full access between the site and the VPN.

### Integrate Non-Native Devices

The Netclient runs on Windows, Linux, and Mac. The Remote Access Client runs on all of these plus Android and iOS. For everything else, there’s the static WireGuard config, which can be run on anything that supports WireGuard.

## Limitations of Static WireGuard Files

The Netclient dynamically updates and receives information about peers in the network. When using a static configuration file, it cannot receive any updates, and thus has some limitations.

### Static Configuration

The primary limitation of the static config file is that it is static. It will have routes for everything that exists at the time it is generated, including the whole VPN network range. So new VPN endpoints will be accessible. However, if you generate an Egress or Internet gateway, config files will need to be re-generated. Also, if your Remote Access Gateway changes its public key or endpoint. Using the API and some automation tools will help alleviate this problem in some scenarios, which we will discuss later on.

This is alleviated by the Hub-And-Spoke pattern used with the config files. Because they gain access to the VPN using the hub, as long as the hub’s information remains the same, these configs will continue to work. However, this introduces another limitation.

### Hub-And-Spoke Architecture

An additional limitation is that access to and from the network from these static endpoints go through a gateway. There will always be an extra hop for connections, which can reduce the network speed and produce a bottleneck for traffic. However, this comes at the advantage of higher connectivity and consistency.

## Deploying Static Clients

Before we can create static clients, we need a Remote Access Gateway, which acts as the “Hub” for these connections. This gateway forwards traffic to and from the clients, acting as a middle point for connections. This should have been deployed in the previous section. If you need a refresher, go back and look. But you simply need to set a Host in a public environment as the gateway.

## Configuring the Remote Access Gateway

Before creating your clients, there are some global settings you can put on your gateway which will be applied to all generated clients by default. To access these settings, click on the dropdown on the gateway on the left side of the Remote Access tab.

![](/files/2449597836bb3d6dfaf38e890e5ba78c34951813)

### DNS

The “Remote Access Gateway” DNS configuration sets a DNS server for all the static clients generated under this specific gateway. However, this setting can be overridden while generating individual clients using the advanced configuration settings.

This should be used for either:

* Providing a public DNS server which is accessed while using features like the Internet Gateway, to avoid DNS leaks. If using an Internet Gateway, DNS traffic will route to the gateway first, and then to the public DNS server.
* Providing a private DNS server which gives the clients information about local sites (for instance [myapp.company](http://myapp.company/).local). The DNS server must be accessible, either directly over the VPN or via Egress Gateway. For instance, if you have a DNS server at 192.168.1.52, have an egress gateway with a route to this IP, and your clients will now be able to use the local DNS.

### Additional Endpoints

This is an advanced feature for users who have placed their Remote Access Gateway in a location, and want it to be accessible over a different IP address.

This is used in tandem with the Remote Access Client, which allows users to specify the connection endpoint. The typical use case is having a RAG deployed in an office network, and adding the local IP as an endpoint for the gateway. This allows users to connect over the local IP when they are in the office, which will increase the speed of connections.

### Network Info

When users use the Remote Access Client, they will see this information. Typically, it’s a description of what the users will be able to access over the VPN, since they will see it in the information in their local client before connecting.

## Generating Clients

Static clients can be generated through the Netmaker UI, or **over API (see How to Guide)**. After generating these client configurations, they can be imported and used on any operating system that supports WireGuard, including Windows, MacOS, Linux, Android, BSD, iOS and many router operating systems.

{% stepper %}
{% step %}

### Add a new node

![](/files/7gztQwQnMcZwlOtfuGGz)
{% endstep %}

{% step %}

### Choose the config files option, specify the node name, and select your gateway

![](/files/AVxPyYQ5U78A42jgMox9)

Even if your node is not configured as a remote access gateway in the gateway list, it will be automatically created during this process.
{% endstep %}

{% step %}

### Select Config files filter and download the WireGuard config file

Click on your WG config file to download the WG configuration you created for the target device.

![](/files/P38BpnoGtg06rzeryyzJ)
{% endstep %}

{% step %}

### Run the WireGuard configuration on the target device

Follow platform-specific instructions below to apply the configuration.
{% endstep %}
{% endstepper %}

Another option is to create the WG config client through the Remote Access interface by following these steps:

{% stepper %}
{% step %}

### Go to the Remote Access interface of your network

{% endstep %}

{% step %}

### Select a Remote Access Gateway

{% endstep %}

{% step %}

### Click “Create Config” above “VPN Config Files”

{% endstep %}

{% step %}

### (Optional) Configure as desired

{% endstep %}

{% step %}

### Click “Create Client”

{% endstep %}
{% endstepper %}

![](/files/IxJbO8nnCr862LePVcLh)

Static clients cannot be automatically updated after the configuration file has been deployed to your specific devices. Any changes to the static client configuration file have to be manually updated on their respective devices.

## Client Settings

When creating a client, the dialog box presents some optional fields you may wish to set:

![](/files/f494c4b491fda7413c17da77e492905b998b169a)

* Client ID — an identifier for the config.
* Public Key — You may generate a public/private keypair locally, and specify the public key here. This will allow you to keep the private key off the server, which will enhance security. However, you will need to store and paste in the private key into the configuration file after download.
* DNS — This overrides whatever is set as the default Gateway DNS server, and will be applied as the DNS settings for the VPN tunnel.
* Additional Addresses — This field can be used to create your own “egress gateway” from a static file. Other peers in the network will be told that this static client will route traffic for these addresses. In the above picture we have added two routes for “192.168.5.0/24” and “10.10.10.0.0/16.” This is advertised to all the peers in the network, and they will attempt to send traffic to these addresses via the static client.

  Note that you will have to manually configure the device to forward traffic. However, you can also set this in the PostUp and PostDown commands.
* Post Up and Post Down — The “Post Up” and “Post Down” fields are commands that get run locally by WireGuard when the interface is brought up (Post Up) and down (Post Down). This can be useful for setting routing or firewall rules on the device whenever the interface is created and destroyed. In our example, we have added an iptables firewall command to allow all ssh connections originating from the netmaker interface when the WireGuard tunnel is alive.

### Viewing and Downloading the Config File

After generation, the configuration file can be viewed or downloaded by clicking the client id in the UI and then the “View/Download config” button. This will show the client’s full WireGuard configuration and it will also provide a handy QR code to scan and import the configuration file on mobile devices.

![](/files/f32494272d302c8b4b7c60db0e36eb674611253e)

## Applying to Devices

The generated static client configuration files can be used in various different platforms and operating systems. These files can be applied to any device that supports WireGuard. However, depending on the system, you may not be able to import or run the file directly. Instead, you may need to set up a tunnel, using the settings presented in the config file.

The steps to apply WireGuard here are exactly the same as you would to set up any WireGuard tunnel. These config files are just valid WireGuard tunnel parameters, which will add it to the network. Below, we provide some generic instructions on how to do this, but again, searching for any instructions to set up WireGuard on your device will work. Just use the settings from the configuration file.

### Install WireGuard

First, WireGuard must be installed on the target platform.

To install WireGuard, follow the official WireGuard installation link, and find instructions for your target device: <https://www.wireguard.com/install>

### Apply Configuration via WireGuard GUI (Windows)

On Windows, you’ll get a GUI application to import WireGuard files.

![](/files/2b5cb3c0f7c3995e27e1a06d7ad91eca3a085aae)

Click the Import Tunnels button, and select the config file (If you have not done so already the config file must be downloaded or transferred to the target device).

![](/files/718b925fa55615219bf473494fda9680399c0ad5)

After importing the static client configuration file, click the Activate button to make the tunnel active.

![](/files/21acb90bd43cfe0f5dd9cde61212fa2165fcc62e)

If successful, it will show an “Active” status alongside some additional information such as the connection handshake status and total data transfer amount, which can help verify the connection is working.

![](/files/582ce4a9ac7ee31cdc925e20f8f79111e3f15599)

Now this static client can reach any other hosts in the network through the “Remote Access Gateway” host. So, basically it can reach and access network resources of the hosts which are available inside the netmaker network and reachable by the “Remote Access Gateway” host.

The windows terminal can be used to check all the WireGuard interfaces and tunnels and can also be used to configure custom interfaces. Open up Windows terminal app, then type wg and press enter to show all the WireGuard interfaces and peers configuration.

![](/files/bf31c29f13e6cda0aef67938494f737dc46c1118)

### Apply Configuration via wg-quick — Linux, macOS, and Others

wg-quick is the easiest tool to get a tunnel active on Linux and macOS (as well as some other operating systems), and is included in the wireguard-tools package.

{% stepper %}
{% step %}

### Place the config file on the device

Download, transfer, or copy/paste the config file to the device.
{% endstep %}

{% step %}

### Bring the tunnel up

Run:

{% code title="Bring up tunnel" %}

```bash
wg-quick up ./path/to/config.conf
```

{% endcode %}

This will configure and bring up the WireGuard interface. Use the wg command to verify the interface.
{% endstep %}
{% endstepper %}

It will show the handshake and other statistics of the WireGuard interface upon successful connection. Similarly you can bring down the connection with:

{% code title="Bring down tunnel" %}

```bash
wg-quick down ./wg.conf
```

{% endcode %}

![](/files/53708cee86671c3857bfa52f7bfb4c288948fa3f)

### Always On-VPN for Windows Devices

Using PowerShell, an always-on VPN tunnel can be created for user devices. Open Windows Terminal and run:

{% code title="Install tunnel service" %}

```powershell
wireguard.exe /installtunnelservice "C:\\Users\\%USERNAME%\\Downloads\\test\\SiteA.conf"
```

{% endcode %}

This creates a system service for handling the tunnel so the adapter survives reboots and automatically reconnects.

## Next Steps

We did not mention configuring Routers in this section, which we will cover in the next section, where we will walk through setting up site-to-site connectivity using Netmaker. There are two primary approaches to this, using static config files, or using the netclient.


# Netmaker Desktop Installation

## Netmaker Desktop

Netmaker Desktop is the revamped Remote Access Client, offering a simple GUI for connecting to a Netmaker network from an offsite device. Available on Windows, Mac, and Linux.

### Download / Installation

You can download the netmaker-desktop-installer.exe installer and run it to install on your Windows machine. You can then launch Netmaker Desktop, sign in and connect to your Netmaker network!

Download link: <https://fileserver.netmaker.io/releases/download/latest/netmaker-desktop-installer.exe> (netmaker-desktop-installer.exe)

For PowerShell silent installation: /netmaker-desktop-installer.exe quiet

Mac installers:

* <https://fileserver.netmaker.io/releases/download/latest/Netmaker-Desktop-Intel.pkg>
* <https://fileserver.netmaker.io/releases/download/latest/Netmaker-Desktop-M1.pkg>

Install the appropriate version, then open Netmaker Desktop, sign in to your server, and join your Netmaker network!

Ubuntu/Debian

{% code title="Ubuntu / Debian" %}

```shell
curl -sL 'https://apt.netmaker.org/netmaker-desktop/gpg.key' | sudo tee /etc/apt/trusted.gpg.d/netmaker-desktop.asc
curl -sL 'https://apt.netmaker.org/netmaker-desktop/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/netmaker-desktop.list
sudo apt update
sudo apt search netmaker-desktop  # to see available versions
sudo apt install netmaker-desktop
```

{% endcode %}

Fedora/RedHat/CentOS/Rocky

{% code title="Fedora / RHEL / CentOS / Rocky" %}

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

{% endcode %}

Following the above instructions, you can run Netmaker Desktop from your Linux desktop environment launcher or from the command line using the netmaker-desktop command.

Netmaker Desktop is supported on Ubuntu 22.04+ (glibc version 2.32+).

### Getting Started with Netmaker Desktop

To use Netmaker Desktop, you will need to have a Netmaker server running and have a user account on that server. You will also need to have a gateway set up on the server. Remote devices connect to the network through the gateway.

RAC is best suited for non-admin users who want to gain remote access to the network; this also gives net admins fine-grained control by granting users access only to the networks or gateways they need. Admins can also use Netmaker Desktop to gain remote access to the network with a different machine.

Check <https://docs.netmaker.io/docs/features/users-management-pro> on how to create a non-admin user.

#### Launching Netmaker Desktop

* Find the Netmaker Desktop shortcut on your desktop and double-click to launch it.
* Or click Start or the Windows Icon then go to All Apps and find Remote Access Client. Click it to launch.
* Find Netmaker Desktop in the Application Folder and click to launch it.
* Find the Remote Access Client shortcut and click to launch it.

#### Using Netmaker Desktop

Once a service/platform user has been given access to the network, they can connect to that network using the desktop client. To do this, they will first need to log in using the credentials that were provided to them. Social login is also supported.

![](/files/1hiWJUqDIQBQrQ4z9XDT)

**Where to find your Tenant ID / Server URL**

* To connect to a SaaS tenant, you will need to provide your tenant ID, which can be found in the Download Netmaker Desktop modal of your tenant NMUI or from the tenants interface.

![](/files/YaBsAFgUo0omEN7DxINb)

* Connecting to a self-hosted (on-premises) instance is straightforward. You only need the server URL, which typically follows the format: .domain.com. For example, if your dashboard is accessible at dashboard.example.com, the default server URL would be api.example.com.

Enter the Tenant ID / server URL in the settings screen

![](/files/UQAdrNXYGhzqkG9vjkBV)

After successful login you will be shown all the networks and gateways you have been given access to, so you will be able to connect/disconnect/refresh your connection to a gateway.

Internet gateways are depicted with a globe icon. An internet gateway can be used to route all your traffic through the gateway, this is useful if you want to access the internet without exposing your public IP address. This behaves like a traditional VPN.

![](/files/2J6iNaUsv6J9DndLh6Uk)

The remote access client also has the following features:

* Connect / Disconnect to network: Networks you have access to are listed after a successful login. Under these networks, you will also see a list of gateways you can use to connect to the network. If there are multiple, select the gateway you prefer by clicking on it. Click on the switch to the right of the network name to connect to (or disconnect from) the network.
* Reload: Reloads the network data on the page, which can be useful if an admin has changed network or gateway settings or access from the dashboard.
* Logout: Disconnects any active network connection and logs you out of the desktop client.
* Info boxes: Show a glimpse of network statistics (when connected to a network) and gateway details.

#### Using Netmaker like a “normal VPN”

Some remote access gateways, specifically internet gateways (depicted by globe icon) can route all your traffic through them. This can be useful if you want to access the internet without exposing your public IP address. This behaves like a traditional VPN. Internet gateways is a Pro-only feature.

<figure><img src="/files/dP5aHkEnYBD0YP6ICE2Y" alt=""><figcaption></figcaption></figure>

![](https://docs.netmaker.io/docs/client-installation/Base64-Image-Removed)Internet Gateways (depicted by the globe icon) allow a user to use Netmaker like a normal VPN service

### (Re)Starting the service / daemon process

On very few occasions, the Netmaker Desktop daemon may not be running and will need to be restarted manually. There are two ways to resolve this:

{% stepper %}
{% step %}

### Restart the computer

The daemon starts automatically on boot so restarting the computer will start the daemon on next startup.
{% endstep %}

{% step %}

### Manual restart on Windows

* Open Task Manager.
* Go to the “Services” tab.
* Look for the “netmaker-desktop-daemon” service.
* Right-click on the service and select “Restart” or “Start”.
  {% endstep %}

{% step %}

### Manual restart on macOS (launchd)

Netmaker Desktop daemon relies on launchd to manage the service. Restart via launchctl:

{% code title="macOS" %}

```shell
sudo launchctl stop com.gravitl.netmaker-desktop
sudo launchctl start com.gravitl.netmaker-desktop
```

{% endcode %}
{% endstep %}

{% step %}

### Manual restart on Linux (systemd)

Netmaker Desktop daemon relies on systemd to manage the daemon. Restart via systemctl:

{% code title="Linux" %}

```shell
sudo systemctl stop netmaker-desktop
sudo systemctl start netmaker-desktop
```

{% endcode %}
{% endstep %}
{% endstepper %}

### Controlling Netmaker Desktop user sessions

On pro servers/tenants, the duration of a non-admin user’s remote session can be controlled by setting RAC\_AUTO\_DISABLE (to true) and JWT\_VALIDITY\_DURATION (to an integer in seconds) environment variables on the server.

With RAC\_AUTO\_DISABLE set to true, a non-admin user’s remote sessions will be disabled after the duration specified in JWT\_VALIDITY\_DURATION has elapsed. The user will have to relogin to enable their remote session again.

NOTE: The JWT\_VALIDITY\_DURATION environment variable also configures all JWT token validity duration for all users, regardless of whether RAC\_AUTO\_DISABLE is set to true or not.

On newer servers (v0.90.0+), there is the option to restrict users from connecting to multiple networks simultaneously with the RAC\_RESTRICT\_TO\_SINGLE\_NETWORK environment variable. Setting this to true will allow users to only connect to one network and gateway at a time. Any other value will not restrict the user; they will be able to connect to multiple networks at the same time.

### FAQs

<details>

<summary>Q: I am getting an error when trying to connect to a gateway.</summary>

A: Make sure that the gateway is running healthily and that you have access to it. Also try to “Refresh” and see if that fixes the issue. Otherwise “Reset” all connections and try again.

</details>

<details>

<summary>Q: Other WireGuard-based VPNs interfere with Netmaker RAC.</summary>

A: This is a known issue. If you have other WireGuard-based VPNs running on your machine, they may interfere with Netmaker RAC. You can try to disable them and see if that fixes the issue. Pro-tip: Netmaker Pro offers internet gateway functionality, so you can use it just as a traditional VPN. For more information, explore the Remote Access gateway feature: <https://www.netmaker.io/features/remote-access-gateway>

</details>

### Uninstalling Netmaker Desktop

If the app is currently open, logout from the app, and quit the app before continuing.

{% stepper %}
{% step %}

### Uninstall on Windows

* Open Control Panel.
* Under Programs, click Uninstall a program.
* Find Netmaker Desktop Installer and Netmaker Desktop.
* Click Uninstall.
  {% endstep %}

{% step %}

### Uninstall on macOS

* Drag Netmaker Desktop from the application folder to the trash bin.
  {% endstep %}

{% step %}

### Uninstall on Debian / Ubuntu

{% code title="Debian / Ubuntu" %}

```plaintext
sudo apt remove netmaker-desktop
```

{% endcode %}
{% endstep %}

{% step %}

### Uninstall on Fedora / RedHat / CentOS / Rocky

{% code title="Fedora / RHEL / CentOS / Rocky" %}

```plaintext
sudo dnf remove netmaker-desktop
```

{% endcode %}
{% endstep %}
{% endstepper %}

***

## Remote Access Client (RAC)

Note: Starting from v0.90.0, Netmaker Desktop will be the preferred client for Windows, Mac, and Linux users.

### Overview of Remote Access Client (RAC)

The Remote Access Client (RAC) is a graphical user interface (GUI) tool designed to help users connect to a Netmaker network from an offsite machine or device. It is ideal for remote users who need access to the network but do not need full administrative control.

Key Features:

* VPN-like functionality: RAC allows mobile users to connect to a Netmaker network and route their internet traffic through a remote access gateway, similar to traditional VPNs.
* Simple and secure connection: Once a user has been granted access to a Netmaker network, they can log in and easily connect using RAC.
* Social login support.
* No administrative access required for typical remote users.

### Download / Installation

You can download the remoteclientbundle.exe bundle (recommended—it installs WireGuard and other dependencies) or remote-access-client\_86.msi installer (MSI doesn't install dependencies) and run it to install on Windows.

Download link: <https://fileserver.netmaker.io/releases/download/v0.30.0/remoteclientbundle.exe>

For PowerShell silent installation: /remoteclientbundle.exe quiet

Mac installers:

* M1: <https://fileserver.netmaker.io/releases/download/v0.30.0/remote-access-client-M1.pkg>
* Intel: <https://fileserver.netmaker.io/releases/download/v0.30.0/remote-access-client-intel.pkg>

Ubuntu / Debian

{% code title="Ubuntu / Debian" %}

```shell
curl -sL 'https://apt.netmaker.org/remote-client/gpg.key' | sudo tee /etc/apt/trusted.gpg.d/remote-client.asc
curl -sL 'https://apt.netmaker.org/remote-client/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/remote-client.list
sudo apt update
sudo apt search remote-client  # to see available versions
sudo apt install remote-client
```

{% endcode %}

Fedora / RedHat / CentOS / Rocky

{% code title="Fedora / RHEL / CentOS / Rocky" %}

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

{% endcode %}

Following the above instructions, you can run RAC from your Linux desktop environment launcher or from the command line using the remote-client command.

Google Play Store (Android):

![Netmaker RAC on Google Play Store](/files/a6eb2083133e1c1b0b3dc0e6af8bed4410835488)

Or use: <https://play.google.com/store/apps/details?id=com.net.netmaker\\&pli=1\\&utm\\_source=docs>

Apple App Store (iOS):

![Netmaker RAC on Apple App Store](/files/2e8e0da2979ac303a8136d19636761500ce35d37)

Or use: <https://apps.apple.com/us/app/netmaker-rac/id6479694220?itsct=apps\\_box\\_badge\\&itscg=30200>

You can download the latest version of RAC from the file server: <https://fileserver.netmaker.io/releases/download/latest> — search for remote client and download the appropriate version for your OS.

### Using RAC

{% stepper %}
{% step %}

### Login

Open the RAC app on your device. Enter the Tenant ID and Server URL (if using a self-hosted instance) to log in. You will then be prompted to enter your credentials. If social login is supported, you can log in with your social account.
{% endstep %}

{% step %}

### Connecting to the Network

Once logged in, you will see a list of networks and gateways you have access to. Select a network and a gateway to establish a connection. Some gateways, especially internet gateways (depicted with a globe icon), allow you to route your traffic through the gateway, providing VPN-like functionality.
{% endstep %}

{% step %}

### Refreshing the Connection

If you're facing any issues with connectivity, you can refresh your connection to the gateway using the "Refresh" option in the RAC interface.
{% endstep %}

{% step %}

### Disconnecting

You can disconnect from the network at any time by selecting the Disconnect option.
{% endstep %}
{% endstepper %}

#### Internet Gateways (Pro-Only Feature)

Some remote access gateways, especially internet gateways, allow users to route all traffic through them, providing VPN-like functionality. This is useful for maintaining privacy and security by masking your public IP address. The internet gateway feature is a Pro-only feature and requires a Netmaker Pro subscription.

### Controlling User Sessions

On Pro-level servers, network admins can control user sessions for non-admin users. Admins can set the session expiration time using these environment variables:

* RAC\_AUTO\_DISABLE: Set to true to automatically disable remote sessions after a certain duration.
* JWT\_VALIDITY\_DURATION: Specifies the session duration in seconds. Once elapsed, the user will need to log in again.

Admins can also restrict users to a single network connection at a time using RAC\_RESTRICT\_TO\_SINGLE\_NETWORK.

### Troubleshooting

* Issue connecting to a gateway: Ensure the gateway is online and accessible. Try refreshing the connection or resetting all connections if needed.
* Conflicts with other VPNs: Other WireGuard-based VPNs may interfere with RAC. Disable them temporarily to see if the issue is resolved.

### Uninstalling RAC

If the app is currently open, logout from the app, and quit the app before continuing.

{% stepper %}
{% step %}

### Uninstall on Windows

* Open Control Panel.
* Under Programs, click Uninstall a program.
* Find Remote Access Client Installer and Remote Access Client.
* Click Uninstall.
  {% endstep %}

{% step %}

### Uninstall on macOS

* Drag Remote Access Client from the application folder to the trash bin.
  {% endstep %}

{% step %}

### Uninstall on Debian / Ubuntu

{% code title="Debian / Ubuntu" %}

```plaintext
sudo apt remove remote-client
```

{% endcode %}
{% endstep %}

{% step %}

### Uninstall on Fedora / RedHat / CentOS / Rocky

{% code title="Fedora / RHEL / CentOS / Rocky" %}

```plaintext
sudo dnf remove remote-client
```

{% endcode %}
{% endstep %}
{% endstepper %}


# Mobile App Installation

The Mobile App offers secure, seamless access to a Netmaker network on iOS and Android devices.

## Download / Installation

The Mobile App is available on both iOS and Android, providing a simple way for mobile users to connect to a Netmaker network.

Google Play Store (Android):

Scan the QR code

<img src="/files/37a2710ba2492558ae4bde3d055a779960ff9e41" alt="Netmaker RAC on Google Play Store" width="188">

Apple App Store (iOS):

Scan the QR code

<img src="/files/fcdbfc842ed7e49bbfa960fc8ac6d81af3bb9d47" alt="Netmaker RAC on Apple App Store" width="188">

## Launching Netmaker (Mobile)

Android and iOS: Find Netmaker RAC in the app list and tap to launch it.

## Using the Mobile App

{% stepper %}
{% step %}

### Login

Open the app and enter the Tenant ID and Server URL (if using a self-hosted instance).

For Self-hosted, the login screen will look like this:\
![Image](https://media.discordapp.net/attachments/1278705372894462003/1354570547513659573/IMG_20250326_223347.jpg?ex=67e5c5a1\&is=67e47421\&hm=dfda3f78e39b1e60d668d3dcfc6f3fda03ccf9ef100709637c4a5be0ec06e05b&=\&format=webp\&width=409\&height=735)

For SaaS, the login screen will look like this:\
![Image](https://media.discordapp.net/attachments/1278705372894462003/1354570547241156781/IMG_20250326_223420.jpg?ex=67e5c5a1\&is=67e47421\&hm=dc10ed335bbfa53ffbeb55a6cbc8016908a64be406b9a8849391000186a6470b&=\&format=webp\&width=429\&height=735)

Users will then enter their credentials or authenticate via social login.
{% endstep %}

{% step %}

### Refresh / Logout

The Reload button (🔄) refreshes the network list, while the Logout button (➡️) signs out.

![](/files/YZdjtVCOR9fUmAD9BCxh)
{% endstep %}

{% step %}

### Connect to the Network

After logging in, select an available network and gateway to establish a connection. Internet gateways (globe icon) provide VPN-like functionality.

![](/files/2dlYP2P5oPVwlAyvltFf)
{% endstep %}

{% step %}

### Refreshing the Connection

If connectivity issues arise, refresh the connection using the Refresh option.

![](/files/V7UUW1zfsWbIlS6CQkuk)
{% endstep %}

{% step %}

### Disconnecting

You can disconnect from the network at any time by selecting Disconnect.

![](/files/xu11BFNOGzetFmzKO3F9)
{% endstep %}
{% endstepper %}

## Uninstalling the Mobile App

If the app is currently open, logout from the app and quit it before continuing.

{% stepper %}
{% step %}

### Android

1. Open the Google Play Store app.
2. At the top right, tap the Profile icon.
3. Tap Manage apps & devices. Manage.
4. Find and tap Netmaker.
5. Tap Uninstall.
   {% endstep %}

{% step %}

### iOS

Find the Netmaker RAC app.

1. Touch and hold the Netmaker RAC app.
2. Tap Remove App.
3. Tap Delete App, then tap Delete to confirm.

If you can't find the app, [use Spotlight to search for it](https://support.apple.com/en-ph/118232). You can delete apps from Spotlight.
{% endstep %}
{% endstepper %}


# Upgrading your Client and Server

## Introduction

These steps will help you upgrade to the latest version of Netmaker. Note that all instructions here assume you have installed using docker compose. You may need to modify these steps depending on your setup.

As of v0.20+, the server configuration is stable, meaning you should only need to:

{% stepper %}
{% step %}

### Update image tags

Change the associated docker image tags for the Netmaker server and Netmaker UI.
{% endstep %}

{% step %}

### Restart services

Restart the server and UI using the new image (for example: `docker compose up -d`).
{% endstep %}
{% endstepper %}

For migrating from v0.17.1, you can use the migration steps listed below under [Upgrade from v0.17.1 to Latest](#upgrade-to-latest-from-v0171)

For older versions of Netmaker (pre-v0.17.1), you must first manually upgrade to v0.17.1 before running the migration script.

## Client Upgrades (General)

As of v0.20.5, the Netclient should automatically upgrade itself when it detects a change in the server version. For prior versions of the netclient (or if this fails), you will need to manually upgrade the client.

For Linux and Freebsd: Download the netclient for your target version, OS, and arch, from [the fileserver](https://fileserver.netmaker.io/releases/download). Then run `./netclient install` from the downloaded executable in your terminal.

For Mac and Windows: Download and run the installer (.EXE for Windows, .PKG for Mac) for your target version, OS, and arch, from [the fileserver](https://fileserver.netmaker.io/releases/download). Then, run the installer.

## Server Upgrades (v1.5.1+)

**Upgrade Notice for v1.5.1+**

* **Prerequisites**: To upgrade to v1.5.1 or later successfully, you must be running at least version v1.0.0. Direct upgrades from versions earlier than v1.0.0 to v1.5.1 are not supported.
* **Schema Migration**: v1.5.1 begins a schema migration process, moving all tables from a key-value store to SQL. The following tables are migrated in this version:
  * Users
  * Roles
  * Groups
  * Networks
  * Hosts
* **Note**: Additional tables will be migrated in future releases.

## Server Upgrades (v0.20.0+)

Unless otherwise noted, for newer versions of Netmaker:

{% stepper %}
{% step %}

### Connect to the server

SSH to the server hosting Netmaker.
{% endstep %}

{% step %}

### Edit environment file

Open the `netmaker.env` file using a text editor.
{% endstep %}

{% step %}

### Update image tags

Change `UI_IMAGE_TAG` and `SERVER_IMAGE_TAG` to the latest version.
{% endstep %}

{% step %}

### Restart

Run `docker compose up -d`.
{% endstep %}
{% endstepper %}

1. For versions prior to v0.20.5, follow the [Client Upgrades](#client-upgrades-general) instructions to upgrade your netclients.
2. For v0.20.5 or later, check in the UI to confirm that all nodes have successfully upgraded to the new version.

test line

## Upgrade to latest from v0.17.1

These steps assume you have already upgraded your server and netclients to v0.17.1.

### General Notes

1. The server should be upgraded before any clients.
2. Relays will need to be recreated after the server and all clients are upgraded. Relays are now only available on Pro.
3. If upgrading to Pro, a new license key and tennet id must be obtained from [https://app.netmaker.io](https://app.netmaker.io/)
4. As each netclient is updated, a new nodes, nodes, and gateways (if applicable) will be visible in the netmaker UI.
5. Extclient config files may have to be regenerated after the upgrade.

### Steps

{% stepper %}
{% step %}

### Download upgrade script

Download the `nm-upgrade.sh` script from: <https://fileserver.netmaker.io/upgrade/nm-upgrade.sh>
{% endstep %}

{% step %}

### Run upgrade script

Make the script executable and run it.
{% endstep %}

{% step %}

### Verify server node

After the upgrade, you should see only one node in the Netmaker UI. It will have the same name as the hostname of your server, rather than `netmaker-1`.
{% endstep %}

{% step %}

### Upgrade netclients

Do not use packages to upgrade on Windows/Darwin; use the netclient binary to update.
{% endstep %}

{% step %}

### Client-specific install commands

Linux/Freebsd/Darwin:

* On each client download [the latest version](https://fileserver.netmaker.io/latest) of netclient and run the `netclient install` command.

Windows:

* On each client download `https://fileserver.netmaker.io/latest/netclient-windows-amd64.exe`
* Open a PowerShell window as Administrator and run:
  * `net stop netclient`
  * `C:\Users\User\Downloads\netclient-windows-amd64.exe install`
    {% endstep %}

{% step %}

### Verify clients in UI

As each netclient is updated, check that a new node, nodes, and gateways (if applicable) are visible in the Netmaker UI.
{% endstep %}

{% step %}

### Recreate relays for Pro

If upgrading to Pro, recreate any relay gateways.
{% endstep %}

{% step %}

### Verify extclient configs

Verify extclient config files are correct. Delete and regenerate if incorrect. For each peer in config file:

* the peer’s public key should be the same as the peer’s public key in the Netmaker UI
* the peer’s endpoint should be the same as the peer’s endpoint in the Netmaker UI
* the peer’s allowed ips should be the same as the peer’s allowed ips in the Netmaker UI
  {% endstep %}
  {% endstepper %}

Your Netmaker server and clients should all now be running the latest version of Netmaker.

## Critical Notes for 0.13.X

If upgrading from 0.12 to 0.13, refer to this gist: <https://gist.github.com/afeiszli/f53f34eb4c5654d4e16da2919540d0eb>

## Critical Notes for 0.10.0

At the time of this writing, an upgrade process has not been defined for 0.10.0. DO NOT follow this documentation to upgrade from a prior version to 0.10.0. An upgrade process will be defined shortly. For now, if you seek to upgrade to 0.10.0, you must clear your server entirely (`docker compose down --volumes`), uninstall your netclients, and re-install netmaker + netclients.

## Upgrade the Server (prior to 0.10.0)

To upgrade the server, you only need to change the docker image versions:

{% stepper %}
{% step %}
SSH to the server:

```bash
ssh root@my-server-ip
```

{% endstep %}

{% step %}
Stop compose:

```bash
docker compose down
```

{% endstep %}

{% step %}
Edit docker-compose:

```bash
vi docker-compose.yml
```

Change `gravitl/netmaker:<version>` and `gravitl/netmaker-ui:<version>` to the new version.
{% endstep %}

{% step %}
Start compose:

```bash
docker compose up -d
```

{% endstep %}
{% endstepper %}

## Upgrade the server after v0.16.1

There have been changes to the MQ after v0.16.1. You will need to make changes to the docker-compose.yml and get the new `mosquitto.conf` files. We recommend upgrading your server first before any clients.

Start by shutting down your server with:

```bash
docker compose down
```

You then need to get the updated `mosquitto.conf` file. You will also need to get the `wait.sh` file and make sure it is executable.

```bash
wget -O /root/mosquitto.conf https://raw.githubusercontent.com/gravitl/netmaker/master/docker/mosquitto.conf
wget -q -O /root/wait.sh https://raw.githubusercontent.com/gravitl/netmaker/develop/docker/wait.sh
chmod +x wait.sh
```

Then make the following changes to the `docker-compose.yml` file.

* change image tags in netmaker and netmaker-ui service sections to `gravitl/netmaker:v.0.16.1`.

In your `netmaker` service section:

* In the volumes section, change `- shared_certs:/etc/netmaker` to `- mosquitto_data:/etc/netmaker`
* In the environment section, add `MQ_ADMIN_PASSWORD: "<CHOOSE_A_PASSWORD_YOU_WOULD_LIKE_TO_USE>"`

In the `mq` service section:

* Add `command: ["/mosquitto/config/wait.sh"]`
* Add an environment section and add `NETMAKER_SERVER_HOST: "https://api.NETMAKER_BASE_DOMAIN"`
* In the volumes, add `- /root/wait.sh:/mosquitto/config/wait.sh`
* You need to make some changes to the labels. A few of them just need `mqtts` to be `mqtt`. The labels should look like this:

```plaintext
- traefik.enable=true
- traefik.tcp.routers.mqtt.rule=HostSNI(`broker.NETMAKER_BASE_DOMAIN`)
- traefik.tcp.routers.mqtt.tls.certresolver=http
- traefik.tcp.services.mqtt.loadbalancer.server.port=8883
- traefik.tcp.routers.mqtt.entrypoints=websecure
```

Your MQ section should look like this after the changes.

```plaintext
mq:
container_name: mq
image: eclipse-mosquitto:2.0.11-openssl
depends_on:
  - netmaker
restart: unless-stopped
command: ["/mosquitto/config/wait.sh"]
environment:
  NETMAKER_SERVER_HOST: "https://api.NETMAKER_BASE_DOMAIN"
volumes:
  - /root/mosquitto.conf:/mosquitto/config/mosquitto.conf
  - /root/wait.sh:/mosquitto/config/wait.sh
  - mosquitto_data:/mosquitto/data
  - mosquitto_logs:/mosquitto/log
expose:
  - "8883"
labels:
  - traefik.enable=true
  - traefik.tcp.routers.mqtt.rule=HostSNI(`broker.NETMAKER_BASE_DOMAIN`)
  - traefik.tcp.routers.mqtt.tls.certresolver=http
  - traefik.tcp.services.mqtt.loadbalancer.server.port=8883
  - traefik.tcp.routers.mqtt.entrypoints=websecure
```

You should be all set to:

```bash
docker compose up -d
```

Note: Your clients will show in warning until they are also upgraded. The upgrade for clients is the regular upgrade, then do a `netclient pull`.

If your `docker logs mq` show repeated "Waiting for netmaker server to startup" after longer than usual, check if your Traefik certs are generated correctly. You can try to resolve with:

```bash
docker restart traefik
```

Example expected MQ logs:

```plaintext
Waiting for netmaker server to startup
...
Starting MQ...
1665067766: mosquitto version 2.0.11 starting
...
1665067769: New client connected from 172.21.0.2:34004 as L0vUDgN0IZFru9VaS6HoRL5 (p2, c1, k60, u'Netmaker-Admin').
```

## Upgrade the server to use 0.17.0 after Upgrading for 0.16.3

Version 0.17.0 uses Caddy instead of Traefik.

To set up Caddy you’ll need to configure the Caddyfile as follows.

Community Edition:

```bash
wget -O /root/Caddyfile "https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile"
```

Professional Edition:

```bash
wget -O /root/Caddyfile "https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile-pro"
```

Once you have a Caddyfile you’ll need to run these two commands:

```bash
sed -i "s/NETMAKER_BASE_DOMAIN/$NETMAKER_BASE_DOMAIN/g" /root/Caddyfile
sed -i "s/YOUR_EMAIL/$EMAIL/g" /root/Caddyfile
```

Where `$NETMAKER_BASE_DOMAIN` is the base domain you used for your Netmaker setup and `$YOUR_EMAIL` is your email address.

If users still want to keep using Traefik as the reverse-proxy instead of Caddy for v0.17.0 and above, refer to this docker-compose file: <https://gist.github.com/alphadose/1602e5dcba500f75ab0b873d4441236b>

Edit the above docker-compose file:

```bash
sed -i 's/NETMAKER_BASE_DOMAIN/<your base domain>/g' docker-compose.yml
sed -i 's/SERVER_PUBLIC_IP/<your server ip>/g' docker-compose.yml
sed -i 's/REPLACE_MASTER_KEY/<your generated key>/g' docker-compose.yml
sed -i "s/REPLACE_MQ_ADMIN_PASSWORD/<your generated password>/g" docker-compose.yml
```

After that finally start the netmaker server:

```bash
sudo docker compose up -d
```

## Upgrade the Clients (prior to 0.10.0)

To upgrade the client, you must get the new client binary and place it in `/etc/netclient`. Depending on the new vs. old version, there may be minor incompatibilities (discussed below).

{% stepper %}
{% step %}

### Find release

Visit: <https://github.com/gravitl/netmaker/releases/>
{% endstep %}

{% step %}

### Download binary

Find the appropriate binary for your machine and download, e.g.:

```bash
wget https://github.com/gravitl/netmaker/releases/download/vX.X.X/netclient-myversion
```

{% endstep %}

{% step %}

### Install binary

Rename binary to `netclient` and move to folder, e.g.:

```bash
mv netclient-myversion /etc/netclient/netclient
```

{% endstep %}

{% step %}

### Verify and pull

Check version:

```bash
netclient --version
```

Then run:

```bash
netclient pull
```

This helps ensure any newly added fields are now present.
{% endstep %}
{% endstepper %}

You may run into a “panic” based on missing fields and your version mismatch. In such cases, you can either:

* Add the missing field to `/etc/netclient/config/netconfig-yournetwork` and then run `netclient checkin`

or

* Leave and rejoin the network


# Operations Field Guide


# Introduction and Index

The purpose of this document is to provide IT Administrators with opinionated but flexible directions for implementing and operating the Netmaker platform.

The goal is to provide you with a complete walkthrough from start to finish, presenting configuration options and guidance at each stage so that by the end of this guide you have the exact network setup and configuration that is desirable for your organization and networking scenario.

This guide will walk you through:

* Deploying and configuring the coordination server (Netmaker)
* Planning and creating your networks (VPNs)
* Deploying your endpoints (Nodes, Clients, WireGuard config files)
* Configuring traffic (Gateways, Egress)
* Onboarding and managing users (Remote Access)
* Accessing the VPN as an end user
* Troubleshooting connectivity and operational issues
* Monitoring your network traffic

We encourage you to skip around this guide depending on your stage of implementation and needs, or to go through the guide in its entirety to get a complete picture.

## Next steps

In the next section, we’ll cover the high-level networking scenarios and terminology used throughout this guide.


# Networking Scenarios, VPN Types, and Terminology

## Introduction

The purpose of this chapter is to provide you with an overview of some common networking scenarios we see at Netmaker that you may be attempting to implement, and explain some terms as they relate to these scenarios, to provide context throughout the course of the guide.

By the end of this chapter, you should have a general understanding of the various scenarios, how they relate to Netmaker, and the terminology typically employed in these scenarios.

## Types of VPNs

When an administrator is tasked with setting up a VPN, they likely have a particular goal, or set of goals. Here are some of the most common we see:

{% stepper %}
{% step %}
Provide a group of users with remote access to a site, such as an office, or to particular devices, such as a server, e.g. **Remote Access**.
{% endstep %}

{% step %}
Route all user or device network traffic through a specific endpoint (Gateway), e.g. a **Full Tunnel VPN**.
{% endstep %}

{% step %}
Create secure links between particular devices, such as servers at the edge, and VMs in the cloud, e.g. a **Point-to-Point VPN or Overlay Network.**
{% endstep %}

{% step %}
Create secure links between sites, such as an office and a cloud environment, e.g. **Site-to-Site**.
{% endstep %}
{% endstepper %}

You may be attempting to accomplish one or more of these goals. For example, your employees may need **remote access** to the office, and the office may need a **site-to-site** connection with a data center. All can be accomplished with Netmaker, using multiple VPN networks configured in different ways, to create a mix of VPN topologies.

## Devices and Sites

Before discussing these scenarios, let’s break it down into the base components: **Devices** and S**ites**.

### What is a Device?

![](/files/9715fbeb69d6fa86200a41a71ab0b1c39cc1ed6d)

By a device, we mean an endpoint. Think of a particular device, server, or IP address. A **device** is one particular network resource. When we use words like **device**, **host**, **node**, **endpoint**, **peer**, or **ip (singular)**, we are typically referring to a “device.” Devices are typically configured with a VPN client on the device itself, so that you have direct access to (or from) the resource over the VPN.

### What is a Site?

![](/files/4a1ecb56417b7f72297c2d48f682c5049029aa80)

A **Site** is typically a **local** or **private network,** a **subnet** or **ip cidr range**. It could be an office LAN, a data center subnet, or a cloud VPC. Think of it as a collection of network resources contained within a subnet. You may need to provide access to or from these sites. When we mention an **environment**, **subnet**, **local network,** **private network**, **cidr**, or **vpc,** we are typically referring to a “site.”

A site is not meant to refer to the whole internet, but conceptually, you can think of the internet as just a really big site, with special rules.

When setting up access to and from a site, it is usually easier to have one or more **devices** acting as **Egress**, which will forward traffic from the VPN to the site. Those devices, usually  servers or routers, will be the only devices configured with a VPN client inside of the network, and will rote traffic for the entire site, to simplifies operations.

An alternative approach would be a **full overlay network**, where every device at each site is configured with the VPN client.

## Types of VPNs (Patterns with Devices and Sites)

Now let’s discuss the types of networks you can create with devices and sites.

### Peer-to-Peer

In a point-to-point, or peer-to-peer VPN, we are connecting devices directly to one another. This is useful to minimize network hops, minimize the security perimeter, and create lower level access controls between devices on the network. If you have a server in a data center that needs to connect directly to a VM in the cloud, this would be peer-to-peer. Another modern phrase for this is a **mesh VPN or overlay network.**

In Netmaker, this is the default configuration when you deploy VPN endpoints using the Netclient.

![](/files/e8bd7bb3f4b2c9edf6d1c6dd7852531b0a5bb208)

### Hub-And-Spoke

In a Hub-And-Spoke VPN, we are connecting endpoints together via a **Hub**. The **Hub** is one of the devices in the network, which forwards traffic to and from the other devices. This can simplify setup and increase reliability, though it comes at the cost of **increased latency**, because connections are not direct.

![](/files/c2b000769644e080a958bf5e0d192e5d01845708)

In Netmaker, if you use Static WireGuard Clients, they will always be connected using a Hub, which inside of Netmaker is called a Gateway. You can also assign particular Nodes (devices) to a Gateway, and traffic will flow through the gateway to and from the device, rather than peer-to-peer. In Netmaker, you can have a mix of peer-to-peer and hub-and-spoke configurations inside of a single network.

![](/files/4a4a4868d7a99bf8c2587cb936abed3624b2e716)

### Point-to-Site

In a Point-to-Site VPN, we are connecting endpoints to a site by routing traffic through an endpoint (or endpoints) at that site. This is typically called **Remote Access,** and in Netmaker this uses the Egress function. In this scenario, the site itself **is not a part of the VPN.** As an example, if you are providing remote access to an office network from remote employee devices, this would be point-to-site. Traffic is routed into the office network via specific endpoints located inside of the office network, but the destination for traffic will be outside of the VPN.

![](/files/d8433a2cc8b03894cd8a47d1b4cf62e5bc6999a4)

Remote Access is the most common form of VPN we see at Netmaker, so we’ll go into more details on this topic below.

Note the similarities between a Point-to-Site and Hub-and-Spoke network, where a single point is **relaying** connections to and from the site.

### Site-to-Site

With a Site-to-Site configuration, we are connecting two or more sites together, without installing the VPN client on all of the devices at either site. Instead, a set of devices (such as routers) will handle all of the traffic flowing between the sites.

A typical scenario would be two or more office branches which need to communicate securely. By installing a Netmaker client[ on **routers**](/getting-started/operations-field-guide/site-to-site-and-routers) at these sites, a secure tunnel is created over the internet, over which the office traffic can flow.

![](/files/cc2ca8b2181d6603acb07ca4fa0ef8d7bd8cce64)

Site-to-Site VPNs can also be created in a Hub-and-Spoke configuration, which can again simplify operations. In Netmaker this is the configuration when you use **static wireguard** on the routers.

![](/files/5149fea79ba3da2c4beff98e469f133ff4671610)

### Full Tunnel VPN (Internet Gateway)

A Full Tunnel VPN is basically a Point-to-Site VPN, where the “Site” is the entire internet. All of the traffic from assigned devices, regardless of destination, is routed through a particular endpoint in the VPN, and then forwarded out to the internet. This is how a standard “layperson” VPN functions, for example NordVPN. In a business setting, you might want to set this up in order to monitor or restrict internet access from employee devices, by routing traffic through an endpoint where some firewall functionality is installed.&#x20;

In Netmaker, this is done via [Internet Gateways](/features/gateways#internet-gateway), a special function of the Gateway (as opposed to Egress).

![](/files/99bdac8d955ff1143a698af6eeb1c18e98179afb)

## Combining Patterns

At Netmaker, we find that many users are looking to accomplish more than one of these patterns simultaneously. Consider Customer X, who wanted to:

{% stepper %}
{% step %}
Provide Remote Access to the Office from Remote Employee Workstations
{% endstep %}

{% step %}
Route Employee Internet Traffic through an Endpoint in the Office
{% endstep %}

{% step %}
Create a Site-to-Site Connection between their Office and their Cloud
{% endstep %}
{% endstepper %}

The result was a mix of point-to-point, site-to-site, full tunnel, and hub-and-spoke patterns. Luckily, all of this can be done with Netmaker!

![](/files/fe0663ce8238430b7f67c2acb911b75816ebd39a)

## Remote Access

Lastly, let’s discuss Remote Access in more detail, which is usually a Point-to-Site VPN, where Employee devices are the points, and some environment (offices clouds, edge) is the site.

Remote Access is the process of providing access **to** a site **from** users, and typically consists of a few components:

{% stepper %}
{% step %}

### Source

The source is the endpoint, device, or user making the request. These devices could be anywhere, and must run some form of VPN Client in order to access the network securely to make requests.

Examples of source devices may include:

* A laptop
* A phone
* A server
* An IoT device

In the context of Netmaker, we recommend [**Netmaker Desktop**](/getting-started/server-and-client-management/client-installation/netmaker-desktop-installation) for user access, which allows users to authenticate using their credentials before they can make requests. Optionally, an administrator could use manually configured [**WireGuard VPN clients**](/getting-started/operations-field-guide/deploying-static-wireguard#integrate-non-native-devices) for devices like IoT and routers. Lastly, they could use the [**Netclient**](/getting-started/server-and-client-management/client-installation/netclient-installation), though this is typically meant for servers which are destinations or traffic forwarders (Egress, Gateway) in your network.
{% endstep %}

{% step %}

### Gateway

A [**Gateway**](/features/gateways) is used by the **source** machines to access the network. It acts as a reliable entry point for traffic, and checks to make sure requests are allowed and valid before forwarding them into the network.

If using the Netclient, no Hub is necessary, since connections are direct.
{% endstep %}

{% step %}

### Destination

This is the site being accessed from the source devices. More specifically, this will be IP addresses at the site, typically a CIDR range or ranges (subnets), or specific endpoints (IP addresses). Example destinations may include:

* A cloud VPC
* An office network
* A kubernetes cluster
* A data center
* A database

Additionally, there may be some private DNS configured at the site which you may want source devices to use, for example, so they can simply navigate to printer.mycompany.internal in their browser, rather than having to know the actual endpoint, which may be something like 192.168.15.35.
{% endstep %}

{% step %}

### Egress

This is a device located inside the Destination Environment, which routes traffic to the local network.

In Netmaker, this is most commonly configured using [**Egress**](/features/egress), but depending on the scenario, may be done in some different ways:

* [**Egress**](/features/egress) - Routes are added to a linux-based netclient in the destination environment, which automatically begins to forward VPN traffic to the selected routes, creating a **split tunnel** VPN for end users and devices.
* [**Internet Gateway**](/features/gateways#internet-gateway) - By simply switching on "Internet Gateway" in your Gateway settings, a full tunnel VPN is created, forwarding all device traffic through the specified device
* [**WireGard Config File Egress**](/help-articles/egressing-wireguard-clients) - If access must be configured on a device which cannot run the netclient, such as a Router, you can generate a Config File and specify Egress ranges directly on the configuration. Run the file on a destination device using any WireGuard-compatible plugin, and confirm traffic forwarding is configured, and this device will work the same as regular Egress.
  {% endstep %}
  {% endstepper %}

### Next Steps <a href="#next-steps" id="next-steps"></a>

Before you continue, we recommend reviewing our [**Glossary**](/getting-started/about/glossary), which contains helpful terminology we will use throughout the course of the guide. After that, we'll proceed to Netmaker Server Deployment.


# Netmaker Server Deployment

## Overview

In this section of the field guide, we discuss deployment options for your Netmaker Server, including On-Prem vs SaaS deployment. In this guide we rely on several features available only in the Teams and Business version, so we assume you are not using the Community version of Netmaker.&#x20;

You are welcome to use this guide with just the open source version of Netmaker, but note that some features may be missing depending on what you are attempting to do.

As a note, you can get a free trial license, for both SaaS and On-Prem, by visiting [app.netmaker.io](https://app.netmaker.io).

## Determine SaaS vs. On Prem

We’ll begin by discussing the options of SaaS and On-Prem. At a high level, here are the differences.

|                                                                                                                                   |                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Netmaker SaaS**                                                                                                                 | **Netmaker On-Prem**                                                                                                                                                        |
| Recommended for most use cases. The easiest way to get started and manage Netmakr, because we manage the Netmaker server for you. | Recommended for IT Administrators deploying Netmaker who require enhanced data privacy, server customizations, custom Oauth integration, or metrics exporting capabilities. |

### Consideration for ITSPs and MSPs

You can deploy multiple servers of either SaaS or On-Prem. If you are a B2B company that provides IT Services, you may want to create a tenant (server) per-customer, which can be done via the portal. This also allows you to have both SaaS and On-Prem tenants, depending on the use case, and to keep all settings and access segmented by account, with centralized billing.

### Flow Chart

Here is a quick flow chart that can help you decide whether SaaS or On-Prem is right for you.

<figure><img src="/files/MBEsJacVenuLLvVuD72v" alt=""><figcaption></figcaption></figure>

#### Primary Considerations for SaaS vs On-Prem <a href="#determine-saas-vs-on-prem__primary-considerations-for-saas-vs-on-prem" id="determine-saas-vs-on-prem__primary-considerations-for-saas-vs-on-prem"></a>

You should default to assuming you will use the SaaS version, unless you have a particular need for On-Prem. Here are a few reasons you may need to deploy On-Prem

**White Labeling, Custom Domain**

Netmaker On-Prem allows you to use a custom domain for your server, e.g. “[netmaker.mycompany.com](http://netmaker.mycompany.com/)”. Additionally, you can customize the color scheme, labels, and logos in the On-Prem version to match your business.

**OAuth Integration**

Netmaker On-Prem allows you to integrate with any OIDC-compliant [Oauth](https://docs.netmaker.io/docs/server-installation/integrating-oauth) provider such as Auth0, [Azure](https://www.netmaker.io/resources/remote-access-to-azure) AD, and more. This can allow you to integrate your in-house auth provider, or provide a more generic authentication mechanism that integrates several different sources like Google, Microsoft, etc. SaaS, by comparison, allows you to use basic auth, Google, GitHub, and Microsoft for authentication.

**Data Controls**

For companies that have heightened data control policies, On-Prem may be necessary. For instance, companies requiring GDPR compliance may need to use Netmaker’s On-Prem edition. The only data exported to Netmaker on-prem is licensing and billing information.

Additionally, you may need to add security enhancements to your server, such as whitelisting and blacklisting IP addresses, or making it only accessible from within a particular environment.

**Metrics Exports**

Netmaker On-Prem allows you to export traffic [metrics](https://docs.netmaker.io/docs/features/metrics-pro) via Prometheus, which can be helpful for monitoring your networks.

### Creating and Managing Server Instances <a href="#creating-and-managing-server-instances" id="creating-and-managing-server-instances"></a>

Netmaker’s [account management portal](https://account.netmaker.io/) allows you to create and manage multiple instances of Netmaker, referred to as “Tenants”, for both SaaS and On-Prem.

To create a tenant, you first need to sign up at <https://account.netmaker.io/>. You must provide valid billing details, and then you can create both SaaS and On-Prem instances. Your first instance will include a free trial.

After you have created a tenant, you can either sign in directly to your dashboard (SaaS) or retrieve your deployment keys (On-Prem).

**SaaS Tenants:** An actual server instance is created for you

**On-Prem Tenants:** A license key is created that is valid for your server deployment

#### Multiple Tenants or Single Tenant <a href="#creating-and-managing-server-instances__multiple-tenants-or-single-tenant" id="creating-and-managing-server-instances__multiple-tenants-or-single-tenant"></a>

You may want to create multiple tenants depending on your use case and business needs. You should default to assuming you only need one tenant. Here are some reasons you might need multiple Tenants:

**You Manage Multiple Customers:** If you are managing Netmaker for multiple customers, the best practice would be to deploy a tenant per-customer. You can also segment your customers using multiple networks within your instance, but in most cases, this is a cleaner approach.

**You Have a Test/Staging Environments:** If you have test or staging environments for your in-house operations, you may want to have Test and Staging instances of Netmaker as well.

**You Have Global Operations:** If you have widely dispersed operations, it may be better to have multiple instances of Netmaker to improve performance..&#x20;

### Deploying Netmaker SaaS <a href="#deploying-netmaker-saas" id="deploying-netmaker-saas"></a>

Deploying Netmaker SaaS is very simple. Once you create an account, you just need to click to create a new SaaS tenant. It will take 1-3 minutes to provision, and you will then be able to log in.

### Deploying Netmaker On-Prem <a href="#deploying-netmaker-on-prem" id="deploying-netmaker-on-prem"></a>

Deploying Netmaker On-Prem can be straightforward or complex, depending on your requirements. To start, once you create an account, click to create a new On-Prem tenant. You can then go to the dashboard for your instance and retrieve the license keys necessary to deploy your server.

#### On-Prem Deployment Considerations <a href="#deploying-netmaker-on-prem__on-prem-deployment-considerations" id="deploying-netmaker-on-prem__on-prem-deployment-considerations"></a>

Deploying on-prem can be done in many ways and highly customized for your environment.

#### Single Instance vs. Highly Available <a href="#deploying-netmaker-on-prem__single-instance-vs-highly-available" id="deploying-netmaker-on-prem__single-instance-vs-highly-available"></a>

Netmaker can be deployed on a single VM or in HA-mode using Kubernetes. To deploy HA you should have an existing Kubernetes cluster you can use. For most use cases, we recommend a single-instance. The server is fairly resilient and your networks will continue to function even if there is a server failure. HA should only be considered for large-scale deployments.

#### Deploying on a Single VM

Our Platform Installation quick start is the fastest way to get going.

{% content-ref url="/pages/Z4KKBOHDo86Pa9Iz5dZg" %}
[Platform Installation](/getting-started/quick-start/platform-installation)
{% endcontent-ref %}

#### Deploying HA on Kubernetes

Netmaker can be deployed HA on Kubernetes with a Helm chart.

{% content-ref url="/pages/66de10d44a71c184ffc53f57d86a5910ef123c79" %}
[HA installation on Kubernetes](/getting-started/server-and-client-management/server-installation/ha-installation-on-kubernetes)
{% endcontent-ref %}

#### **OAuth integration**

Netmaker can be integrated with any OIDC-compliant auth provider to set up OAuth.

{% content-ref url="/pages/9d08ce7b7781bc52900cedd924ef17dd17f857f7" %}
[Broken mention](broken://pages/9d08ce7b7781bc52900cedd924ef17dd17f857f7)
{% endcontent-ref %}

#### **IDP Integration**

For Microsoft Entra, Google, and Okta, you can set up SCIM to sync your users and groups directly from the provider.

{% content-ref url="/pages/ab54d87ec96414100871bc6c6526f9a5f311600b" %}
[Identity Provider Integration Guide](/how-to-guides/identity-provider-integration-guide)
{% endcontent-ref %}

#### **Other Server Customizations**

To review a full list of server customizations, refer to our advanced installation docs.

{% content-ref url="/pages/5de4117c62630df8f0aa792d2549665945ef6d05" %}
[Advanced Options](/getting-started/server-and-client-management/server-installation/advanced-options)
{% endcontent-ref %}

### Next Steps <a href="#next-steps" id="next-steps"></a>

Once your server is deployed and configured, you can then proceed to setting up your Networks.


# Network Setup

## Overview

Creating Networks in Netmaker is a very simple process. You need at least one network for your devices, and in many cases, you will want multiple networks. In this short guide, we discuss what a Network is, when to use multiple networks, how to create networks, and your network configuration options.

## What is a Network in Netmaker?

Simply put, a Network in Netmaker is a virtual private network, or [VPN](https://www.netmaker.io/resources/wireguard-vpn). You could also refer to it as a “Virtual Subnet” or “Virtual Network”. In it, you will configure access to devices, internal and external to the VPN. So it is a logical container, or grouping, of your devices and users, that segment their access.

![](/files/xYvxPTwyMp4MVBliGSiB)

A network in Netmaker has a defined subnet (or subnets, if using both ipv4 and ipv6). All devices enrolled in the network, both Clients and Hosts, will be assigned a virtual IP Address from this range, which is the private IP address over which encrypted traffic and communications occur between devices.

![](/files/87c2486dfb22d8ae8ee41c7ac3936ad52a6a814a)

## Network Settings

Network settings are immutable. This is important to know when you create a network! If you want to change your network settings, you will need to delete and create a new one. Why? Because network properties are fundamental to the functioning of the network, and changing these settings could cause all sorts of disruptions. Luckily, there are only a few network settings to keep track of:

### Network Name

The identifier of the network. Typically will be the environment, use case, or customer name (for B2B use cases). For example, if providing remote access to an office network, consider naming the network “myoffice-1”.

### IPv4, IPv6 CIDRs

This is the virtual IP range(s) of the network. Typically, we recommend just using IPv4, unless you have a strong need for private IPv6 addresses. Note that these are just the private addresses assigned to the machines, and have nothing to do with the public addresses over which the machines reach each other. Devices can still use their ipv6 endpoints to communicate, even if the virtual network is ipv4.

You do, of course, need to specify a network size that is suitable for your network. For example:

10.10.10.0/24 - A /24 network. Will be able to include up to 254 distinct private IPs, meaning if you plan to include more than 254 machines in your private network, it will not be big enough.

10.10.0.0/16 - A /16 network. Will be able to include up to 65,534 distinct private IPs.

The slash is known as the “subnet mask.” See here for a description of various subnet masks and how many addresses they provide: <https://www.freecodecamp.org/news/subnet-cheat-sheet-24-subnet-mask-30-26-27-29-and-other-ip-address-cidr-network-references/>

Important Notes on the Address Range:

{% stepper %}
{% step %}

### Use private address space

The subnet you specify should be in the private address space. Otherwise, it may conflict with public (real world) IPs: <https://www.iana.org/help/private-addresses>
{% endstep %}

{% step %}

### Avoid conflicts with local addresses

The range specified should not conflict with any local addresses that your machines may have. For instance, a local area network (e.g. your home network) will often have an address space starting with 192.168.*.*, so this should be avoided. Many (such as [AWS](https://www.netmaker.io/resources/how-to-deploy-a-wireguard-vpn-for-aws-remote-access-with-netmaker) EC2 instances) use the prefix 172.*. This is why typically, we use a private subnet with a prefix of 10.*.
{% endstep %}
{% endstepper %}

### Default Access Control

This should almost always be set to “ALLOW”. The Default Access Control is the setting that Hosts are given for reachability.

{% hint style="info" %}
If it is set to “ALLOW”: All machines in the network can reach all other machines in the network by default. A network administrator can optionally disable connections in the “Access Controls” tab of network management.

If it is set to “DENY”: No machines will be able to reach each other by default. Any machine added to the network will have no connections. A network administrator must specify which machines can reach each other in the “Access Controls” tab of network management.
{% endhint %}

![](/files/f092f1ece7cb3fcbadcd2cee163915a5bd1ca5c6)

## The Default Network

When you deploy Netmaker on-prem from the quick install script, or sign up for the SaaS, a network will be available by default with the following properties:

* Name: netmaker
* Subnet (ipv4): 10.*.*.\*/24
* Subnet (ipv6): *:*:*:*::/64
* Default [ACL](https://www.netmaker.io/features/acls): ALLOW

Note that the specific IP ranges are randomized.

This is suitable for most standard use cases where only one network is required, and is provided to accelerate the setup process. For simple use cases, this should be all you need. However, it can be deleted if you wish to set your settings differently.

## How Many Networks Do You Need?

Planning out your Netmaker setup requires making a determination of how many Networks you will use in your setup. There are a few reasons you might want multiple networks. The main thing to keep in mind is each network acts as a different VPN, and hosts (devices added via Netclient) can be a part of multiple networks simultaneously.

### You Manage Multiple Customers

If you are an IT Services company that works with multiple customers, you may wish to manage access to or from customer environments in one platform. Setting up multiple networks is an easy way to do this. You can of course also deploy multiple “tenants” as described in the Server Deployment guide, but keeping everything on one server will be simpler for some use cases. In such a case, simply create one network per customer.

### You Have Multiple Environments or Use Cases

If you have multiple offices, clouds, testing environments, or just have vastly different use cases (e.g. remote access to office vs. allowing IoT devices to reach your cloud environment), you may want to manage these via different networks.

### You Want to Segment Access

If you have vastly different levels of access between user or machine groups, it may be easier to  segment this access using multiple networks. This can also be done within a single network via [Access Controls](/features/acls-access-controls), but using multiple networks is sometimes cleaner and easier to manage.

## Creating Networks

Once you have determined how many networks you need, making them is easy. Simply go to the Dashboard interface and click “Create Network”:

![](/files/1QPihTQRPVLdhJEkwWru)

If you are unsure, or don’t care, about the subnets, you can simply “Autofill” the settings, which is fine for most users. However, take care to choose a network name that matches the use case. For instance, if setting up remote access to a customer’s environment, consider naming it .

## Next Steps

Once you’ve created your Network(s), it’s time to add the devices that will make up your network. We’ll discuss that in the next section.


# Planning Your Endpoints

## Overview

Now that we have a network (or networks) configured for our VPN, it is time to start adding in the devices that will make up the networks. Before we do this, it is helpful to understand what needs to be deployed, and where. For instance, do you need a Node in the office on a Linux server, or a Client deployed on a Router? Do you need a [Gateway](/features/gateways) in the cloud?

This chapter will provide clarity on **what** devices you will need to add to your network, and **how** you will need to add them, including supporting features which may be necessary.

By the end of this chapter, you should have a good mental picture of which devices are going into your network, and how you will add them (via Netclient or WireGuard config file).

## Types of Clients: Netclient, Config File, Netmaker Desktop/Mobile

Netmaker has 3 types of Clients: The Netclient, Static WireGuard Config Files, and our user apps (Netmaker Desktop and Mobile).

<figure><img src="/files/ZhUPOQiaTZzQFuiGs8Ic" alt=""><figcaption></figcaption></figure>

|              |                                                                                 |                                                                                                                  |                                                                       |
| ------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|              | **Netclient**                                                                   | **Static WireGuard**                                                                                             | **User Apps**                                                         |
| Format       | Headless Daemon                                                                 | WireGuard Config File                                                                                            | GUI App for Desktop, Mobile                                           |
| OS Support   | Linux, Windows, Mac                                                             | [Many](https://www.wireguard.com/install/)                                                                       | Linux, Windows, Mac, iOS, Android                                     |
| Connectivity | <p>Peer-to-Peer<br>Always-On</p>                                                | <p>Via Gateway (Hub-And -Spoke)<br>Always-On</p>                                                                 | <p>Via Gateway (Hub-And -Spoke)<br>On Demand or Always-On</p>         |
| Capabilities | <p>Act as Hub for other Clients<br>Forward traffic to external environments</p> | <p>Can be used with many routers to support Site-to-Site<br>Deployable on any device that supports WireGuard</p> | <p>User auth-based login<br>Session Expiry<br>GUI for Ease of Use</p> |

## Netclient (Nodes)

When the Netclient is deployed to your network it appears as a Node in your dashboard.

The Netclient is meant to be deployed on servers, which are either endpoints, or will serve a routing function in the network:

* Forward traffic to a LAN or Internet
* Act as Gateway for connections from static WireGuard, users, or other Netclients

Every network will at least need one Netclient to function, so this is a good place to start.

### Netclient In Multiple Networks

A Netclient can be a part of multiple networks simultaneously, and can serve different functions in different networks. After adding a Netclient to Netmaker, you can choose to give it access to different networks. In Network A it could forward traffic to a local network, while in Network B it could just be an Endpoint, or a Relay.

The main use of this is to have dedicated clients which serve as Gateways within multiple networks, since most use cases require a Gateway. The Netclient maintains secure segmentation between networks, so traffic does not leak between them.

### Example Network with One Netclient: Internet VPN

If you are logging into Netmaker for the first time, you will see an auto-generated network with a single, default device in it, which is set as a Gateway. In order to set this device as an Internet Gateway, simply edit the device settings, and toggle on "Internet Gateway." This use case is now complete.

You, as a user, now just have to download a user app, log in, and connect, and you now have a fully functioning full-tunnel VPN.

### Example Network with Two Netclients: Remote Access VPN

The most common use case we see at Netmaker only requires 2 netclients to function.

Netclient 1: Acts as a Gateway for user connections.

Netclient 2: Acts as Egress to a local network.

Netclient 1 is deployed in a public-facing environment, so that users can access the network from anywhere. The default node works fine for this.

Netclient 2 is deployed inside the private environment, and configured to forward traffic to the local network.

![](/files/YmFwPE2W0XZA1TF5yMPz)

### Example Network with Many Netclients: Overlay Network / Mesh VPN

With servers deployed in the cloud, the office, and at the edge, Company X needed a simple overlay so these servers could all reach each other. So, they installed the Netclient on each server and to make them all accessible from one another, giving direct, peer-to-peer access between the devices.

## Static WireGuard (Clients)

If you have endpoints which do not support the netclient, you will want to generate Config Files and apply them to these devices using WireGuard.

These are just simple configuration files, which can be used on any WireGuard-compatible device.

These config files connect over a Gateway.

There are a few reasons you may want to use static WireGuard clients, rather than the Netclient:

{% stepper %}
{% step %}

### You want to deploy static files onto user devices which are “always-on” and admin-managed

Use static WireGuard config files when devices are managed by admins (e.g. no "user auth" is required) and need persistent, always-on connectivity.
{% endstep %}

{% step %}

### You want to integrate a device into your network which does not support the Netclient

Static files allow integration of devices that cannot run the Netclient but do support WireGuard, which as of today includes most operating systems and devices.
{% endstep %}

{% step %}

### You want to integrate a router into your network

When generating a Client, use the “Egress” parameter to specify a LAN range. After applying the file to the router and configuring routing, this enables communication between the LAN and the VPN.
{% endstep %}
{% endstepper %}

## User Apps (Netmaker Desktop and Mobile)

The user apps enable users to sign-in to the network using their credentials, and connect to the VPN. This is the recommended method for connecting to the VPN from end user devices for remote access. These should not be considered “Endpoints” in this context. On your local laptop, we recommend installing [Netmaker Desktop](/getting-started/server-and-client-management/client-installation/netmaker-desktop-installation) to use while testing out your network.

### Next Steps <a href="#next-steps" id="next-steps"></a>

By this point you should have a good understanding of what you will need to deploy to set up your network. Once you know which devices will serve as the foundation of your network, it is time to move on to add these devices into your network and configure them for their required role.

We will start with the non-user devices, which are the Endpoints, Routers, Relays, and Gateways of your network. After that, we will move on to configuring user access.


# Deploying the Netclient

## Overview

You have configured your Netmaker server and created a network (or networks). You have determined the layout of your network, and which devices will serve various functions within the network. Now, it is time to add and configure these devices.

![](/files/mYvORWR05rzoZjR66rTU)

This section covers adding the Netclient to your network, which make up endpoints of your network infrastructure, serve as gateways for traffic, and route (egress) traffic to external environments.

**Nodes:** Typically servers, which you want to reach directly, or which need a direct connection to the network. Examples: A jump server, a database server, edge servers.

**Gateways:** Dedicated nodes which route traffic into and between other devices in the network. Handles access from WireGuard Config Files, User Apps, and assigned Netclients (in the case of peer-to-peer connectivity issues).

**Egress:** Dedicated nodes which route traffic out of the network to an external, local environment.

In the next section, we’ll discuss setting this functionality. But first, we need to add the devices to the network. The Netclient is used on Linux, Windows, and MacOS. Other devices will require static WireGuard config files:

* To add Config Files (static WireGuard), we will need a Gateway. There should be one already deployed in your network, but we'll also cover configuring these in the next section.
* To add Routers, a custom Config File must be created, which we will do in a later section.

We will not cover how to enroll users with the network, which again will come in a later section.

With that in mind, let us begin.

## Adding New Nodes

![](/files/MDA5dtpdHi7iwiPJpXBu)

We will start by adding new Nodes to our server, which are devices running the **netclient**. Such devices can be Linux, Mac, or Windows-based. Additionally, such devices can be added using a Docker Container.

Adding **new** devices to your server consists of three steps:

{% stepper %}
{% step %}

### Create an Enrollment Key

There will already be a default Key created in your network you can use, but we can also define keys with special settings. Keys are how your device initially enrolls into the network, but they have no effect after enrollment is completed, as the devices generate their own, secure encryption keys.

<figure><img src="/files/O4fZQvi0BHH3QBfhfTwT" alt=""><figcaption></figcaption></figure>

Enrollment Keys tell the server, and the device, which networks they will have access to. They also determine if the device will be **relayed** by default, a useful feature if you know your devices are in a restricted environment.

Enrollment Keys are defined by a number of uses, an expiration date, or are simply unlimited, until you delete them. Choose the option that works for you, and select the networks which your devices will be a part of.

![](/files/ded606af986974ffd641981e3a64e4545a1f90d6)

{% hint style="info" %}
You can also create an enrollment key **without** any network access. This allows devices to enroll with your server so an administrator can later grant network access after review.
{% endhint %}
{% endstep %}

{% step %}

### Install the Netclient

After creating the key, add your devices via the “Add Device” flow within your Network. Choose the target platform to get platform-specific installation steps for the netclient.

Once the netclient is installed, you will join the server using the enrollment key provided with the command shown in the UI.

![](/files/f21bsLuPCPa9zRnA9YHL)

For Docker, run the Docker container with the provided command.

{% hint style="info" %}
For Docker: You can deploy multiple netclient docker containers on a single machine if each container uses distinct volume mount names.
{% endhint %}
{% endstep %}

{% step %}

### Join the Server with the Enrollment Key

Once your devices are added to the network, you will see them in two places: within the Devices interface and in the Nodes interface of your network.

![](/files/TWGdGanoMDD3BHdscSKm) ![](/files/LH2K4KBNP6du9HgW82eg)
{% endstep %}
{% endstepper %}

Hosts that are **already** enrolled with your server can be added and removed from Networks without using a Key — see “Managing Existing Hosts” (below) for details.

After devices are enrolled, the key no longer serves a purpose, and can be deleted if so desired, to prevent other devices from joining the network.

## Managing Nodes

Nodes added to your server can be managed by an administrator. You can edit things like the private IP, the public Endpoint (how other machines reach the device), and MTU. The netclient sets these settings automatically, which can be overridden if necessary. For instance, a device may have two public IPs and you might want to specify which one to use. A device may also be in a high-speed network, where a higher MTU will optimize performance.

### Global vs. Network Scope

Devices have two different “Scopes”: the Network scope and the Global scope. When you go to your network, you will see your device and can edit certain network-specific settings, or remove it from the network.

![](/files/Pq6AojOm5TSsFJ6x4ulq)

If you go to the Devices page in the sidebar, you will see all of the devices on the server, regardless of network, and can edit global settings, such as the port the device uses for the VPN.

A Device will only have one network interface locally and use a single IP and port, even if it is in multiple networks. The agent maintains segmentation between networks, so traffic is not sent where it should not be.

![](/files/s18rj2OLASHCle4AMqXK)

### Network Access Management

Within the Device interface, you can also choose which networks a node is a part of. Simply click to add and remove the host from any networks.

A node will have a different virtual IP for each network it is in.

![](/files/x3C6Biiv98LKJrvDDtkY)

## Notes on Deploying Config Files

While adding nodes to your network, you may find that some devices do not support the Netclient. For such devices, we need to use Config Files. These files are standard WireGuard configurations, and have static access to the network via the Gateway to which they are attached.

![](/files/aTjOFn4SD5bXtzEVSGWY)

Important considerations for Config files:

* These are static files and do not update automatically when the network changes.
* When created, these files include the currently available network resources.
* If you add or remove an Egress range,  the files must be re-generated to include them.

Typically, you will want to create these files after you’ve configured all gateways and egress ranges for the network, to avoid having to recreate them.

## Next Steps

Once nodes are added to the network, it is time to configure them with their various network operations. Some nodes may be just endpoints you wish to access, in which case you’re done. Other nodes may need to act as gateways or egress in order to route traffic - See the next section for configuring these networking functions.


# Giving the Netclient Networking Functions

## Overview

Now that you have added Nodes to your server and appropriate networks, it is time to configure the nodes that require specific network functions. We’ll walk through all the various network functions you may wish to set up here.

Keep in mind that a single Node can serve multiple functions. A single Node can be a Gateway that serves both User and Config File Traffic, Auto-Relays traffic between Netclients, and also configured with Egress to subnet ranges, or configured as an Internet Gateway. It will all come down to your scenario and topology.

## The Default Endpoint

For SaaS, a Managed Endpoint is included, which can serve many of these purposes when you don’t know what to use. For On-Prem, a Node is deployed on the server which can serve the same purpose.

Consider this your default endpoint for routing. There are reasons to choose Nodes in other locations (latency, redundancy, access restrictions), but the default endpoint is a good place to get started. It will already be set as a Gateway, which will serve several purposes:

* Auto Relay: Provides higher availability for connections, acting as a fallback when peer-to-peer connections fail.
* User Traffic: The default endpoint is ideal to serve as an entrypoint for user traffic, because the Netmaker server is typically deployed in a way where the endpoint will be easily accessible globally.
* WireGuard Config files: For a similar reason, the default endpoint works well for generating config files, if necessary.
* Static Relay: if you notice a Node with reachability issues, using the default endpoint as a Relay for this host is a good idea.
* Internet Access: If you're looking to set up a simple full tunnel VPN, you can use the default endpoint, editing its Gateway settings to make it an "Internet Gateway".

## Required Configurations by Topology

If you are looking to generate a specific topology, there are related functionalities you will need to give your Netclients.

### Peer-to-Peer

By default, Nodes form a peer-to-peer network with each other. Any machine with the Netclient deployed should have direct access to the other machines with the Netclient deployed. For certain networks, this may be all you need — for instance, if you have some devices in various, scattered networks which need to communicate with each other over a secure channel.

### Hub-And-Spoke

You may want some, or all, of your Nodes to communicate via a “Hub”, e.g. a Gateway. For instance, if operating in a restricted environment, or for data security reasons. This can be done by setting a Node as a Gateway, and selecting which other Nodes it will manage traffic for.

### Full-Tunnel

To create a Full-Tunnel VPN, set a Gateway as an Internet Gateway, and select which Nodes it will forward traffic for. Users and Config Files that use the gateway will also by default have their internet traffic routed through the device.

### Remote Access

For accessing remote environments like office LANs or cloud VPCs, you will most likely use two Nodes: one (or more) acting as the Gateways, and one (or more) acting as a Egress to the local network(s).

### Site-to-Site

If you would like to forward traffic between two or more local networks, such as offices or data centers, this can be accomplished via two distinct methods. The configuration for each is very different:

{% stepper %}
{% step %}

### Nodes with Egress

Deploy a Node in each Site, and set it as a Egress to the local network. Then configure forwarding rules (router configuration or other method) so that local devices push traffic destined for the other sites via the local Node. For example, you could change the default gateway in the local network to use the Node.
{% endstep %}

{% step %}

### Config Files with Egress

A single Gateway can serve as the “Hub” of a Hub-and-Spoke shaped site-to-site network. For each site, generate a WireGuard config file and specify the Egress ranges. Apply the config file to a router at each local site; traffic between the sites will then flow through the Gateway and out to the other sites via WireGuard.
{% endstep %}
{% endstepper %}

## Gateway Setup

In most scenarios, you are going to want one or more Gateways. The Gateway serves two purposes:

* **The Access Point for the Users:** Users, when they log into the VPN, will connect via a Gateway. Users can manually select a Gateway, or simply connect, and the fastest Gateway will be selected automatically. In a global deployment, you will want to deploy multiple Gateways in different regions for optimal performance.
* **A Gateway for Static WireGuard Configuration Files:** The Gateway allows you to create and manage WireGuard config files which can be applied directly to devices. If you wish to add a router or IoT device to your network which cannot run the netclient, generate a WireGuard config file and apply it to the device. Access to and from the device will then go through the Gateway.
* **A Relay between Netclients:** Netclients (Nodes) can be assigned to a Gateway, in which case their traffic will route via the Gateway. There is also an Auto Relay feature of the Gateway, which will do this automatically in the case of connection failure.
* **A Gateway to the Internet:** By toggling on the Internet Gateway feature of the Gateway, it will forward all connected traffic (which does not have a destination inside the VPN) out to the internet.

![](/files/SpFwBnS8tU3iF8xCd9E7)

### Configuring the Remote Access Gateway

Setting a Node as a Gateway is simple. Go to the “Gateways” tab of your network, and create a Gateway from an existing Node. A few considerations:

{% stepper %}
{% step %}
The Gateway must be deployed on a Linux host (or docker container).
{% endstep %}

{% step %}
The Gateway should be accessible by all remote devices which will use it — typically meaning it is in a public environment (cloud) or has appropriate routing set up for the IP and Port of the netclient.
{% endstep %}

{% step %}
The Gateway should be stable: ideally a dedicated, static IP address (not floating), consistent Port, no NAT restrictions, and not on a workstation or device which may turn off easily.
{% endstep %}
{% endstepper %}

![](/files/Rd9Yx9wsndXd3OP6G9im)

Once the gateway is created, config files and users can be added. Both will be discussed in later sections of the guide.

## Egress

For a typical remote access scenario, you will want one or more Egress routes. The Egress functionality forwards traffic via specified nodes to specified external IP addresses in a remote network (for example, an office LAN, cloud VPC, or edge site). Multiple Egress ranges can be configured per-network, and multiple Nodes can act as Egress for the same route, to provide redundancy and high availability. The fastest route will always be selected.

A more advanced use case is to use Egress to configure site-to-site traffic. However, local devices must be configured to forward traffic via the local node, so routes must be configured on the local network after egress is deployed.

### Configuring Egress

Like the Gateway, a Egress must be configured on Netclients running in Linux or Docker.

To configure: go to the Egress tab, click create, and specify the routes. Then add the devices which will forward the traffic. The specified nodes will begin forwarding traffic from the VPN network to the specified ranges automatically.

### Setting Up Site-to-Site with Egress

Egress makes local networks accessible from the VPN. But to make local networks reach the VPN or each other, these routes must be advertised on the local network, to tell those devices to route the remote network CIDRs via the local egress node.

**Example scenario:**

* Netmaker VPN: 100.10.10.0/24
* Cloud VPC: 172.98.52.0/24
  * Netclient with Egress deployed
* Office LAN: 192.20.0.0/16
  * Netclient with Egress deployed on 192.20.10.15

Assume you want the Office Lan to reach the Cloud VPC and the Netmaker VPN. You must advertise routes on the LAN so that devices route both 100.10.10.0/24 and 172.98.52.0/24 via 192.20.10.15. This can be done on the local firewall or a variety of other methods.

After this, the egress node will forward requests to the remote networks from the local devices.

## Next Steps

In the next section, we’ll discuss static clients, where you might use them, and how to add them to your network to fill in any remaining gaps before granting users access to the network.


# Deploying Static WireGuard

## Overview

Your network is now configured with Nodes acting as Endpoints, Gateways, and Egress. Before we move on to adding Users to your network, let’s take care of any of the devices which are not user-managed, and do not support the Netclient, using WireGuard Configuration Files.

These static WireGuard configuration files will allow you to add devices to your network such as Routers and other non-standard devices. They can also be used to run a privileged, always-on VPN on user devices, which is managed by administrators.

There are three primary reasons you may want to use Static Clients with your network:

### Admin-Managed, Always On VPN for User Devices

The User Apps are typically used to give users access to the VPN. However, this client requires user authentication to run. You may find yourself in a situation where you want the VPN to run every time the device is booted, and be unaccessible to the user. Perhaps you are configuring fresh user workstations with VPN access which should be “always-on.” This is a good use case for configuration files.

### Site-to-Site Connectivity via Routers

There are other ways to configure site-to-site connectivity with Netmaker, but one easy way is to utilize the WireGuard plugins which are supported on a large number of Routers today. You can generate a configuration file, configure them with additional routes (for the local network behind the router), and apply the configuration to routers via the supported plugin, to give full access between the site and the VPN.

### Integrate Non-Native Devices

The Netclient runs on Windows, Linux, and Mac. The User Apps runs on all of these plus Android and iOS. For everything else, there’s the static WireGuard config, which can be run on anything that supports WireGuard, from routers to IoT.

## Limitations of Static WireGuard Files

The Netclient dynamically updates and receives information about peers in the network. When using a static configuration file, it cannot receive any updates, and thus has some limitations.

### Static Configuration

The primary limitation of the static config file is that it is static. It will have routes for everything that exists at the time it is generated, including the whole VPN network range. So new VPN endpoints will be accessible. However, if you generate an Egress or Internet Gateway, config files will need to be re-generated. Also, if your Gateway changes its public key or endpoint, the files will stop working, which is why it is important for Gateways to have a static IP.

Using the API and some automation tools can help alleviate this problem, which we will discuss later on.

### Hub-And-Spoke Architecture

An additional limitation is that access to and from the network from these static endpoints go through a Gateway. There will always be an extra hop for connections, which can reduce the network speed and produce a bottleneck for traffic. However, this comes at the advantage of higher connectivity and consistency.

## Generating Config Files

Config files can be generated through the Netmaker UI, or **over API (see How to Guide)**. After generating these client configurations, they can be imported and used on any operating system that supports WireGuard, including Windows, MacOS, Linux, Android, BSD, iOS and many router operating systems.

{% stepper %}
{% step %}

### Add a new node

![](/files/vArRy42KYSffxzwRqzoL)
{% endstep %}

{% step %}

### Choose the config files option, specify the node name, and select your gateway

![](/files/8bAD3H8VhlJosgcHwtJm)

Even if your node is not configured as a Gateway in the gateway list, it will be automatically created during this process.
{% endstep %}

{% step %}

### Select Config files filter and download the WireGuard config file

Click on your WG config file to download the WG configuration you created for the target device.

![](/files/QTQnr3zn36rIjhb1uyLi)
{% endstep %}

{% step %}

### Run the WireGuard configuration on the target device

Follow platform-specific instructions below to apply the configuration.
{% endstep %}
{% endstepper %}

## Client Settings

When creating a client, the dialog box presents some optional fields you may wish to set:

![](/files/f494c4b491fda7413c17da77e492905b998b169a)

* Client ID - an identifier for the config.
* Public Key - You may generate a public/private keypair locally, and specify the public key here. This will allow you to keep the private key off the server, which will enhance security. However, you will need to store and paste in the private key into the configuration file after download.
* DNS - This overrides whatever is set as the default Gateway DNS server, and will be applied as the DNS settings for the VPN tunnel.
* Egress - This field can be used to create your own egress from a static file. Other peers in the network will be told that this static file will route traffic for these addresses. In the above picture we have added two routes for “192.168.5.0/24” and “10.10.10.0.0/16.” This is advertised to all the peers in the network, and they will attempt to send traffic to these addresses via the static client.

  Note: Y will have to manually configure the device to forward traffic. However, you can also set this in the PostUp and PostDown commands.
* Post Up and Post Down — The “Post Up” and “Post Down” fields are commands that get run locally by WireGuard when the interface is brought up (Post Up) and down (Post Down). This can be useful for setting routing or firewall rules on the device whenever the interface is created and destroyed. In our example, we have added an iptables firewall command to allow all ssh connections originating from the netmaker interface when the WireGuard tunnel is alive.

### Viewing and Downloading the Config File

After generation, the configuration file can be viewed or downloaded by clicking the client id in the UI and then the “View/Download config” button. This will show the client’s full WireGuard configuration and it will also provide a handy QR code to scan and import the configuration file on mobile devices.

![](/files/f32494272d302c8b4b7c60db0e36eb674611253e)

## Applying to Devices

The generated static client configuration files can be used in various different platforms and operating systems. These files can be applied to any device that supports WireGuard. However, depending on the system, you may not be able to import or run the file directly. Instead, you may need to set up a tunnel, using the settings presented in the config file.

The steps to apply WireGuard here are exactly the same as you would to set up any WireGuard tunnel. These config files are just valid WireGuard tunnel parameters, which will add it to the network. Below, we provide some generic instructions on how to do this, but again, searching for any instructions to set up WireGuard on your device will work. Just use the settings from the configuration file.

### Install WireGuard

First, WireGuard must be installed on the target platform.

To install WireGuard, follow the official WireGuard installation link, and find instructions for your target device: <https://www.wireguard.com/install>

### Apply Configuration via WireGuard GUI (Windows)

On Windows, you’ll get a GUI application to import WireGuard files.

![](/files/2b5cb3c0f7c3995e27e1a06d7ad91eca3a085aae)

Click the Import Tunnels button, and select the config file (If you have not done so already the config file must be downloaded or transferred to the target device).

![](/files/718b925fa55615219bf473494fda9680399c0ad5)

After importing the static client configuration file, click the Activate button to make the tunnel active.

![](/files/21acb90bd43cfe0f5dd9cde61212fa2165fcc62e)

If successful, it will show an “Active” status alongside some additional information such as the connection handshake status and total data transfer amount, which can help verify the connection is working.

![](/files/582ce4a9ac7ee31cdc925e20f8f79111e3f15599)

Now this device can reach any other nodes in the network through the Gateway node.

The windows terminal can be used to check all the WireGuard interfaces and tunnels and can also be used to configure custom interfaces. Open up Windows terminal app, then type wg and press enter to show all the WireGuard interfaces and peers configuration.

![](/files/bf31c29f13e6cda0aef67938494f737dc46c1118)

### Apply Configuration via wg-quick — Linux, macOS, and Others

wg-quick is the easiest tool to get a tunnel active on Linux and macOS (as well as some other operating systems), and is included in the wireguard-tools package.

{% stepper %}
{% step %}

### Place the config file on the device

Download, transfer, or copy/paste the config file to the device.
{% endstep %}

{% step %}

### Bring the tunnel up

Run:

{% code title="Bring up tunnel" %}

```bash
wg-quick up ./path/to/config.conf
```

{% endcode %}

This will configure and bring up the WireGuard interface. Use the wg command to verify the interface.
{% endstep %}
{% endstepper %}

It will show the handshake and other statistics of the WireGuard interface upon successful connection. Similarly you can bring down the connection with:

{% code title="Bring down tunnel" %}

```bash
wg-quick down ./wg.conf
```

{% endcode %}

![](/files/53708cee86671c3857bfa52f7bfb4c288948fa3f)

### Always On-VPN for Windows Devices

Using PowerShell, an always-on VPN tunnel can be created for user devices. Open Windows Terminal and run:

{% code title="Install tunnel service" %}

```powershell
wireguard.exe /installtunnelservice "C:\\Users\\%USERNAME%\\Downloads\\test\\SiteA.conf"
```

{% endcode %}

This creates a system service for handling the tunnel so the adapter survives reboots and automatically reconnects.

## Next Steps

Now that we have all of our devices deployed, lets discuss setting up DNS and Access Controls, which will complete the formation of our topology.


# DNS

Netmaker's DNS is a powerful system utilizing both an internal resolution system, and the ability to integrate additional private and public nameservers with match domains.

If utilizing Egress, you will likely want to include your own DNS servers, making the local site's DNS available over the VPN.

If utilizing the Internet Gateway, you will likely want to include a public DNS server, so that DNS requests go through the Gateway.

Other than this, you can define any custom DNS entries you would like, to any resource both inside or outside the network.

Learn more about how to manage DNS with the following resources.

{% content-ref url="/pages/eb8e4b35aaf4f2e54a5c40bd19dee782100b9388" %}
[DNS](/features/dns)
{% endcontent-ref %}

{% content-ref url="/pages/0CiQckqWWzTps6th7Q1Y" %}
[How to Set DNS](/getting-started/walkthrough/how-to-set-dns)
{% endcontent-ref %}

## Next Steps

Lets next touch on Access Controls. We will use Access Controls later on for user access as well, but they may also be necessary for your devices.


# Access Controls - ACLs

Access Controls (ACLs) are a powerful component of the Netmaker platform, which give Zero Trust functionalities, determining which resources have access to which other resources, on specified ports and IPs, as well as defining directionality.

If you have deployed multiple use cases within a single network, you will want to use Access Controls to segment these use cases.

For example, if you have defined remote access to multiple sites, different groups of users might need access to only one of those sites, and should not have access to the others. This can be managed with Access Controls.

You can learn more about configuring ACLs in the following documentation.

{% content-ref url="/pages/4a837ecb1ded1e8e068932cda021b360b01fc9c6" %}
[ACLs - Access Controls](/features/acls-access-controls)
{% endcontent-ref %}

{% content-ref url="/pages/5J0GVggi06EWWuAb3UbC" %}
[How to Manage Access Controls - ACLs](/getting-started/walkthrough/how-to-manage-access-controls-acls)
{% endcontent-ref %}

## Next Steps

We did not mention configuring Routers in the previous sections, which we will cover in the next. We'll will walk through setting up site-to-site connectivity using Netmaker. There are two primary approaches to this, using WireGuard configuration files, or using the Netclient.


# Site-to-Site and Routers

## Overview

In this section we will give an overview of how to integrate routers into your Netmaker network, in order to create site-to-site connectivity. We will discuss two methods using Netmaker:

* Using WireGuard Configuration Files and applying them to Routers
* Using the Netclient, Egress, and additional routes in the local network

The first approach creates a hub-and-spoke site-to-site network, where traffic passes through a “hub” before reaching other sites. The second approach gives direct site-to-site connectivity, creating a peer-to-peer network of routers.

## Using Config Files On the Router

Following the previous sections, you should be familiar with Gateway and how to add Egress to a config file.

For our example we will assume you have two sites, Site A and Site B, which need to be connected.

{% stepper %}
{% step %}

### Create Static Config Files

* Press the “Create Config” button and use the value “SiteA” in the “Client ID” field to uniquely identify the static client configuration for SiteA.
* Add the network address with subnet for the SiteA local network in the “Egress” field so that other peers (SiteB) will be able to reach those network addresses and access relevant resources.
* Set a DNS server address which is hosted inside the SiteA network for internal hostname resolution.

![](/files/OR4KahW9fsrgRWAl4tsB)
{% endstep %}

{% step %}

### Repeat for SiteB

* Repeat the same steps to add SiteB with the “Client ID” of SiteB.
* In the “Egress” field, add the network subnet of the SiteB local network.

![](/files/a6eadbd1cb68618c1f9c2b3774d5caa24fec9268)
{% endstep %}

{% step %}

### Apply Configs to Routers

Apply the generated configuration files to the routers at each site.

![](/files/f2d558849e3b749045ac36b70ff6514b1fa01f7b)

Below are example steps for MikroTik RouterOS. Steps differ by router vendor, but generally you will need to:

* Install the WireGuard plugin.
* Create a WireGuard interface using the config file.
* Add routes so the local site can access the other site.

**Note:** In many router WireGuard plugins you will need to manually enter the information from your configuration file rather than uploading it directly.
{% endstep %}
{% endstepper %}

### Adding the WireGuard Interface (MikroTik example)

{% stepper %}
{% step %}

### Create the WireGuard Interface

1. Go to the WireGuard section.
2. Click Add New.
3. Give an interface name (any will do).
4. Add the private key from the config file.
5. Hit Apply/OK.

![](/files/82ea188c33f204f8305a86a1998bff2b1306d912) ![](/files/0486229950bea04ddd8b1f83df2eeaa278813198)
{% endstep %}

{% step %}

### Add Peer Information

1. Go to Peers.
2. Add the Peer information from the config file.
3. Apply it to the interface created above.
4. Click Apply/OK.

![](/files/fbf424dd63a20c3f520e8fb8b26a13ce89905bf3) ![](/files/f104144731a67a75edceba67ee3669155d409a14)
{% endstep %}
{% endstepper %}

### Add Routes on the Router

You need to add routes to advertise the newly available networks to devices on the local network.

{% stepper %}
{% step %}

#### Go to IP -> Routes.

{% endstep %}

{% step %}

#### Click “Add New”

{% endstep %}

{% step %}

#### Type the name of the new WireGuard interface (include a % prefix).

{% endstep %}

{% step %}

#### Enter the allowed IP address range in the “Dst. Address” field.

![](/files/3fae9c075c34b7ec03b104a872f0f0e9ea2578ce)
{% endstep %}

{% step %}

#### Press “Apply” and then “OK” to save the route.

{% endstep %}

{% step %}

#### For multiple allowed IP address ranges, create multiple routes following the same procedure.

{% endstep %}
{% endstepper %}

Follow these same steps on the Site B router, and the two sites should be able to begin communicating over the VPN.

## Direct Site-to-Site with Netclient

The static procedure above is straightforward and works directly with routers. However, it creates a hub-and-spoke network and managing static WireGuard files can be problematic when updating or adding sites.

An alternative is using Netclient (peer-to-peer mesh). Below are the main considerations and steps.

### Ensure Non-Overlapping Networks

Local networks at different sites must not overlap. For example:

* Two sites both using 192.168.1.0/24 will not work.
* One site using 192.168.1.0/24 and another using 192.168.0.0/16 will cause issues.

Use distinct ranges like 192.168.1.0/24 for SiteA and 192.168.2.0/24 for SiteB.

### Install Netclient at Sites

Install Netclient on one Linux machine at each site. Recommended options: dedicated Linux server, VM, or Docker container. These machines should typically be behind a router on the LAN or in the DMZ. In a VPC without gateways/routers, choose a machine with direct internet access.

### Set Up Egress

Designate the machines with Netclient as Egress using the Netmaker web UI.

![](/files/f9b702fca6c6f18df5da07cf7bdc036d485ccb64)

Click “Add external route” to expose the whole or part of the site’s private network by specifying the network ranges in the “external ranges” field.

![](/files/8c39a8b7ecd95d587e86b63bbb2499e1d1ba607e)

Then press “Update Egress” to save the external routes.

At this point you have dedicated egress capable of forwarding traffic to/from the network over the VPN. However, local devices still need to know how to reach the Egress Gateway — choose one of the three methods below:

* For No Router or No Gateway Environments (like VPCs)
* For NAT Router Environments using the Virtual Router Method
* For NAT Router Environments using the Static Routing Method

### For No Router or No Gateway Environments (Like VPCs)

Some VPCs do not expose a centralized gateway/router for managing routes. Capabilities vary by cloud provider.

#### How to implement

{% stepper %}
{% step %}

1. Enable "NAT for egress traffic" on the Egress to allow incoming traffic from other sites.
   {% endstep %}

{% step %}
2\. If your VPC allows it, add static routes for:

* every remote site,
* the Netmaker network,
* all other egress ranges and external client address ranges.

Route all this traffic through the local network address of the Egress. Maintain these routes—changes to VPN settings require manual updates to these routes.
{% endstep %}

{% step %}
3\. If the VPC does not allow VPC-level routes, add identical static routes to each machine in your VPC that needs connectivity to the other sites.
{% endstep %}
{% endstepper %}

### For NAT Router Environments Using the Virtual Router Method

In this method, machines that need to access other sites use the Egress Node as their default gateway. The Egress Node forwards Internet traffic to the router and VPN traffic to the Netmaker tunnel.

Key traffic flows:

* Site-to-site: Site1EgressRange1 → Site1EgressNode → tunnel → Site2EgressNode → Site2EgressRange2
* Internet from egress range: EgressRange → EgressNode → Router → Internet
* Devices not in VPN use Router → Internet

How to implement:

{% stepper %}
{% step %}

1. Ensure the default gateway on each client machine is set to the Egress Node.
   {% endstep %}

{% step %}
2\. Disable "NAT for egress traffic" on the Egress Gateway.
{% endstep %}
{% endstepper %}

Advantages:

* Easy to implement.
* No need to add/maintain static routes.
* Fewer hops; source IPs preserved.
* Tunnel traffic is faster than the Static Route method.

Disadvantages and workarounds:

* DHCP setup may be tricky since resources can point to two potential gateways; use VLANs to separate resources.
* Egress Node may get overloaded—use link aggregation to increase bandwidth.
* Manually set network settings if router/switch doesn’t support VLAN or external DHCP.

### For NAT Router Environments Using the Static Routing Method

This method adds and maintains static routes on the site router. Client devices keep the router as their default gateway; the router forwards VPN-bound traffic to the Egress Gateway.

Key traffic flows:

* Incoming VPN traffic: Site1-EgressNode → Client
* Outgoing VPN traffic: Client → Router → Site1-EgressNode → tunnel → remote site
* In physical terms: Site2Client → Site2Router → Site2-EgressNode → tunnel → Site1Router → Site1-EgressNode → Site1Client

How to implement:

{% stepper %}
{% step %}

1. Enable "NAT for egress traffic" on the Egress Node to allow incoming traffic from other sites.
   {% endstep %}

{% step %}
2\. On each site’s router, add static routes for:

* every remote site,
* the Netmaker network,
* all other egress ranges and external client address ranges.

Route this traffic through the local network address of the Egress Node. Maintain these routes as VPN settings change.
{% endstep %}
{% endstepper %}

Note: If you use management software for local devices, you can push these routes to each machine via the Egress Node.

Advantages:

* Seamless integration.
* All internet traffic goes through the router.
* No extra DHCP configuration needed.

Disadvantages and workarounds:

* Need to constantly add/maintain static routes—use management software to push routes via the Egress Gateway.
* Additional network hop per site.
* Source IPs aren’t preserved.
* Slower than the Virtual Router method.

### ISP Failover

For multiple ISP links, let the router, firewall appliance, or manageable switch handle internet load balancing and failover. Refer to your device manual for configuration. Expect momentary connection breakage during failover; Netmaker should handle public IP changes similar to dynamic public IPs.

{% hint style="info" %}
If you see references to a “NOTE” in other docs, ensure you follow any special considerations or warnings for your environment (for instance, DHCP or route persistence) when implementing these methods.
{% endhint %}

## Next Steps

By this point, your networking infrastructure should be configured. You can now set up access for your users.


# Granting Access to Your VPN

## Overview

Now that you’ve set up your network, it’s time to invite users to begin using it. Netmaker’s User Management streamlines the process of inviting users, setting roles and permissions on the platform, and granting access to your VPN.

Users can be granted a role that gives them access to the platform, to directly manage networks, or access to the VPN, at particular points of entry.

In this section of the guide, we’ll cover how to invite users and grant them access to the VPN. For a full overview to invite other platform administrators and set other sorts of users, check out the full documentation.

## Roles

Permissions on Netmaker are either server-wide, or network-specific. For instance, you can make someone an Admin of the platform, or a Network Admin, to manage a specific network.

### Platform Roles (Server-wide access level)

Platform-level roles in Netmaker Professional are a mechanism to define user permissions across the entire platform, rather than on a per-network basis. They determine a user's overall access level and capabilities.

Here's a breakdown of platform roles and their associated capabilities.

#### Super Admin

* Highest level of privilege. Considered the “platform owner”
* Complete control over the platform: Can manage all users, networks, configurations, and system settings.

#### Admin

* A “platform manager” with most privileges.
* Does not need to be assigned groups or network roles since they have full access.

#### Auditor

* A “platform auditor” with view-only permissions of your networks

#### Platform User

* Limited access to the platform.
* Can interact with assigned resources and perform specific tasks.
* Must be added to a group or given network roles to have any platform or network access.
* In the context of VPN access, can be used to grant the ability to deploy the netclient (typically should be a network administrator) or to deploy static config files.

#### Service User

* Meant for “VPN Users”
* No Platform access
* Primarily used for remote access via the RAC application.
* Must be added to a group or given network roles to have any network access

For the purposes of this guide we’re concerned with Platform Users and Service Users, and how to grant them access to deploy VPN endpoints.

## Groups

Groups are a collection of users and network roles. It makes permissioning easier since, rather than granting the same network roles to every new user, you can just add them to a group.

{% stepper %}
{% step %}

### Create a Group

Define a group based on criteria such as department, role, or project.
{% endstep %}

{% step %}

### Add Roles

Add roles to the group that define its permissions.
{% endstep %}

{% step %}

### Add Users

Add the relevant users, and they will inherit the permissions.

A user can be in multiple groups, and the inherited permissions are additive.
{% endstep %}
{% endstepper %}

### Default Groups

There are some pre-defined groups that you can assign to users, to simplify setup:

* **(network name)-network-admin-grp:** Contains the network role **-network-admin** and grants admin privileges on the network.
* **(network name)-network-user-grp:** Contains the network role **-network-user** and grants end user access to the network

## Network Resource Access Control with ACL Policies

Use the defined groups to determine who can access what within Netmaker's Access Controls. To learn more about this, check out the related documentation.

{% content-ref url="/pages/5J0GVggi06EWWuAb3UbC" %}
[How to Manage Access Controls - ACLs](/getting-started/walkthrough/how-to-manage-access-controls-acls)
{% endcontent-ref %}

## Authentication Options

Users can either be created with a username and password (Basic Auth) or Invited, allowing them to log in with an authentication provider like Google, Microsoft, Okta, or others. Note, on SaaS, you must use the provided options, and with On-Prem, you must first set up OAuth integration.

**Basic Auth:** Users are created with a password, and managed directly by admins within the Netmaker platform. This is not available on SaaS.

**OAuth:** Users are invited to the Netmaker server via email, and log in using the integrated authentication mechanism.

Note, users can also be invited via email, and set a username/password, to allow invitation, but still use basic auth.

## Adding and Inviting Users

#### Setting up Email Notifications On-Prem

Netmaker On-Prem will only send email notifications to any invited user if it is configured to do so. Check our [documentation](/getting-started/server-and-client-management/server-installation/advanced-options#setting-a-netmaker-server-up-for-emailing) on how to configure email notifications.

### Inviting Users via Email

{% stepper %}
{% step %}

### Open Invite Flow

In the user management page, click on Add a User > Invite User
{% endstep %}

{% step %}

### Enter Email and Select Access Level

Enter the admin email address(es) and select “Platform User” or “Service User” as Platform Access Level.

![](/files/N3yjf3um1wprgS5Q8QGz)

Notes:

* If users should only have access to the RAC (the usual option) they should be Service Users.
* If they need access to the dashboard to, for instance, create and download their own config files, make them Platform Users.
  {% endstep %}

{% step %}

### Assign Groups

Select between “Groups” to assign access.

![](/files/uO8M43qcqASqrbI1AXSL)
{% endstep %}

{% step %}

### Create Invite(s)

Click on “Create User invite(s)”. The user(s) will get notified through the entered email address(es).
{% endstep %}
{% endstepper %}

### Creating Users via Basic Auth

{% stepper %}
{% step %}

### Open Create User Flow

In the user management page, click on Add a User > Add a User

![](/files/oILGD8FZbKaXHmkgt8QX)
{% endstep %}

{% step %}

### Provide Credentials

Provide a username and initial password for the user.

![](/files/m0XXDvuF4sa1Ajq8nV8T)
{% endstep %}

{% step %}

### Select Platform Access Level

Select a Platform Access Level.
{% endstep %}

{% step %}

### Specify Permissions

Specify permissions if necessary (same as the invite process above).
{% endstep %}

{% step %}

### Create User

Click on “Create User” and share the credentials with the intended user for them to log in.
{% endstep %}
{% endstepper %}

#### Updating User Permissions

{% stepper %}
{% step %}

### Open User

Click on a username.

![](/files/S738itHoiTe1cONSnr1V)
{% endstep %}

{% step %}

### Update Permissions

Update the user’s permissions.

![](/files/3TvDoHY6QV8y7wSgOluT)
{% endstep %}

{% step %}

### Save

Click on “Update User” to save.
{% endstep %}
{% endstepper %}

## Next Steps

Now that users have been added to the VPN, we will show you how they will access the VPN as end users.


# Accessing the VPN as an End User

## Overview

Once you have configured access to the platform for users, your users will need to join. Here are some simple steps for how users accept an invite, download, install, and use the VPN client: Netmaker Desktop and Mobile

## Accepting an Invite

Users who have been invited to the platform will be sent an email with an invite link, if email is configured. If not, you must manually provide them with the invite link.

Once they click the link, they will see a registration page allowing them to sign up with SSO (Social Sign On) or by setting a password.

![](/files/78cdfdd37373aa58cddfa4459f3cba60edf6477d)

## Downloading and Installing the Netmaker Desktop

After signing up, the user should download and install the Netmaker Desktop.

{% stepper %}
{% step %}

### Download the installer

Download the platform-specific installer from:\
<https://www.netmaker.io/download>

![](/files/FQRETIX1IoIxUMUXKAGK)
{% endstep %}

{% step %}

### Install the application

Follow the installation instructions from the bundler.

![](/files/pQeIrNbYVWMloFsFYmVN)
{% endstep %}

{% step %}

### Virtual Machine prerequisite

{% hint style="info" %}
If installing on a Virtual Machine, include the “Mesa Dependency” package while installing.
{% endhint %}

![](/files/ciujp54vgGJHTwaYjftk)
{% endstep %}

{% step %}

### Finalize installation

On successful installation, press the “Finish” button to finalize and close the installer.

![](/files/bZ8tasXbgsNY7TnrXP26)

After that, users can search for “Netmaker Desktop” and open the application.

![](/files/W2twg7Ngo1mPv4KJNWGn)
{% endstep %}
{% endstepper %}

## Logging In

To log in, a user will need to specify the netmaker server, and enter their credentials.

### Specify Server

The application needs to know which server it is logging into.

* On Prem: For On-Prem installations, this will be the API URL, which usually looks like api.
* SaaS: For SaaS accounts, this will be the “Tenant ID”, which should be included in the email invite, and can be seen when logging into [account.netmaker.io](http://account.netmaker.io/) under tenant management.

![](/files/ZDHvb43zR2Jo8aC7vZQv)

### Enter Credentials

* Basic Auth: For basic auth users, they will enter their username and password.
* OAuth: To log in using OAuth (SSO), click the “Login with OAuth” button and then go through the provider’s login process.

![](/files/59YwezC6CrM5NjCfbDH6)

Note: If this is a new registration, the admin of the netmaker server or the netmaker SaaS tenant will be notified of the new user request which needs to be manually approved by the admin, under Pending Users.

<figure><img src="/files/25xwZI44Mu3gwp05SfUD" alt=""><figcaption></figcaption></figure>

### Connecting to the VPN <a href="#connecting-to-the-vpn" id="connecting-to-the-vpn"></a>

After logging in, users will see the networks and gateways for which they have been granted access.

#### Gateway Information <a href="#connecting-to-the-vpn__gateway-information" id="connecting-to-the-vpn__gateway-information"></a>

Hover over the information icon to view gateway details.

<figure><img src="/files/PIi8awLf0pnFWXhVHijQ" alt=""><figcaption></figcaption></figure>

#### Connecting/Disconnecting <a href="#connecting-to-the-vpn__connectingdisconnecting" id="connecting-to-the-vpn__connectingdisconnecting"></a>

Use the toggle switch to connect or disconnect from a specific gateway and access the network.

Press the Refresh icon to refresh a connection.

<figure><img src="/files/iKLpptAWFpkeu9zyv4fQ" alt=""><figcaption></figcaption></figure>

### Admin Visibility <a href="#admin-visibility" id="admin-visibility"></a>

As an admin, you can see active users in your network, if you navigate to the Node interface and click on the “Active Users” filter, you will be able to see users.

<figure><img src="/files/TcYVAWzPLrZqyZLGN9q8" alt=""><figcaption></figcaption></figure>

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### **OAuth Error** <a href="#troubleshooting__oauth-error" id="troubleshooting__oauth-error"></a>

<figure><img src="/files/we20OU9ywlvqqoR8aEe7" alt=""><figcaption></figcaption></figure>

This error is related to the netmaker server not having OAuth setup and enabled. Please request the netmaker server admin to configure and enable OAuth by following the docs at <https://docs.netmaker.io/docs/server-installation/integrating-oauth>

#### **Checking WireGuard** <a href="#troubleshooting__checking-wireguard" id="troubleshooting__checking-wireguard"></a>

To look at the wireguard configuration that has been applied by the Netmaker Desktop, you can simply open up your terminal and use the “wg” command to view the current connection status as shown below.

<figure><img src="/files/sMtcMX5eJQ5Sd3yaO4Mw" alt=""><figcaption></figcaption></figure>

This information can help you diagnose any problems further or simply log the current WireGuard connection status.

#### **Authentication Timeouts and Re-Authenticating** <a href="#troubleshooting__authentication-timeouts-and-re-authenticating" id="troubleshooting__authentication-timeouts-and-re-authenticating"></a>

In the Netmaker standalone server environment configuration file, there are two options to set user authentication token validity duration and auto disable a non-admin user’s remote access upon token expiration. These two configuration variables can be found in the netmaker.env file on a standalone netmaker server as shown below.

<figure><img src="/files/kivM89Xmkp8kYy2SeWVW" alt=""><figcaption></figcaption></figure>

The “**JWT\_VALIDITY\_DURATION**” is responsible for expiring the user authentication token after the **value in seconds**. And if the “**RAC\_AUTO\_DISABLE**” is set to **true**, it will result in authentication timeout and the remote access client user needs to re-authenticate using the rac software for renewing the authentication token and resume normal operation.

### Next Steps <a href="#next-steps" id="next-steps"></a>

Let’s now cover some global troubleshooting, should you run into any trouble while setting up your network.


# Troubleshooting

## Overview

Here are some helpful troubleshooting steps for networking issues you may encounter while setting up your network.

## Netclient Connectivity Issues

On the netclient side, there could be many reasons why connectivity is not working as expected. Below are common troubleshooting steps for netclient connections.

### Verify Netclient Installation

Check that wireguard-tools is installed by running:

```bash
wg
```

<figure><img src="/files/iXfvNH6eV3mRP4dEsGn6" alt=""><figcaption></figcaption></figure>

The response should show the WireGuard interface named `netmaker`. If `wg` is not found, install wireguard-tools:

```bash
sudo apt install wireguard wireguard-tools -y
```

To verify netclient is installed and accessible, run:

```bash
netclient
```

<figure><img src="/files/w5byCl3nz4P27gRqUvfK" alt=""><figcaption></figcaption></figure>

If `netclient` is not found or fails, try reinstalling following the documentation: <https://docs.netmaker.io/docs/netclient#installation>

To verify the netclient daemon is running (Debian-based distros):

```bash
systemctl status netclient
```

The service should be `active (running)`. If it's not, try:

```bash
netclient install
```

If problems persist, uninstall and reinstall:

```bash
netclient uninstall
# then reinstall per docs
```

(Images showing `wg`, `netclient`, and `systemctl status netclient` appear in the original content.)

### Verify Network Connectivity

After joining a netmaker network, verify connectivity with:

```bash
netclient list
netclient server list
wg
```

* `netclient list` shows the network(s) the node joined.
* `netclient server list` shows the server(s) the node joined.
* `wg` lists peers and handshake/byte stats.

If `netclient list` or `netclient server list` show nothing, rejoin with the appropriate enrollment key.

If `wg` shows no peers despite multiple hosts in the network, try syncing:

```bash
netclient pull
```

Common causes for netclient failure to connect to others:

* Unable to establish connection to server over MQTT (failure to receive peer updates).
* Failure to create correct local routes.
* Unable to establish connection via TURN.

Basic troubleshooting steps:

* Run sync from server.
* Run `netclient pull` on the netclient machine.
* Restart the netclient daemon:

```bash
systemctl restart netclient
```

* Check the node status in the Netmaker UI.
* Consider relaying the client through a publicly accessible netclient as a relay server.

If issues persist, inspect logs:

```bash
sudo systemctl status netclient@<network-name>
sudo journalctl -u netclient@<network-name>
# For live logs:
sudo journalctl -u netclient@<network-name> -f
```

(Use the End key to jump to the most recent entries if using a pager.)

### Firewall Blocking Issues

Netclient (WireGuard) nodes must communicate with the server and peers. Firewalls commonly block required traffic by default. Typical rules to allow:

* UDP and TCP ports 51821-51830 (or your custom static ports)
* TCP port 443
* UDP ports 19302 & 3478 (STUN)
* UDP and TCP port 53 for DNS (optional)

Example iptables rule to allow a UDP port range:

```bash
iptables -A INPUT -p udp --dport 51821 -j ACCEPT
```

For UFW logging and inspection:

```bash
ufw logging low
cat /dev/null | sudo tee /var/log/ufw.log
ufw reload
cat /var/log/ufw.log | grep -e <netmaker server IP> -e <other nodes' IPs>
```

On Windows, allow Netclient and WireGuard applications through the firewall via the Windows Firewall settings.

For NAT/firewall appliances, check their blocked logs for traffic to/from your device IPs.

### MTU Issues

If WireGuard handshakes exist but peers are not reachable (cannot ping), MTU is often too high. Lower the MTU on the node via netconfig or by editing the host in the Netmaker UI.

Note: minimum recommended MTU is 1280 (IPv6 minimum and many routers expect standard MTU). Going lower may cause issues.

### Unresponsive Netclient / Segmentation Error

If netclient commands fail with segmentation faults or the daemon is unresponsive, the binary may be corrupted (failed update, interrupted install, OS issue). Reinstall netclient to overwrite the corrupt installation, then re-join the network if necessary.

### Incorrect Endpoint IP

You can set a static endpoint for a device in the Netmaker UI. This also disables endpoint detection if desired.

{% stepper %}
{% step %}

### Access All Devices

Open the All Devices interface in the Netmaker UI.
{% endstep %}

{% step %}

### Select Device

Select the device you want to modify.
{% endstep %}

{% step %}

### Edit Device

Click Edit.
{% endstep %}

{% step %}

### Enable Static Endpoint

Turn on "Static Endpoint".
{% endstep %}

{% step %}

### Set IP

Enter the correct endpoint IP and click "Update Device".
{% endstep %}

{% step %}

### Verify

Return to the Devices interface and confirm the IP has been updated.
{% endstep %}
{% endstepper %}

(Images illustrating the UI steps appear in the original content.)

## Relays

If relayed client traffic is not forwarded by the relay server:

* Ensure relay servers have required ports open and are publicly reachable.
* Run traceroute from relayed client to the destination client to identify where traffic is stopping. On Ubuntu:

```bash
sudo apt install traceroute
traceroute <destination-ip>
```

* If traceroute shows hops then a `*` at the relay server toward the destination, check Linux IP forwarding on the relay:

```bash
echo "net.ipv4.ip_forward = 1" >> /etc/sysctl.conf
sysctl -p
```

* Check the relay server firewall and WAN/VPC rules to ensure forwarding is permitted.
* Ensure netmaker's default iptables rules exist on the relay server:

```bash
iptables -L
```

* Repeat verification (excluding the ip\_forward change) on the target netclient to ensure it can reach the relay and the relay can reach it. Troubleshoot firewall rules on that machine as needed.

## Static WireGuard

For static WireGuard peers that can't reach each other:

* Verify public/private key pairs for both peers.
* Verify endpoint addresses and ports.
* Verify AllowedIPs ranges include intended traffic.
* If handshake exists but ping fails, check MTU (lower it if needed).
* For NAT/restrictive firewalls, set PersistentKeepalive to keep NAT table entries alive.

You can set MTU in the peer config under the \[Interface] section:

```
MTU = <value>
```

Then restart the WireGuard interface.

## Remote Access Gateway and Client

Remote Access Gateways/Clients are static WireGuard configurations for devices that do not run netclient. The same relay and static WireGuard troubleshooting steps apply.

* Ensure "VPN Config Files" specify the correct egress address ranges.
* For Linux egressing external clients, enable IP forwarding and ensure iptables is installed on the gateway.
* Add a POSTROUTING MASQUERADE rule for the egress network interface, for example:

```bash
ip a
# assuming interface eth1
iptables -t nat -I POSTROUTING -o eth1 -j MASQUERADE
```

* The remote access gateway should show external clients as peers in `wg`. If peers are missing:

```bash
netclient pull
wg
```

* If per-peer domain names are used, ensure the gateway's DNS server can resolve those domain names.

## Egress

Netclient egress gateways forward traffic to/from specific IP ranges accessible to the gateway. This uses WireGuard AllowedIPs routing.

"External routes" determine which IP ranges are routed through the egress gateway. Correct configuration is essential.

Common problems:

* No traffic passing through although peer connects to the gateway.
* Only some internal ranges accessible.
* Traffic leaking to local network instead of through the egress.

Potential causes include misconfigured External routes, firewall rules, routing conflicts, or overlapping subnets.

Recommended troubleshooting:

1. Verify External routes / Allowed IPs match intended routing policy:

```bash
wg show netmaker allowed-ips
```

2. Check routing tables on the peer:

```bash
ip route
```

3. Test connectivity by pinging internal IPs and using traceroute to observe paths.
4. Review firewall rules and NAT configuration on the gateway.
5. If you need to preserve original source IPs, disable NAT on the egress gateway (note: this can introduce other issues).

Route conflicts example:

* If a local network 192.168.1.0/24 and a remote network 192.168.1.0/24 are both present, there will be duplicate routes to the same destination via different interfaces. Solutions:

{% stepper %}
{% step %}
Use different route metrics; the lower-metric route is preferred.
{% endstep %}

{% step %}
If only a few hosts must be egressed, add host IPs individually to the egress range rather than the whole network.
{% endstep %}

{% step %}
If many remote hosts but few local hosts, add the remote network to the egress range and add local hosts one-by-one in routes.
{% endstep %}
{% endstepper %}

If another host in the same local network is an egress gateway and the local network is added to the egress range, host route conflicts may occur. Adjust route metrics so the desired interface is preferred.

## Internet Gateway

Internet Gateway works like Egress but with AllowedIPs = 0.0.0.0/0 for selected hosts so all traffic routes through the internet gateway. Use the same troubleshooting steps as Egress (External routes = 0.0.0.0/0).

## Netmaker Server

If Let's Encrypt certificate retrieval fails when installing Netmaker with an auto-generated domain (nip.io), restart the Caddy container to retry:

```bash
docker restart caddy
```

After installation, verify the required containers are up:

```bash
docker ps
```

If containers failed, recreate them:

```bash
docker compose up -d
```

If signup/login to the Netmaker UI fails, you can reset the server (this deletes data and configs):

```bash
docker compose down --volumes
docker compose up -d
```

Then reopen the dashboard and create a new admin account.

If the UI shows an MQ error, restart the MQTT container:

```bash
docker restart mq
```

If restarting the server with docker-compose fails with an error like:

ERROR: Get "<https://registry-1.docker.io/v2/>": dial tcp: lookup registry-1.docker.io on \[::1]:53: read udp \[::1]:...: connection refused

This can occur because CoreDNS was taken down and systemd-resolved is disabled. To resolve:

{% stepper %}
{% step %}
Temporarily start systemd-resolved:

```bash
sudo systemctl start systemd-resolved.service
```

{% endstep %}

{% step %}
Start the netmaker server:

```bash
docker-compose up -d
```

{% endstep %}

{% step %}
Stop and disable systemd-resolved again:

```bash
sudo systemctl stop systemd-resolved.service
sudo systemctl disable systemd-resolved.service
```

{% endstep %}
{% endstepper %}

(Images showing container status and restarting steps appear in the original content.)

***

If you need any of the screenshot images preserved as separate assets for GitBook or want specific commands converted to runnable code blocks, tell me which sections and I will update accordingly.


# Monitoring your Network

## Overview

You probably want to monitor the traffic and connections in your network. There are three primary ways to do this with Netmaker:

{% stepper %}
{% step %}

### The built-in Metrics dashboard

Use the Netmaker web UI (Professional / Enterprise Edition) to view aggregated metrics collected by the netmaker server from netclients.
{% endstep %}

{% step %}

### A Prometheus exporter and a Grafana dashboard template

Export metrics to Prometheus using the netmaker exporter, then visualize with Grafana (dashboard JSON can be imported).
{% endstep %}

{% step %}

### View network data directly on devices using WireGuard features

Use wireguard-tools (wg show) on client systems to inspect per-peer bytes, handshakes, and other WireGuard statistics locally.
{% endstep %}
{% endstepper %}

In this section, we overview how to use these features.

## Monitoring Network Stats with the Metrics Dashboard

The netmaker server collects metrics from netclients and provides aggregated views inside the Netmaker web UI. This feature is available in Netmaker Professional / Enterprise Edition.

Steps to access:

* Log into the Netmaker dashboard.
* Navigate to the specific network from the Networks tab.
* Click the Metrics tab.

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

Available metric pages:

* Connectivity status: overview of which hosts can establish connectivity with each other.

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

* Example: host “centos-userspace” can connect with “ubuntu20-04”; “fedora” cannot connect with “relayed”.

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

* Latency: round-trip time (ms) between hosts (e.g., 149ms between “centos-userspace” and “ubuntu20-04”).

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

* Bytes Sent: amount of data sent from hosts on the left to hosts on the top.

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

* Example: “390.56 MiB” sent from “Ubuntu20-04” to “centos-userspace” (so centos-userspace received 390.56 MiB).
* Bytes Received: amount of data received on hosts on the left from hosts on the top.

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

* Example: “313.73 MiB” received on “Ubuntu20-04” from “centos-userspace” (so centos-userspace sent 313.73 MiB).
* Uptime: uptime percentage for the connection between two hosts.

![](/files/40730f3b22cc72d83d9c5b16cc2b4c4c97f309aa)

* Example: “Ubuntu20-04” ↔ “centos-userspace” uptime is “100.00%”.
* Clients: connection status, uptime, latency, total data sent/received for static external clients under a Remote Access Gateway.

![](https://docs.netmaker.io/docs/operations-guide/Base64-Image-Removed)

These metrics are available in Netmaker Professional / Enterprise Edition via the Netmaker web UI.

## Exporting Metrics via Prometheus

The netmaker exporter plugin fetches statistics from the netmaker server and exposes them in a Prometheus-friendly format.

* Default exporter URL (example): <https://netmaker-exporter.nm.your-domain-name.com>
* Prometheus can be configured to scrape this exporter URL.

![](/files/ab8dce1efd4ab7524038965177d1f50d5fba43a9)

Notes:

* Prometheus is installed by default on Netmaker EE installation.
* For manual Prometheus installation, see: <https://prometheus.io/docs/prometheus/latest/installation>

Accessing the default Prometheus instance (example URL):

* <https://prometheus.nm.your-domain-name.com>
* Login: username “Netmaker-Prometheus”, password is your Netmaker EE license key.

![](/files/db6cc1ef90120f304dbb7258757d7647d08cde40)

Inside Prometheus:

* Status -> Configuration: confirms netmaker-exporter is added as a scrape config (configured in prometheus.yml).

![](/files/26cefbd1af7beae1ab8a8c9e4fd3783bf90d6f1b)

* Status -> Targets: shows the netmaker-exporter endpoint status and details.

![](/files/f61ac415d90d75f0e952ca8c2d842c5fcb77933c)

## Importing Metrics via Grafana

Grafana visualizes metrics stored in Prometheus. Netmaker EE installs a Grafana instance by default.

* Official Grafana install guide: <https://grafana.com/docs/grafana/latest/setup-grafana/installation>
* Default Grafana URL (example): <https://grafana.nm.your-domain-name.com>
* Default login: admin / admin (you will be prompted to set a new password after first login).

![](/files/ef9a10b35d735efa8b0d0ae5af080f9c4996d75a)

Adding Prometheus as a data source:

* Open the Grafana menu -> Connections (Data Sources).
* Search for Prometheus and create a Prometheus data source.
* Configure the name, Prometheus endpoint/server URL, authentication, etc.
* Click “Save & Test”.

![](/files/49d401e8a1770152081d0ca809717bfe2e1d274c)

Notes:

* The default Grafana installed with Netmaker EE already has the netmaker Prometheus instance added as a data source.

![](/files/4656bfc9ab490400bfe23e8a9273dfd8cbb51eae)

Netmaker dashboard:

* Netmaker EE installs a default Netmaker Grafana dashboard.
* This dashboard shows the same metrics available in the Netmaker web UI.

![](/files/b081563c8d84aff433dfc517c23e6e0ed523b1ae) ![](/files/806bed7ddb34092f321018519f9e13b8f4b84584)

Exporting/importing the dashboard JSON:

* Inside the Netmaker metrics dashboard, open dashboard settings (gear icon) -> JSON Model and copy the JSON.
* In another Grafana instance: Dashboards -> New -> Import -> paste JSON -> Load to add the dashboard.

![](/files/88e6a6e6a0884991824daac663109ebf4d057bc7)

![](/files/e55a52ea68a32490ba9ff8e140ecd0323a4f8c97)

![](/files/d9c669846a3948fa25dc3f70468696dbdcd59751)

## Using WireGuard to Check Network Statistics on Devices

If wireguard-tools is installed on client systems, you can view WireGuard interface statistics gathered by the netclient.

Install on Debian/Ubuntu:

* sudo apt install wireguard-tools

Run:

* wg show

This displays:

* bytes sent and received per peer
* latest handshake time
* other WireGuard details

![](/files/a955a1cf157bdc1cbe7eb02fde2296ecf7269bb6)

These metrics are part of what the netclient collects for the Netmaker web UI and the Prometheus exporter.


# Feature Matrix

Netmaker comes in four editions: Community, Teams, Business, and Enterprise. The matrix below indicates which features are available, depending on the version.

<table><thead><tr><th>Feature</th><th data-type="checkbox">Community</th><th data-type="checkbox">Teams</th><th data-type="checkbox">Business</th><th data-type="checkbox">Enterprise</th></tr></thead><tbody><tr><td><a href="/pages/99035700405c9b5b8e6706a38796a0f91dbff5a6">Dashboard UI</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/d0634bf44c3f6bbea296b328e9015d4f75f8b16e">Overlay Networks</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/2c8ef69b3dc32bece37fb8491e9703f65d245c8e">Netclient</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/4a837ecb1ded1e8e068932cda021b360b01fc9c6">ACLs</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/5bf6be3da497bc3dc534777f6942f16e0f6f6566">Enrollment Keys</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/4c68fa6950804fc849c001b80127eb3cbd4f00b7">Egress (basic)</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/8023dcd81897c9bc7f43477add0ae990e6caf0ac">Gateways (basic)</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/eb8e4b35aaf4f2e54a5c40bd19dee782100b9388">DNS</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/85d4bea0eb63629c42e3ad2972fdf043ff02a832">MFA</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/85c7a8fc2a5269c4c8cfa5a1a0f292798dcb7b57">User Management (basic)</a></td><td>true</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/85c7a8fc2a5269c4c8cfa5a1a0f292798dcb7b57">Groups and Roles</a></td><td>false</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/9d08ce7b7781bc52900cedd924ef17dd17f857f7">OAuth</a></td><td>false</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/f169a78f6e8f463983b91bf57a45815be35842fa">Desktop and Mobile User Apps</a></td><td>false</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/8023dcd81897c9bc7f43477add0ae990e6caf0ac#auto-relay-pro">Auto-Relay</a></td><td>false</td><td>true</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/ab54d87ec96414100871bc6c6526f9a5f311600b">SCIM<br>(IDP Sync)</a></td><td>false</td><td>false</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/fc0d4d10aa0e0e79723240a1d9fb0a3458be8610#audit-logs">Audit Logs</a></td><td>false</td><td>false</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/4c68fa6950804fc849c001b80127eb3cbd4f00b7">HA Egress</a></td><td>false</td><td>false</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/fc0d4d10aa0e0e79723240a1d9fb0a3458be8610">Analytics</a></td><td>false</td><td>false</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/fc0d4d10aa0e0e79723240a1d9fb0a3458be8610#grafana-dashboard">Metrics Export</a></td><td>false</td><td>false</td><td>true</td><td>true</td></tr><tr><td><a href="/pages/a7206991ebe5234fb7bf22b06e54e36f0b1575c0">White Labelling</a></td><td>false</td><td>false</td><td>false</td><td>true</td></tr><tr><td><a href="/pages/fc0d4d10aa0e0e79723240a1d9fb0a3458be8610#traffic-logs">Network Access Logs</a></td><td>false</td><td>false</td><td>false</td><td>true</td></tr><tr><td><a href="/pages/42b605135713d0ac1e93ead787ad27c424c18056">Device Posture Checks</a></td><td>false</td><td>false</td><td>false</td><td>true</td></tr></tbody></table>


# Features

This sect highlights the features in Netmaker that enhance network management, security, and performance. It includes tools to simplify management, optimize connectivity, control access, enhance


# Mesh Overlay

Secure Mesh Overlay for Hybrid & Zero Trust Infrastructure

{% embed url="<https://media.netmaker.io/features/Mesh-Overlay.mp4>" %}

Netmaker delivers a high-performance, encrypted mesh overlay network designed for distributed and hybrid infrastructure. Built on WireGuard®, it enables secure peer-to-peer connectivity across cloud, edge, on-prem, and multi-region environments, without centralised bottlenecks.

Architect deterministic connectivity. Enforce Zero Trust segmentation. Operate with full observability.<br>

Netmaker’s mesh overlay provides:

* Encrypted peer-to-peer connectivity<br>
* NAT traversal and relay support<br>
* Multi-site and multi-region networking<br>
* Hybrid cloud and on-prem integration<br>
* Centralised governance with distributed data paths<br>

This architecture reduces latency, eliminates single points of failure, and improves scalability across distributed systems.<br>

## Mesh Overlay Performance & Speed

Netmaker’s mesh overlay is engineered for high-throughput, low-latency connectivity across distributed infrastructure. Built on WireGuard®, the architecture leverages modern cryptography and direct peer-to-peer tunnels to eliminate centralised bottlenecks.

Unlike hub-and-spoke designs, traffic flows directly between authorised peers whenever possible, reducing latency and improving bandwidth efficiency. When direct connectivity is restricted (e.g., NAT, CGNAT, firewall constraints), relay mechanisms ensure reliable communication without compromising encryption or policy enforcement.

#### Performance Characteristics

* Direct peer-to-peer encrypted tunnels<br>
* No centralised data-plane choke points<br>
* Low-overhead modern cryptography<br>
* Efficient NAT traversal<br>
* Horizontal scalability across thousands of nodes<br>
* Multi-region and hybrid deployment support<br>

Control remains centralised for governance. Data paths remain distributed for performance.

This architecture enables secure connectivity without compromising throughput, scalability, or reliability in hybrid cloud and edge environments.

***

## Use Cases for a Mesh Overlay Network

A secure mesh overlay network is purpose-built for modern distributed infrastructure where performance, segmentation, and operational clarity are critical.

### Remote & Distributed Work Environments

Modern remote work requires secure, high-performance access to internal services without centralised bottlenecks.

A mesh overlay enables direct, encrypted peer-to-peer connectivity between users and infrastructure resources, reducing latency and improving reliability compared to traditional hub-based architectures. Access is governed by identity-aware policies and Zero Trust segmentation rather than network location.

Key advantages:

* Direct encrypted access to internal systems\ <br>
* Reduced latency through distributed data paths\ <br>
* Identity-integrated access controls\ <br>
* Elimination of centralised traffic choke points\ <br>
* Full observability and auditability\ <br>

This approach supports global remote teams while maintaining an enterprise-grade security posture.

***

### Multi-Site & Global Enterprise Infrastructure

Organisations operating across multiple offices, data centres, or regions require efficient cross-site communication.

In traditional hub-and-spoke models, traffic between two sites must traverse a central gateway, which increases latency and introduces unnecessary load. A mesh overlay enables authorised sites to communicate directly, improving performance and distributing traffic evenly across the network.

Benefits for multi-site enterprises:

* Direct region-to-region encrypted tunnels<br>
* Reduced inter-site latency<br>
* Improved resiliency with no single data-plane bottleneck<br>
* Policy-driven segmentation between business units<br>
* Consistent security across hybrid cloud and on-prem environments<br>

This architecture is particularly well-suited for global enterprises with hybrid infrastructure footprints.

***

### IoT & Edge Device Networks

Large-scale IoT and edge deployments introduce complex connectivity challenges across geographically distributed devices.

A mesh overlay allows sensors, controllers, gateways, and embedded systems to form secure, encrypted peer-to-peer connections without relying on centralised routing hubs. Devices operate as part of a virtual subnet, enabling simplified communication and management across locations.

Advantages for IoT and edge environments:

* Secure device-to-device connectivity<br>
* Reduced latency for real-time data exchange<br>
* Distributed load across the network<br>
* Simplified device management and updates<br>
* Scalable architecture for growing deployments<br>

By abstracting physical topology, the overlay provides a consistent, secure networking model across heterogeneous device environments.

<br>


# Multi Network Segmentation

Network Segmentation & Multi-Overlay Architecture

{% embed url="<https://media.netmaker.io/features/Multi-Network-Management.mp4>" %}

Netmaker enables you to design and operate multiple independent overlay networks within a single control plane.\
Each network functions as its own isolated security domain with dedicated policies, access controls, and routing behaviour.

This architecture allows enterprises to enforce strict segmentation across environments, tenants, business units, or compliance zones — without deploying separate physical infrastructure.

***

### Create Multiple Isolated Networks by Design

Unlike traditional segmentation models that divide a single network into subzones, Netmaker allows you to create entirely separate overlay networks, each with:

* Independent peer membership<br>
* Dedicated access control policies<br>
* Separate DNS configuration<br>
* Custom routing and egress rules<br>
* Distinct security boundaries<br>

Each overlay network is logically isolated and cryptographically independent, ensuring clear operational separation across environments.

***

### Environment Separation Without Infrastructure Duplication

Design dedicated networks for:

* Production<br>
* Staging<br>
* Development<br>
* QA<br>
* Customer environments<br>
* Partner access<br>
* Compliance-regulated workloads<br>

All networks remain centrally managed while maintaining strict isolation.

This enables:

* Reduced lateral movement risk<br>
* Clear blast-radius containment<br>
* Simplified governance<br>
* Predictable security enforcement

***

### Multi-Tenant & MSP-Ready Architecture

For enterprises, OEMs, and managed service providers, multi-network capability is critical.

Netmaker supports:

* Customer-isolated overlay networks<br>
* Per-tenant policy enforcement<br>
* Role-based access is scoped per network<br>
* Centralised observability across all networks<br>

This allows organisations to operate multiple secure domains from a unified platform while preserving tenant isolation.

***

### Zero Trust Segmentation Within and Across Networks

Segmentation operates at two levels:

1. Between networks — full logical isolation<br>
2. Within networks — granular peer-to-peer policy enforcement<br>

This layered model strengthens Zero Trust architecture by ensuring:

* No implicit trust based on location<br>
* Explicit authorization for all connectivity<br>
* Default-deny policy support<br>
* Conditional and Just-In-Time access controls<br>

***

### Hybrid & Multi-Region Consistency

Each overlay network can span:

* Cloud providers (AWS, Azure, GCP)<br>
* On-prem data centres<br>
* Edge deployments<br>
* Global regions<br>

Segmentation policies apply consistently across environments without relying on physical topology.

***

### Observability Across Multiple Networks

Manage and monitor all overlay networks from a centralised control plane.

Gain visibility into:

* Network-level traffic flows<br>
* Cross-segment communication<br>
* Policy enforcement events<br>
* Administrative actions<br>

Operate multiple secure domains without sacrificing clarity or governance.

***

### Why Multiple Networks Matter

Modern infrastructure is not a single flat network.

Enterprises require:

* Separation of duties<br>
* Regulatory boundaries<br>
* Tenant isolation<br>
* Environment partitioning<br>
* Independent security domains<br>

Netmaker’s multi-overlay architecture provides these capabilities natively, without introducing routing complexity or centralised bottlenecks.

<br>


# ACLs - Access Controls

Easily manage network access with the new Netmaker ACLs

{% embed url="<https://www.youtube.com/watch?v=nEQfMd3-o1w>" %}

With the latest **ACL feature** in Netmaker, managing network access has never been easier. This powerful addition allows network administrators to control communication between devices by defining policies that restrict or allow access.

## What is an ACL?

An **Access Control List (ACL)** is a set of rules that specify which users or devices are allowed or denied communication within a network. ACLs are used by network administrators to control traffic flow, ensuring that only authorized entities can access or interact with certain network resources, enhancing overall network security.

There are two main types of ACL policies: **User Policies** and **Resource Policies**

### User Policies

This type of policy controls **which users** can access or interact with specific network devices (e.g., servers, databases, gateways). It ensures that only authorized users have permission to access sensitive devices or services.

<figure><img src="/files/4qHwoZCkVLUFfYp0djbz" alt=""><figcaption></figcaption></figure>

Example: Grant access to a **DevOps team** for database servers while restricting other teams' access to the same resources. This ensures only authorized users can access sensitive resources, improving network security.

### Resource Policies

This policy controls **which devices** (like servers, web applications, databases, or gateways) can communicate with each other. It restricts or permits communication between devices based on the network's security needs.

<figure><img src="/files/BviUUhqkcWBAMQkW8Kfx" alt=""><figcaption></figcaption></figure>

Example: A web server might be allowed to communicate with a database server but blocked from connecting to other devices, such as file storage servers or printers. This limits unnecessary or unauthorized traffic between devices, enhancing network security and performance.

## Default Policies

The **Default Policies** are automatically generated whenever a new network is created, enabling unrestricted two-way communication between users and resources, as well as between resources themselves. These policies ensure full connectivity during the initial setup.

<figure><img src="/files/EyAjHRpJMA4W0G4UJqpf" alt=""><figcaption></figcaption></figure>

1. **All Nodes**: Enables all resources (e.g., servers, gateways) to communicate freely with one another in both directions.
2. **All Remote Access Gateways**: Allows remote access gateways (`remote-access-gws`) to communicate with all resources **and vice versa**.
3. **All Users**: Grants all users full access to all resources, ensuring open two-way communication.
4. **Network Admin**: Grants users in the `netmaker Admin Group` and the `All Networks Admin Group` full two-way communication with the remote access gateways (`remote-access-gws`) and associated resources.
5. **Network User**: Grants users in the `netmaker User Group` and the `All Networks User Group` unrestricted access to remote access gateways (`remote-access-gws`) and associated resources in both directions.

### How to Add ACLs in Netmaker <a href="#how-to-add-acls-in-netmaker" id="how-to-add-acls-in-netmaker"></a>

Navigate to the **Access Control** page to view a list of all ACLs across the network. From there, you can enable or disable any ACL as needed. To create a new policy, simply click **Add Policy**.

<figure><img src="/files/dKsdutx8HDiAk24dDXOJ" alt=""><figcaption></figcaption></figure>

Here, you can define a custom rule by specifying:

* **Policy For**: Choose whether the policy applies to resources (controlling device access) or users (managing user permissions).
* **Rule Name**: Give the rule a clear name, like "api-gateway-access" or “devops-team”
* **Source and Destination**: Select the source and destination entities to control which nodes can communicate. \
  [Tags](https://docs.netmaker.io/docs/features/tag-management-pro) are available to help group nodes and apply rules more efficiently.
* **Enable Policy**: Toggle this switch to activate or deactivate the policy.

Once configured, click **Save Policy** to apply the policy.

To enable communication between peers in the **same group**, add the **group** to both the **Source** and **Destination** fields.

### How to Update ACLs in Netmaker <a href="#how-to-update-acls-in-netmaker" id="how-to-update-acls-in-netmaker"></a>

Identify the ACL policy you want to update, click on the three dots, and choose the "Edit" option

<figure><img src="/files/4Drfw9fSeFpslbF2RO34" alt=""><figcaption></figcaption></figure>

After selecting "Edit," make the necessary adjustments to the ACL policy settings based on your requirements.

<figure><img src="/files/i1SYkMjgHRKYdQ7i894t" alt=""><figcaption></figcaption></figure>

### How to Remove ACLs in Netmaker <a href="#how-to-remove-acls-in-netmaker" id="how-to-remove-acls-in-netmaker"></a>

Identify the ACL policy you want to remove, click on the three dots, and select the "Remove" option.

<figure><img src="/files/B5f4WDtEdOQugmDeaCS2" alt=""><figcaption></figcaption></figure>

## Advanced ACL Capabilities

### Egress ACLs with IP Restriction

Netmaker’s Egress feature allows traffic to be forwarded from the mesh network to external networks such as office LANs, data centers, or legacy infrastructure. With the latest ACL enhancements, access control can now be applied at the IP level inside an egress CIDR range.

This provides fine-grained control over external network access without exposing entire subnets.

Key capabilities:

* Restrict access to specific IPs inside a larger egress CIDR block.
* Apply ACL rules to individual endpoints within external networks.
* Combine egress resources, nodes, tags, and IP-level targets in a single policy.
* Define **one-way or two-way traffic rules** depending on the use case (e.g., mesh network nodes can reach egress network IP(s), or egress network IP(s) can reach mesh network nodes)

Example: Allow access only to `192.168.10.25` (a specific internal service) within an egress network, while blocking all other IPs in the same subnet.

#### Where to configure Egress ACLs

Egress-related ACL policies can be created and managed in two places depending on your workflow:

**From the Egress screen**

Use this when configuring or editing an egress resource. ACL rules can be defined directly in context to immediately control traffic flowing through that egress.

**From the Access Control screen**

Use this when you want to centrally manage all ACL policies, including those targeting egress resources, IPs, or external networks.

**Example:**\
You define a global ACL policy that allows only the `prod-services` tag to access `10.20.5.10` through any egress resource, while denying all other tags from reaching that IP.

**Access control rules can be configured as one-way traffic or two-way traffic, depending on the required access model.**

In the following **one-way setup**, only mesh network nodes are allowed to initiate connections to the egress network IP (10.20.5.10), for services like accessing external resources or APIs.

<figure><img src="/files/FLVZuVTeLS4szOuNsBDP" alt=""><figcaption></figcaption></figure>

And In the following **two-way setup**, you can allow the egress network IP (`10.20.5.10`) to initiate connections back to mesh network nodes for services like monitoring or database callbacks.

<figure><img src="/files/MHPYlEck126xOAtTXKFm" alt=""><figcaption></figcaption></figure>

### Site-to-Site ACLs (Beta)

Using Netmaker's Egress feature at different locations, entire networks can be connected together in a site-to-site setup. Site-to-Site ACLs extend Netmaker's Access Control functionality by allowing administrators to define exactly which traffic is permitted between connected sites.

#### Where to Configure Site-to-Site ACLs

Site-to-Site ACLs can be created from the **Access Control** screen by creating a **Resource Policy**. When defining the policy, select the source and destination resources that should be allowed to communicate.

For site-to-site deployments, it is common to use **egress resources** as the source and destination, then apply additional restrictions using tags, nodes, routes, or specific IP addresses to limit access to only the required resources.

#### Key capabilities:

* Create Access Control rules between egress resources on different networks.
* Use egress resources, nodes, tags, and IP addresses in the same rule.
* Control traffic between specific sites or IP addresses instead of full network access.
* Configure one-way or two-way communication between sites.

#### **Traffic Direction**

Access Control rules can be configured as **one-way** or **two-way** traffic.

In a **one-way** setup, only the source is allowed to initiate connections to the destination. Traffic initiated in the opposite direction is blocked.

**Example:**\
Allow users in the Headquarters network to access a database server located in a Branch Office network, while preventing any devices in the Branch Office network from initiating connections back to Headquarters.

<figure><img src="/files/27UvtMQJnw9jlgCdvIvC" alt=""><figcaption></figcaption></figure>

In a **two-way** setup, both the source and destination are allowed to initiate connections to each other.

**Example:**\
Allow a monitoring server in Site A to access application servers in Site B and allow those application servers to send logs, alerts, or metrics back to the monitoring server.

<figure><img src="/files/AW49E3dJG81fX7OJzfiu" alt=""><figcaption></figcaption></figure>

#### **IP Restrictions**

When creating a **Resource Access Control policy** for site-to-site communication, you define the source and destination sites, and optionally restrict traffic down to specific IPs on both sides.

This allows restricting communication between connected sites at the IP level, instead of allowing full subnet-to-subnet access.

**Example:**\
A Branch Office egress advertises the subnet `10.110.20.0/24`. Instead of allowing full access to the subnet from the remote site, an Access Control rule can be created to allow communication only with `10.110.20.10`. All other IPs in the subnet remain inaccessible from the remote site.

<figure><img src="/files/3Ksy43sTEdXiMvfT5dm2" alt=""><figcaption></figcaption></figure>

For even more granular control, an Access Control rule can restrict traffic between specific IPs on both sides. For example, allow only `192.168.1.10` in Site A to communicate with `10.110.20.10 and 10.110.20.12` in Site B, while blocking all other traffic between the two sites.

<figure><img src="/files/uKKipNgMiircCsP5dM23" alt=""><figcaption></figcaption></figure>


# Tag Management

## Tag Management (Pro)

Tag your devices for easy management within the network.

Tag Management in Netmaker enables administrators to organize and manage devices within a network by applying **tags**. Tags simplify the process of grouping, categorizing, and managing nodes, making network management more efficient and scalable.

## What is Tag Management

Tags are labels that can be assigned to devices in a network. Instead of managing nodes individually, you can group them by assigning tags that reflect their roles, environments, or other relevant attributes. This categorization helps streamline administrative tasks, such as access control, resource allocation, and policy enforcement.

With **Netmaker's Tag Management**, administrators gain the ability to easily group and manage devices, improving both security and operational efficiency.

## Key Features of Tag Management

* **Tagging devices:** Administrators can assign tags to devices either manually or automatically.
* **Peer Auto-grouping:** Devices can be automatically **grouped** based on the **enrollment key** used when they join the network.
* **Efficient Management:** Grouping devices by tags makes it much easier to apply policies, manage resources, or enforce network segmentation based on categories.

{% hint style="info" %}
PRO Feature: Tag management is available as part of the **Netmaker PRO** offering, enabling advanced network management capabilities.
{% endhint %}

## How to Use Tag Management

Administrators can tag devices either during or after their enrollment into the network.

### Tagging Devices from the Node Interface

* Since v0.90.0, administrators can now tag devices directly from the node interface. Simply navigate to the node interface, select the device you wish to tag, and click Update tags. ![](https://docs.netmaker.io/docs/features/Base64-Image-Removed)

<figure><img src="/files/cJYpPABTH7V35FZfki8D" alt=""><figcaption></figcaption></figure>

* Assign the appropriate tag from the available options. ![](https://docs.netmaker.io/docs/features/Base64-Image-Removed)

<figure><img src="/files/WsFHlvWrsGxoE0DFzMbm" alt=""><figcaption></figcaption></figure>

### Manually Grouping Devices

{% stepper %}
{% step %}

### Open Tag Manager

Go to the Tag Manager interface to add one or more tags. ![](https://docs.netmaker.io/docs/features/Base64-Image-Removed)

<figure><img src="/files/m1ttlT8MLK7GB3BWgLCU" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Select Devices

Select the device(s) you want to assign to a specific tag or group. Since version 0.90.0, admins also have the option to select a color for the tag, providing a visual distinction for easier organization. ![](https://docs.netmaker.io/docs/features/Base64-Image-Removed)

<figure><img src="/files/S66gAVxekGU3goiPryQ7" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Create Tag

Click on "Create Tag" to generate the tag.
{% endstep %}
{% endstepper %}

### Automatically Grouping Devices via Enrollment Keys

{% stepper %}
{% step %}

### Create or Edit Enrollment Key

Create an Enrollment Key or edit an existing one in the Enrollment Keys screen. ![](https://docs.netmaker.io/docs/features/Base64-Image-Removed)

<figure><img src="/files/kKl2L1Yor8qi2QvtsvS1" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Associate Tag

Associate the **enrollment key** with a specific tag. ![](https://docs.netmaker.io/docs/features/Base64-Image-Removed)

<figure><img src="/files/sylX0EzceO9USu6rpZCe" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Modify if Needed

You can also modify an existing Enrollment Key.
{% endstep %}

{% step %}

### Automatic Grouping on Join

Any new device joining the network with this key will automatically be grouped with the defined tags or groups.
{% endstep %}
{% endstepper %}

## Use Cases for Tag Management

* **Network Segmentation:** Tagging can be used to logically segment devices based on their role, location, or environment. For example:
  * tags: “prod”, “dev”, “staging”
  * tags: “internal”, “external”, “frontend”, “backend”, “web-servers”, “file-servers”
* **Access Control:** Tags simplify the process of applying **Access Control Lists (ACLs)** to groups of devices. For instance, all devices tagged as **"external"** can be denied access to certain internal services, while **"internal"** devices are granted full access.
* **Node Identification:** Tags make it easier to identify devices with specific characteristics, such as location, purpose, or criticality (e.g., “critical”, “backup”).

## Best Practices for Tag Management

* **Use Descriptive Tag Names:** Ensure that tag names are clear and descriptive, such as “dev”, “prod”, “external”, or “critical”.
* **Consistent Tagging:** Establish consistent naming conventions to avoid confusion. For example, use lowercase letters and hyphens or underscores to separate words (e.g., “ext-client” vs. “extClient”).
* **Document Tag Purposes:** Keep a record of what each tag is used for, so other administrators or team members can quickly understand its purpose.


# Egress

secure network routing to access private and external networks

{% embed url="<https://www.youtube.com/watch?v=4x20rkr-8jQ>" %}

## Understanding Egress&#x20;

Egress enables devices in a Netmaker network to access resources outside the overlay through a designated Linux node with connectivity to the destination environment.

This can provide access to:

* Virtual Private Clouds (VPCs)
* Kubernetes clusters
* Home and office networks
* Private corporate infrastructure
* Data centers
* Cloud-hosted services and applications

Once configured, authorized users and devices can securely communicate with these resources without requiring direct connectivity.

### Routing Methods

Netmaker supports two methods for reaching external resources.

<figure><img src="/files/itG2xkYYAj73zd8UWKxb" alt=""><figcaption></figcaption></figure>

#### Site

Site routing is intended for IP-based destinations and network ranges.

Common use cases include:

* Branch offices
* Corporate networks
* Data centers
* VPCs
* Kubernetes environments

Examples:

* `192.168.1.0/24`
* `10.0.0.0/8`
* `10.116.0.18/32`

Choose this option when the destination is identified by an IP address or network subnet.

<figure><img src="/files/c9aZE6uLRQ6AgXboO3Qc" alt=""><figcaption></figcaption></figure>

#### Apps (BETA)

Apps routing directs traffic using domain names rather than network ranges.

Common use cases include:

* SaaS platforms
* Internal web applications
* APIs
* Cloud services

Examples:

* `example.com`
* `api.example.com`

Choose this option when access is required to a specific service or application rather than an entire network.

> Apps routing is currently in BETA and may change in future releases.

### Network Address Translation (NAT)

In most deployments, Network Address Translation (NAT) is required unless the destination environment can directly return traffic to Netmaker clients.

Two NAT modes are available.

<figure><img src="/files/MZkx3XFPuumqTnvtsdWo" alt=""><figcaption></figcaption></figure>

* **Direct:**  The traditional NAT mode that requires unique IP ranges for each remote site. This option is recommended when every connected environment uses different subnets and no address overlap exists.
* **Virtual:** A new mode available in the e**nterprise plan** that assigns virtual IP ranges, allowing multiple sites with overlapping local IPs to coexist. It resolves a key limitation by enabling connectivity across these overlapping networks. \
  For example:

  * NYC Office → `192.168.1.0/24`
  * LA Office → `192.168.1.0/24`
  * Chicago Office → `192.168.1.0/24`

  Normally, these overlapping ranges create routing conflicts. Virtual NAT solves this by assigning a unique virtual subnet to each location and automatically translating traffic between the virtual and actual addresses.

{% hint style="info" %}
NAT can be disabled for users who prefer to manage their own masquerading and post-routing rules, or who need to preserve source IP addresses.
{% endhint %}

| Feature                        | Direct NAT           | Virtual NAT                     |
| ------------------------------ | -------------------- | ------------------------------- |
| Supports unique subnets        | Yes                  | Yes                             |
| Supports overlapping subnets   | No                   | Yes                             |
| Additional address translation | No                   | Yes                             |
| Enterprise feature             | No                   | Yes                             |
| Recommended for                | Standard deployments | Multi-site overlapping networks |

### High Availability

For additional resiliency, connectivity can be provided by multiple Linux nodes sts instead of a single machine.

Rather than selecting one node, administrators can assign a tag. Any node carrying that tag becomes eligible to forward traffic.

If the active host becomes unavailable, another tagged node automatically takes over, helping maintain uninterrupted access to the destination.

### Access Control

Routing determines how traffic reaches a destination, while Access Control Policies determine who can use that path.

Administrators can restrict access using:

* Nodes
* Tags
* Users
* Specific IP addresses

This enables organizations to limit connectivity to only the resources that are required.

## Configuring an Egress Gateway

Deploy a netclient on a network-accessible Linux node such as a server, office router, or Kubernetes worker node that is stable and mostly static (minimal IP changes or downtime). For HA Egress, you can assign the route to a group of Linux nodes to provide redundancy and continuous connectivity.

<figure><img src="/files/Xsr7kXYVk7RWUr6EKQc6" alt=""><figcaption></figcaption></figure>

Click the **Add Route** button to begin creating a new Egress Route.

<figure><img src="/files/itG2xkYYAj73zd8UWKxb" alt=""><figcaption></figcaption></figure>

### Step 1: Choose Routing Mode

When creating an Egress Route, first select how traffic should be routed.

<figure><img src="/files/lfO7LE910j1H6ATip8Ii" alt=""><figcaption></figcaption></figure>

#### **Site**

Routes traffic based on:

* Subnets
* Individual IP addresses
* Network ranges

Use this option when connecting to private infrastructure or remote networks.

#### Apps (BETA)

Routes traffic based on:

* Domains
* Application endpoints

Use this option when providing access to SaaS platforms, APIs, or web applications.

Click **Next** to continue.

### Step 2: Configure Route Details

{% stepper %}
{% step %}

### Enter a Name (Required)

In the **Name** field, enter a unique and descriptive name for this egress route.
{% endstep %}

{% step %}

### Enter a Description (Optional)

In the **Description** field, optionally describe the purpose or location of this egress route.
{% endstep %}

{% step %}

### Set the NAT mode to Direct or Virtual&#x20;

**Direct:** Standard NAT for unique IP addresses.

**Virtual:** Enables multiple sites with overlapping IPs.
{% endstep %}

{% step %}

### Specify Egress Range or Application (Required)

Enter the external resource this egress route should reach. You can specify:

Example

* Subnet → `10.116.0.0/20`\ <br>

  <figure><img src="/files/HR7WCCSwcLHfHVHER7uf" alt=""><figcaption></figcaption></figure>

* Application → AWS S3 (ap-east-2) Service\ <br>

  <figure><img src="/files/uZxFesOtfyNyqczmYivE" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Click "Next"

After completing all fields, click the **"Next"** button to continue with the egress route creation.
{% endstep %}

{% step %}

### Select a node to act as an Egress

Select the node to serve as the Egress node for the route, or assign a tag to enable HA Egress.&#x20;

<figure><img src="/files/Qv9K8wsgQg4x7n6sLW7c" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**High availability is not supported for Apps egress routes**
{% endhint %}
{% endstep %}
{% endstepper %}

### Configure Egress Access Policies (Optional but Recommended)

Purpose: Define **which nodes and users** are allowed to access the egress route.<br>

<figure><img src="/files/lMkFwhVjfxqzIYLTRdi2" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### Add Resources Policy

Select the **nodes** that are allowed to route traffic through the egress route.<br>

<figure><img src="/files/lujVUzZgTptGNLqQhO24" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Add Users Policy

Select the **users** who are allowed to access the egress route<br>

<figure><img src="/files/joxIaEyPmkORgSGxjG0k" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### When finished, click "Finish" to save the configuration.

<figure><img src="/files/nJRHIlMK5oGmW7q1hRQD" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### If you have multiple Apps/IP Ranges to add, click "Add Route" again.

{% endstep %}
{% endstepper %}

Netmaker will set either iptables or nftables rules on the node depending on which one you have installed on your client. This will then implement these rules, allowing it to route traffic from the network to the specified range(s).

## The Overlapping IP Problem

In many organizations, remote sites independently use the same private IP address ranges. This is very common because:

* Branch offices often use standard ranges like 192.168.1.0/24 or 10.0.0.0/8
* Acquired companies already have established networks that can't be easily changed
* Customer sites use default router configurations with identical IP schemes

Why This Is a Problem: Imagine you have three branch offices:

1. NYC office: 192.168.1.0/24
2. LA office: 192.168.1.0/24
3. Chicago office: 192.168.1.0/24

Each office has a server at 192.168.1.10. When you try to connect to 192.168.1.10, which office's server should you reach? Your network can't tell them apart because they all use the same address. This creates a routing conflict.

**Traditional Limitation:** In Direct NAT mode, Netmaker could only route to one office at a time. Accessing additional sites required renumbering networks to ensure unique IP ranges—a costly and time-consuming process.

### Virtual NAT Mode: The Solution for Egress Routes

Virtual NAT mode assigns each remote network accessed through an Egress Route a unique virtual IP range. When you configure an Egress Route with Virtual NAT:

* You specify the actual remote network in the Egress field (e.g., 192.168.1.0/24)
* You select "Virtual" as the NAT mode\ <br>

  <figure><img src="/files/U5JaW5yjvDFslliUb3PX" alt=""><figcaption></figcaption></figure>
* Virtual NAT automatically assigns a unique virtual IP range (e.g., 198.19.10.0/24) defined under the network settings\ <br>

  <figure><img src="/files/06y4FPp3JGwBXVH3Oa4n" alt=""><figcaption></figcaption></figure>
* Netmaker clients use the virtual range to access the remote network
* The egress node automatically translates between virtual and actual IPs

This removes the previous limitation on overlapping IP ranges for Egress Routes, enabling both site-to-site and remote access use cases with conflicting network addresses.

#### Setting Your Own Virtual IP Range

1. Access the network interface and edit the network settings<br>

   <figure><img src="/files/0CWOiovnb0Tc6KSAbs6v" alt=""><figcaption></figcaption></figure>

2. Enter the desired virtual subnet (e.g., `197.0.8.2/16`)\ <br>

   <figure><img src="/files/YCj42TbzBLuehzJvrT0g" alt=""><figcaption></figcaption></figure>

3. Apply network configuration changes.

## Advanced Use Cases

1. Segmenting Traffic Flow Through Egress Gateways

   User will need to add these additional routing rules on the egress machine to segment traffic to multiple egress ranges as desired when on multiple networks

```plaintext
iptables -t filter -N netmakeregressiptables -t filter -I FORWARD -i netmaker -d egressGwRangeA,egressGwRangeB -j netmakeregressiptables -t filter -I netmakeregress -s networkRangeA -d egressRangeA -j ACCEPTiptables -t filter -I netmakeregress -s networkRangeB -d egressRangeB -j ACCEPTiptables -t filter -A netmakeregress -j DROP# NAT Rulesiptables -t nat -I POSTROUTING -s networkRangeA -d egressGwRangeA -j MASQUERADEiptables -t nat -I POSTROUTING -s egressGwRangeA -d networkRangeA -j MASQUERADEiptables -t nat -I POSTROUTING -s networkRangeB -d egressGwRangeB -j MASQUERADEiptables -t nat -I POSTROUTING -s egressGwRangeB -d networkRangeB  -j MASQUERADE
```

2. IPv6 NAT Masquerading for Egress Gateways

   Currently IPv6 Egress Gateways are not working because the default kernel builds for most common linux distributions do not support ipv6 masquerading. Custom linux kernel needs to be built with flag for enabling ipv6 masquerading to get ipv6 egress gateways working.

   Some online resources about the topic:

```plaintext
https://superuser.com/questions/1751062/ipv6-masquerading-on-linuxhttps://www.kernelconfig.io/config_nf_nat_masquerade_ipv6?q=&kernelversion=5.15.116&arch=x86https://www.reddit.com/r/PFSENSE/comments/vb4r3s/ip6_masquerading
```

### Egressing External Clients <a href="#egressing-external-clients" id="egressing-external-clients"></a>

Unmanaged external clients that are directly connected to a Remote Access Gateway can also act as egressing machines. The idea is the same as egress gateways. The only difference is that Netclient is necessary with egress gateways, whilst only Wireguard is needed with egressing external clients. This feature is provisioned for situations or scenarios where installation of Netclient is not ideal or even possible. For example most VPN routers support WireGuard, but they are available only as plugins that are tailormade or closely coupled with the router’s firmware or user interface. While there are ways to make Netclient work for some routers, the integration could get cumbersome, obsolete, or compromising. Of course this feature is also applicable for simple or ad-hoc networking purposes so long as the external client supports iptables and IP forwarding.

At the time of this writing, this feature only supports Linux-based external clients. But the remote machines can be anything, provided they are in the same local network as one of the egressing external client’s network interface.

#### Configuring Egressing External Clients <a href="#egressing-external-clients__configuring-egressing-external-clients" id="egressing-external-clients__configuring-egressing-external-clients"></a>

The configuration is pretty much the same as Egress Gateways. First, make sure that iptables is installed and IP forwarding is enabled. Please refer to your distro’s documentation on how to do this. For Ubuntu you might do:

```plaintext
#update
apt-get update

#install
iptablesapt-get install iptables

#enable IP forwarding
sysctl -w net.ipv4.ip_forward=1
```

You can then responsibly specify the applicable egress ranges on the external client’s VPN configuration, specifically in the “Additional Addresses” field as shown in the image below. It goes without saying that you can specify single addresses such as 172.16.1.2/32.

<figure><img src="/files/D94eOcAurKxed1ksWIDW" alt=""><figcaption></figcaption></figure>

Your Netmaker server will then pick up the egress ranges and propagate it to all the other managed devices in the netmaker network. And of course you can edit them anytime when necessary. For more information on how to create or edit client VPN configurations, please refer to these links:

{% content-ref url="/pages/2cPkos93a9XpW2rIAmW1" %}
[Deploying Static WireGuard](/getting-started/operations-field-guide/deploying-static-wireguard)
{% endcontent-ref %}

{% content-ref url="/pages/5a7da52f38313d16adc5c6c16a8a2f2ec328e46c" %}
[Integrating Non-native Devices](/how-to-guides/integrating-non-native-devices)
{% endcontent-ref %}

In some cases you might need to add POSTROUTING rules. In Ubuntu, you might do:

```plaintext
#get the name of the specific network interface of the egressing client machine# that is associated with the egress ranges that you have specifiedip a#add the necessary POSTROUTING rule, say the interface name is `eth1`iptables -t nat -I POSTROUTING -o eth1 -j MASQUERADE
```


# DNS

{% embed url="<https://www.youtube.com/watch?v=YpDwYQGbpMw>" %}

## DNS in Netmaker

Netmaker includes a DNS management system (v1.1.0+), which lets you configure **nameservers** and manage **DNS records** directly in the admin UI.

Previously, DNS relied on manual CoreDNS configs. Now, DNS can be managed directly in Netmaker with no extra setup.

## Why Use DNS?

* **Simplifies connectivity** – no need to memorize IPs; connect via hostnames.
* **Consistency** – devices always have a predictable name.
* **Flexibility** – supports both IPv4 and IPv6.
* **Split DNS support** – resolve only specific domains via a custom resolver.

## Key Features

### Name-servers

You can configure global or scoped nameservers for your network.

![](/files/C6meeGdVCy0TSlpp6MYc)

* **Public resolvers**: Google (8.8.8.8), Cloudflare (1.1.1.1), Quad9, etc.
* **Custom resolvers**: your own DNS infrastructure.
* **Match Domain (Split DNS)**: send queries for specific domains (e.g., `*.corp.local`) to a given resolver.
* **Search Domain:** Adds the domain as a search suffix so peers can be resolved using short hostnames.
* **Match All Queries**: force all DNS traffic through the chosen resolver.
* **Peer Scoping**: apply DNS settings only to selected peers.

{% hint style="warning" %}
Important: When using an internal DNS server, ensure peers can access it via an egress gateway; without a valid route, DNS queries will fail.
{% endhint %}

### Search Domain

The **Search Domain** option (available under Add/Edit Nameserver → Match domains) allows Netmaker to automatically append a specified domain when resolving unqualified hostnames.

When enabled, this feature simplifies hostname resolution for internal services — you can reach peers without typing their full domain names.

#### Purpose

The Search Domain setting helps clients resolve short hostnames by automatically completing them with a given domain suffix.

It’s especially useful in managed environments or when using internal DNS zones (e.g., `corp.local`, `vpn.netmaker.io`, `iot-network.corp.com`, etc.).

#### Example

If you configure:

```plaintext
Match domain: iot-network.corp.com
Search domain: enabled
```

![](/files/LUmMWdovrtAKLAjbUhqg)

Then a query for:

```plaintext
ping gateway-O1
```

will automatically be expanded by the system resolver into:

```plaintext
ping gateway-O1.iot-network.corp.com
```

and resolved using the configured nameserver(s).

#### Behavior Notes

* Applies **only to unqualified hostnames** (hostnames without dots, e.g., `gateway-O2`).
* The setting affects **only local resolver behavior on connected peers** — it does **not** change how records are created or stored in Managed DNS.
* Works with **Stub** and **Static** DNS modes, but **does not work with Uplink** mode.
* Search Domain toggle behavior:
  * ON: Example: `gateway-O2` → system automatically tries `gateway-O2.iot-network.corp.com`.
  * OFF: Example: `gateway-O2` → system tries just `gateway-O2`. Fully qualified hostnames like `gateway-O2.server1.iot-network.corp.com` still work.

### DNS Records (Managed DNS)

Netmaker automatically creates DNS records for your nodes and gateways. These records make it possible to connect by hostname rather than IP address.

* Each **netclient** and **gateway** gets an auto-generated DNS record.
* Both IPv4 and IPv6 addresses are included.
* Records follow the format:

```plaintext
<node-name>.<network-name>.<dns-base-domain>
```

The DNS base domain is set under **Settings → System Configuration**.

Examples:

```plaintext
gateway-O1.iot-network.corp.com → 100.111.110.2, fd3c:e02d:d1b:8d7b::2

ny-office-egress.iot-network.corp.com → 100.111.110.4, fd3c:e02d:d1b:8d7b::4

server-endpoint.iot-network.corp.com → 100.111.110.1, fd3c:e02d:d1b:8d7b::1
```

Usage:

```plaintext
ping gateway-O1.iot-network.corp.com
ssh user@server-endpoint.iot-network.corp.com
```

You can view and manage these from Networks → DNS → DNS Records in the admin UI.

![](/files/OcyemB8Hi2R1s735WFHz)

### Key Features of Manage DNS

{% stepper %}
{% step %}

### How It Works

Manage DNS relies on the **broker** to synchronize DNS entries. Without the broker, the feature won't function properly.

It is an out-of-the-box feature that can be enabled by setting `MANAGE_DNS=true` in the `netmaker.env` file. Starting with version v0.99.0, this feature is configurable through the settings of your Netmaker dashboard.

![](/files/c6E7ur19zE6qMtQ0a2Td)

It is independent of CoreDNS and does not require CoreDNS to be enabled.
{% endstep %}

{% step %}

### Domain Name Format

Each device registered in the network is automatically assigned a domain name in the format:

`<device-name>.<network-name>.<dns-base-domain>`

Example: `deviceA.networkA.corp.com`
{% endstep %}

{% step %}

### Netclient Configuration

No manual setup is required on the `netclient` side. The `netclient` automatically checks if Manage DNS is enabled during startup and activates the necessary DNS components.
{% endstep %}

{% step %}

### Static Nodes Configuration

Manage DNS is enabled on static nodes by default, assigning the node’s gateway interface IP as the DNS. If a custom DNS is set in the WireGuard config under advanced settings when generating the conf file, Netmaker applies that instead.

Nodes resolve using the format `<node-name>.<network-name>.<dns-base-domain>`, where the DNS base domain is configured under Settings → System Configuration.

![](/files/Z389QgxzpMoGiiS67tET)
{% endstep %}
{% endstepper %}

## Troubleshooting for netclient and extClient

<details>

<summary>Failed DNS Restoration</summary>

If `netclient` fails to restore DNS settings:

* Check for a backup file at `/etc/netclient/resolv.conf.nm.bkp`. If it exists, replace `/etc/resolv.conf` with the backup.
* If no backup exists, manually edit `/etc/resolv.conf` to remove the Netmaker network IP and search domain.

</details>

<details>

<summary>Incorrect IP in Cache</summary>

If `ping`, `nslookup`, or `dig` returns an old IP, flush the local DNS cache:

```bash
resolvectl flush-caches
```

</details>

<details>

<summary>IPv6-Only extClient</summary>

If an IPv6-only device tries to connect via IPv4, edit the WireGuard config file and update the `AllowedIPs` section to include only IPv6 addresses/ranges.

</details>

## CoreDNS (Legacy Method)

As of 0.22.0, CoreDNS is an active part of the Netmaker system. We deprecated setting entries on the hosts file which was not an ideal implementation. Netmaker server actively sets the DNS entries on the CoreDNS server. After you install the Netmaker server components, you can see the CoreDNS container running as well. You need to make some changes manually to activate the CoreDNS server; follow these steps on the Netmaker server:

{% stepper %}
{% step %}
Make sure that UDP Port 53 and TCP Port 53 are allowed to pass in the network where your Netmaker server lies.
{% endstep %}

{% step %}
Disable systemd-resolved (Reason: to avoid port conflict with CoreDNS server):

```plaintext
sudo systemctl disable systemd-resolved.service
sudo systemctl stop systemd-resolved
```

{% endstep %}

{% step %}
Make sure `network_mode: host` is set on the CoreDNS container spec in `/root/docker-compose.yml` and run:

```plaintext
docker-compose up -d
```

{% endstep %}
{% endstepper %}

You can now point any machine in the network to use this DNS server and reach other peers by their domain names.

For external clients running Linux, make sure `resolvconf` is installed before setting the WireGuard configurations.

Refer to your operating system documentation for information about how to configure custom DNS network settings. General help guides:

* Linux: <https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-linux.html>
* Mac: <https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-mac.html>
* Windows: <https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-win.html>

If your machine is virtually hosted in a cloud, refer to your VM provider’s documentation on how to permanently set the custom DNS resolver.

## Summary

* v1.1.0+ introduces full DNS management in the UI: nameservers, split DNS (Match Domain), forced queries, and peer scoping.
* Managed DNS records give each node a predictable hostname.
* Legacy CoreDNS configs are only needed for older versions.

![](https://docs.netmaker.io/Base64-Image-Removed)


# Gateways

Secure routing and access across any network barrier

{% embed url="<https://www.youtube.com/watch?v=_FZhBhIbUvc>" %}

## Introduction

Gateways are a unified approach to providing several advanced features for secure user connections reliable network access behind restrictive networks (CGNAT, Double NAT, or firewalls) and more.

How Gateways work:

* WireGuard Clients - Allows unmanaged devices (smartphones, laptops, desktops, routers, IoT devices) to securely connect to a Netmaker network via WireGuard.
* Relay / Auto Relay - For devices behind CGNAT, Double NAT, or restrictive firewalls, Relay functionality routes traffic through a gateway to maintain connectivity when direct access isn’t possible.
* Internet Gateway - Provides full tunnel access to the internet for connected devices via the Gateway.
* User Access - The Gateway is how your end users will access the network over Netmaker Desktop and Mobile.

## How Gateways Work

A Gateway is a publicly reachable node in your Netmaker network that performs one or both of the following functions:

* Remote Access: Provides entry for Remote Access Clients using the Netmaker Desktop App or WireGuard configuration files. These clients connect to the gateway to securely access network services.

<figure><img src="/files/d1CnwWNtvjPs7jNOqrLR" alt=""><figcaption></figcaption></figure>

* Relay: Routes traffic for nodes that cannot establish direct peer-to-peer connections due to network restrictions (e.g., NAT or firewalls).

<figure><img src="/files/1SMULmHg34ZCIyw2ZEyD" alt=""><figcaption></figcaption></figure>

## Configuring a Gateway

{% stepper %}
{% step %}

### Create a Gateway

* Navigate to the Gateways interface of your network in the Netmaker dashboard.

<figure><img src="/files/JADr89375ixa3tgZlRH9" alt=""><figcaption></figcaption></figure>

* Click Create Gateway and select a node to act as the gateway. This node must have a public IP address (not behind a NAT).
  * If unsure, the Netmaker server is a good default choice.

<figure><img src="/files/K9HFX8SsTlh43PcdJV7h" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Internet Gateway

Starting from Netmaker v1.0.0, an Internet Gateway option is available from the Gateways screen. This lets designated gateway nodes route traffic from your Netmaker network to the public internet (e.g., full-tunnel VPN access for remote clients).

* Only Linux devices can be configured as Internet Gateways. Windows, macOS, and Linux devices can connect to an existing Internet Gateway.
* Remote clients can connect to Internet Gateways using WireGuard config files, the Netmaker Desktop app, or the mobile Client App.

Creating an Internet Gateway:

* Go to the Gateways interface.

<figure><img src="/files/t795GSRsW3sjoTwQ1R6F" alt=""><figcaption></figcaption></figure>

* Click Create Gateway.
* Select a Linux node with a public IP to act as the Internet Gateway.

<figure><img src="/files/RKXVWM11AA0ZdBDstjg1" alt=""><figcaption></figcaption></figure>

* Toggle the Internet Gateway option.

<figure><img src="/files/FgbOKbp9hNlLkJtf827V" alt=""><figcaption></figcaption></figure>

* Click Create Gateway to finalize setup.

Notes:

* A node can only be connected to one Internet Gateway, regardless of how many networks it's in.
* A node connected to an Internet Gateway cannot itself act as a gateway (chaining is not supported).
  {% endstep %}

{% step %}

### Connecting Nodes to an Internet Gateway

* Click the gateway entry in the Gateways table to expand its details.
* Click the Connected Nodes tab.
* Click Add Connected Nodes.

<figure><img src="/files/hYOfMsZUlk8xIGFAjmH1" alt=""><figcaption></figcaption></figure>

* Select one or more nodes to route traffic through this Internet Gateway.

<figure><img src="/files/XaX3eZRZiymPngKcPw2j" alt=""><figcaption></figcaption></figure>

Default behavior:

* Connected nodes are placed in split tunnel mode (only internal/VPN traffic routes through the gateway; regular internet traffic uses their local network).

To enable full tunnel mode (route all traffic, including internet-bound), toggle Route All Traffic on the connected node entry.

<figure><img src="/files/JsmRGTbeUU988V1yARxK" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Removing an Internet Gateway

* Navigate to the Gateways interface.
* Click the meatballs menu (⋯) on the gateway and select Edit to open the edit modal.
* Toggle off the Internet Gateway switch.
* Save your changes.
  {% endstep %}
  {% endstepper %}

## Relay Configuration

{% stepper %}
{% step %}

### Adding Relayed Nodes

* Navigate to the Connected Nodes tab of your created Gateway.

<figure><img src="/files/j21UnDxN77MsYwdsMyET" alt=""><figcaption></figcaption></figure>

* Click Add Connected Node and select the node that requires relaying.

<figure><img src="/files/YQN1JEBDrFSvPZqHP9zY" alt=""><figcaption></figcaption></figure>

* The selected node will now route its traffic through the gateway.

<figure><img src="/files/39iAJQ29HjPkiilsBubB" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Relay Node on Enrollment

When adding a new node to the network, you can pre-configure it as a relayed node by:

* Generating an enrollment key and specifying the relay and network.

<figure><img src="/files/3F5hQ3zYFGbNfOBdZQ4R" alt=""><figcaption></figcaption></figure>

* Using the enrollment key during node setup to automatically configure it as a relayed node.
  {% endstep %}
  {% endstepper %}

## Create WireGuard Config Files

{% stepper %}
{% step %}

### From the Nodes Interface

* From the left sidebar, open the Nodes page and click on the Config File tab.
* Click +Add config file.

<figure><img src="/files/QPoEAoBdvHeA3lAxJhOs" alt=""><figcaption></figcaption></figure>

* Fill in the required details:
  * Node name: Assign a unique name to identify the client.
  * Gateway: Select the gateway the node should connect to.
  * Public Key (Optional): Use a client-specific public key if available.
  * DNS (Optional): Define a custom DNS server for the client.
  * Address (Optional): Specify a static IP address or subnet for the node.
  * Additional Addresses (Optional): Add multiple IP addresses if required.
  * Post Up / Post Down (Optional): Include optional scripts to run when the client connects or disconnects.

<figure><img src="/files/kjMoedkmSO63dfC3ysXx" alt=""><figcaption></figcaption></figure>

* Click Create Config to add the node.
* The node will appear under the Nodes list and its configuration can also be found in the gateway’s Conf Files tab.

<figure><img src="/files/Q0C9yzkoEMheNARDIRPc" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### From the Gateway’s Conf Files Tab

* Click Create Config in the Conf Files tab of your gateway.

<figure><img src="/files/z0O9LbiSgYYyT2F5WCGM" alt=""><figcaption></figcaption></figure>

* Optionally configure the following parameters (leave blank for auto-generation):
  * Name: Assign a unique name to the client.
  * Public Key: Enhance security with a client-specific public key.
  * DNS: Specify a custom DNS server for the client.
  * Additional Addresses: Assign multiple IP addresses to the client.
  * Post Up: Add a custom script to execute after the client connects.
  * Post Down: Add a custom script to execute after the client disconnects.

<figure><img src="/files/SlyJN68ZQIZ3msj0jTbi" alt=""><figcaption></figcaption></figure>

* Download the WireGuard configuration file (conf file) or scan the QR code for unmanaged devices (routers, IoT devices, desktops) that support WireGuard.

Once configured, the external client can securely connect to the network through the gateway. You can disable or delete the client at any time from the Nodes interface.
{% endstep %}
{% endstepper %}

Example WireGuard configuration:

{% code title="example.conf" %}

```plaintext
[Interface]
Address = 100.70.101.254/32,fd3c:2f98:6bb1:2e37:ffff:ffff:ffff:fffe/128
PrivateKey = UJBMEgy5KlWq/lpDy/3k2FewP1nlSjchOkIhYazA+Fo=
MTU = 1420
DNS = 1.1.1.1

[Peer]
PublicKey = KsHJHPJO4b6sviElK1XdGkw3M+oQFYJbVKnXBlLGGFA=
AllowedIPs = 100.70.101.0/24,fd3c:2f98:6bb1:2e37::/64,192.168.1.0/24
Endpoint = 134.122.28.173:443
PersistentKeepalive = 20
```

{% endcode %}

## Connected Users

You can view and manage connected desktop clients from the Nodes screen.

<figure><img src="/files/pLNwSCwUBFF39PpIUpuT" alt=""><figcaption></figcaption></figure>

The Connected Users tab under your gateway provides another way to monitor and manage connections established via the Netmaker Desktop App.

<figure><img src="/files/ytv1v0iPBefSDLBO0kjo" alt=""><figcaption></figcaption></figure>

For each connected user, you can:

* View their WireGuard configuration file.
* Delete the node if required.

## High Availability (HA) Gateways

### Overview

High Availability (HA) Gateways, introduced in version 1.2.0, add automatic gateway selection and failover switching. Nodes can automatically connect to the best available gateway and seamlessly switch when their current gateway becomes unavailable, improving reliability, uptime, and ease of management.

### How HA Gateway Works

* Nodes can have their gateway mode set to Auto.
* Netmaker periodically checks gateway availability and latency (approximately every 30 seconds).
* The node connects through the nearest and healthiest gateway.
* If that gateway goes down, the node reconnects through another available gateway seamlessly.

### UI Configuration Example

* When viewing network devices, click Assign Gateway next to any node to open the gateway selection menu.

<figure><img src="/files/SyjusxD2US1Bl4bQkUZo" alt=""><figcaption></figcaption></figure>

* In the Assign Gateway window, toggle Auto-select Gateway to let Netmaker automatically pick the best available gateway for that node.

<figure><img src="/files/r8rIYpTlDXIob84UptRX" alt=""><figcaption></figcaption></figure>

* Toggle **Auto-select Gateway** to enable automatic gateway selection for this node.
* When enabled, Netmaker will automatically choose the **best available gateway**.
* The peer will automatically **switch gateways** when its current one is offline.

<figure><img src="/files/iM3LBpXwg1VO7DS0Fnwo" alt=""><figcaption></figcaption></figure>

### Notes

* Introduced in Netmaker v1.2.0
* Gateway status checks occur approximately every 30 seconds.
* Currently labeled as BETA.
* Switching happens seamlessly — users won’t notice the transition.
* Works best in multi-gateway or distributed environments.

### Use Case Examples

* Server Clusters: Redundant gateways ensure zero downtime during maintenance or outages.
* Multi-site VPN Networks: Automatically route client traffic through the nearest or most responsive gateway.
* Remote Workers: As clients move between locations, Netmaker automatically connects them to the gateway with the lowest latency.
* IoT Devices: Field units maintain connectivity even when one gateway goes offline.

## Auto-Relay (Pro)

Automatically routes traffic through the closest, lowest-latency gateway.

{% hint style="info" %}

#### Overview

The **Auto-Relay** feature (formerly called Failover) allows multiple gateways to act as relays for peers, making the network more flexible and resilient.

Key points:

* Multiple auto-relays can be configured simultaneously.
* Peers automatically select the relay with the **lowest latency**.
* All gateways are **auto-relay enabled by default**, meaning any new gateway can act as a relay immediately.
* **Useful in NAT scenarios:** Auto-Relay is especially beneficial when nodes are behind CGNAT, Double NAT, or restrictive firewalls, where direct peer-to-peer connections may fail.
  {% endhint %}

## How Auto-Relay Works

{% stepper %}
{% step %}

### Gateway advertisement

Each gateway advertises its Auto-Relay status across the network.
{% endstep %}

{% step %}

### Reachability & latency measurement

Peers evaluate which gateways are reachable and measure latency.
{% endstep %}

{% step %}

### Relay selection

Peers connect through the active Auto-Relay gateway with the lowest latency.
{% endstep %}

{% step %}

### Automatic failover

If that gateway becomes unavailable, the peer automatically switches to another reachable Auto-Relay gateway.
{% endstep %}
{% endstepper %}

This creates **dynamic redundancy** and ensures smooth network performance **without manual failover setup**.

## Default Behavior

* Every new gateway is automatically set as **Auto-Relay = ON**.
* You can view or edit this setting in the **Edit Gateway** modal.
* Manual configuration is optional — Auto-Relay works automatically across gateways.

{% hint style="info" %}

### Notes

* Auto-Relay replaces the older Failover logic but **retains backward compatibility**.
* Any gateway can act as a relay without explicit assignment.
* Latency-based routing **balances network load** and maintains optimal data flow.
* Particularly **helpful when NAT or firewall restrictions prevent direct peer-to-peer connections**.
  {% endhint %}


# User Management

{% embed url="<https://www.youtube.com/watch?v=94VhOoqGd1s>" %}

**Superadmin Signup**

When you start Netmaker for the first time, you will be prompted to create a superadmin account from the UI like below

![](/files/WMGhEZxwGX4HNKeyn6WP)

Input your username and a super memorable but strong password then click on the Sign up button. Once you’ve signed up, you can login to your Netmaker server with the account.

![](/files/TyIu3aSqxVQtrmLG6msk)

Another user type that exists in netmaker CE is “admin“. A user with admin role has equal capabilities as the superadmin, except the creation of other admins and transfering super-admin priviledges.

## User Access Tokens

#### Overview

User Access Tokens are used to generate **Bearer tokens** that enable programmatic access to API resources on a Netmaker server. These tokens are designed to support non-interactive authentication workflows, particularly in environments that rely on automation and scripting.

![](/files/Qws3rFqGFlrbhqSonPJq)

#### Purpose and Use Cases

User Access Tokens are especially useful in scenarios involving:

* Automated scripts
* CI/CD pipelines
* Infrastructure management tools
* Programmatic integrations with the Netmaker API

By using access tokens, applications and scripts can authenticate securely without requiring interactive user login.

#### Token Generation

User Access Tokens can be generated under the following conditions:

* Tokens may be created for **existing user accounts**.
* Tokens may also be generated **during account creation**.
* **Multiple tokens** can be generated for a single account.
* Each token is issued with an **explicit expiration date**, after which it becomes invalid.

![](/files/Ohf44Zu9XZDhrvSlPFUV)

#### Permissions and Scope

* The **access scope** of a User Access Token is strictly limited to the **role and type of account** for which it was generated.
* Tokens do not grant privileges beyond those assigned to the associated user account.

#### Authorization to Generate Tokens

The ability to generate User Access Tokens is restricted as follows:

* **Super Admins**, **Owners**, and **Admins** are permitted to generate tokens.
* **Admins** are limited to generating **one token per non-admin user**.
* Admins cannot generate multiple tokens for the same non-admin account.

#### Token Lifecycle and Revocation

* If a user account is **disabled** or **deleted**, all tokens associated with that account can no longer be used for access.
* If an **admin account** is **deleted** or **demoted to a non-admin account**, **all tokens generated by that admin account are automatically deleted**, regardless of which users they were issued for.

{% hint style="warning" %}
Security Considerations

* Tokens should be treated as sensitive credentials and stored securely.
* Expiration dates should be configured according to the principle of least privilege.
* Regular token rotation is recommended, especially for long-running automation workflows.
  {% endhint %}

## Users in Netmaker Professional

Since v0.25.0, Netmaker Professional offers a more capable user management feature. Server administrators can create different kinds of users (admins, platform users and service users) and group them for easier management.

Check the “Users in Netmaker Professional“ section for more information

#### Using the Netmaker Desktop Application

Users are required to sign in using their assigned credentials. Alternatively, social login options are available.

![](/files/bZttlCTdTrKSaaQXm9mg)

After successful login you will be shown all the networks and gateways you have given access to, so now you will be able to connect/disconnect/refresh your connection to a gateway. Internet gateways are depicted with a globe icon. An internet gateway can be used to route all your traffic through the gateway, this is useful if you want to access the internet without exposing your public IP address. This behaves like a traditional VPN.

![](/files/YpxreQzVeQHungqGQygE)

&#x20;

## User Management in Netmaker Professional

The User Management features in Netmaker Professional are designed to streamline the administration of user roles, permissions, and access levels within a platform. This system allows super admins to create and manage user accounts with varying levels of access, ensuring appropriate permissions for tasks. Supported user types include super admins, admins, service users, and platform users, each with distinct capabilities.

User accounts can be created via invitation or direct addition. Super admins assign Platform Access Levels (PAL) to determine access across the platform. Admins can manage user roles, invite users, and oversee network configurations; service users are limited to specific tasks without dashboard access (commonly used for remote access via the Netmaker Desktop app).

The system also supports network roles and groups for more granular access control. Admins can create network-specific roles and assign them to users or groups to simplify permission management across teams and projects.

User types and platform access levels:

* Super Admin: Full control over the platform, including creating and managing other user types and permissions.
* Admin: High privileges to manage accounts, assign roles, and handle network configuration, but cannot create other admins.
* Platform User: Dashboard access and ability to interact with assigned resources as permitted.
* Service User: No dashboard access; permissions adjustable by Super Admins/Admins. Typical use: remote access via Netmaker Desktop app.

## Adding users

There are two ways to create a user:

{% stepper %}
{% step %}

### Basic Auth

This method is suited for creating individual users directly. The admin provides a username and password, assigns groups, then clicks Create User.

Click on "Add a User" then choose "Create User"

![](/files/urAbppWjVRmSwzmKT1iH) ![](/files/oX2cGKTKsMZh3GXhjPfs)
{% endstep %}

{% step %}

### User Invite

This method is suited for inviting multiple users. The admin enters email addresses of users to invite and assigns them to a group.

Invited users receive an email with a link to create their account and are assigned the groups set by the admin during invite. For Netmaker on-prem deployments, ensure the SMTP client is configured to send emails.

![](/files/AIlImfmSe7hvVoaESexo)
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Note:

* Starting from Netmaker version 0.90.0, SMTP configuration is managed via Settings → Email Configuration.  See the official guide: <https://learn.netmaker.io/how-to-guides/how-to-secure-it-operations-with-netmaker#setting-up-smtp-self-hosted>
  {% endhint %}

<figure><img src="/files/b2s4Kazem6WSpYXhnxCi" alt=""><figcaption></figcaption></figure>

## User Groups

User grouping in Netmaker Professional allows admins to organize users by department, role, project, or other attributes, simplifying permissions and access control.

Think of a group as a collection of network roles.

How it works:

* Group Creation – Administrators create groups based on needs.
* User Assignment – Users are added to one or more groups.
* Permission Management – Permissions are assigned to groups via network roles, reducing per-user configuration.
* Inheritance – Users inherit the combined permissions of all their groups.

A group's permissions come from the network roles assigned to it. Users can belong to multiple groups; their effective permissions are additive.

### Associated Network Roles

The Associated Network Roles section defines per-network access levels:

* Admin – Full access, including managing devices and users.
* User – View-only access.
* n/a – No access to that network.

Assigning roles per network enables fine-grained control over visibility and management rights.

For a visual guide on creating and managing users, roles, and groups, see the User Interface section of the docs: <https://docs.netmaker.io/docs/references/user-interface#users\\_\\_user-groups>

## Provision Users and Groups from Your Identity Provider

Managing private network access can become complex at scale. Manual provisioning and membership maintenance are time-consuming and error-prone.

Netmaker’s Identity Provider (IdP) Integration automates user and group management by synchronizing with your enterprise IdP. This ensures permissions remain accurate across private networks without manual effort. Benefits include simplified onboarding/offboarding, reduced administrative overhead, improved compliance, and Single Sign-On (SSO).

Note: IdP integration is available only for self-hosted Pro tenants. For managed tenant support, contact: <https://www.netmaker.io/contact>

### Supported Identity Providers

Netmaker supports native synchronization with:

* Microsoft Entra ID (Azure AD)
* Google Workspace
* Okta

### Features

#### Single Sign-On (SSO)

Users can log in via their IdP credentials, replacing local password management.

#### Automatic User and Group Sync

* Users: Synchronized as service-users by default (no dashboard access unless promoted).
* Groups: Memberships are imported.
* Prefix Filtering: Admins can limit which users/groups are imported via prefixes.
* Sync Frequency: Default every 24 hours; adjusted via IDP\_SYNC\_INTERVAL environment variable (e.g., 30m, 1h, 6h, 12h, 24h).

Admins can manually trigger sync via the Settings page.

#### Self-Onboarding via IdP Sign-In

If auto-sync is disabled or incomplete:

* Users may sign in with IdP credentials.
* Only users from allowed email domains may attempt sign-in.
* On first login, accounts are created in a "pending approval" state and require admin approval.

#### Automatic Suspension

If a user is suspended or disabled in the IdP, Netmaker prevents their login attempts automatically.

### Setup Guides

* Integrating Google Workspace: <https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide#integrating-google-workspace>
* Integrating Microsoft Entra ID (Azure AD): <https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide#integrating-microsoft-entra-id-azure-a-d>
* Integrating Okta: <https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide#integrating-okta>
* Integrating GitHub: <https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide#integrating-github>
* Integrating Generic OpenID (OIDC) Provider: <https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide#integrating-generic-openid-oidc-provider>

{% hint style="warning" %}
Caution: Removing your IdP configuration cannot be undone without reconfiguration. Proceed carefully.
{% endhint %}

## Transferring super admin rights

Super admin privileges can only be transferred to another administrator. On the User Management page, click the three dots next to the super admin user and select **“Transfer Super Admin”** A dialog box will appear, allowing you to choose an admin to assign the super admin role.

<figure><img src="/files/Jr3YkXzh1vL6WbYQxT1T" alt=""><figcaption></figcaption></figure>

## Controlling User Sessions

Admins can define session time limits to automatically enforce session expiration for security and performance.

Key features:

* Customizable Timeout: Configure durations (e.g., 2 hours, 5 hours).
* Automatic Session Expiration: Sessions expire after the set period.
* Seamless User Experience: Expired sessions log users out and redirect to login.

How it works:

{% stepper %}
{% step %}

### Configure Timeout

Set the session timeout under Settings → Security & Authentication by defining the JWT Validity Duration parameter (in minutes) to specify session length.

![](/files/ljT6pqTWwnZemVkAjLFJ)
{% endstep %}

{% step %}

### Auto Disable User Connection

Enable Auto Disable User Connection under Settings → System Configuration to enforce Netmaker Desktop app session expiration.

![](/files/kjl4u9H3M1dHgnDV28J5)
{% endstep %}

{% step %}

### Expiration and Logout

When the timeout expires, the system logs out the user, terminates the session, and clears session state securely.
{% endstep %}
{% endstepper %}

Benefits:

* Enhanced Security: Reduces risk from idle sessions.
* Compliance: Helps meet policies requiring session timeouts.
* Resource Efficiency: Frees resources by closing inactive sessions.

## User Access Tokens

### Overview

User Access Tokens generate Bearer tokens for programmatic access to the Netmaker API, supporting non-interactive authentication for automation and scripting.

![](/files/13SHcpey6dOCFXzXYAHk)

### Purpose and Use Cases

Common for:

* Automated scripts
* CI/CD pipelines
* Infrastructure management tools
* Programmatic integrations with the Netmaker API

### Token Generation

* Tokens can be created for existing user accounts or during account creation.
* Multiple tokens can exist for a single account.
* Each token has an explicit expiration date.

![](/files/3rMTVL4O2qYVbIbZyhxB)

### Permissions and Scope

* Token scope is limited to the role and type of the account it was generated for.
* Tokens do not grant privileges beyond the associated user account.

### Authorization to Generate Tokens

* Super Admins, Owners, and Admins can generate tokens.
* Admins are limited to generating one token per non-admin user.
* Admins cannot create multiple tokens for the same non-admin account.

### Token Lifecycle and Revocation

* If a user account is disabled or deleted, all tokens for that account become invalid.
* If an admin account is deleted or demoted to non-admin, all tokens generated by that admin are deleted, regardless of target users.

### Security Considerations

* Treat tokens as sensitive credentials; store securely.
* Configure expirations following the principle of least privilege.
* Regular token rotation is recommended for long-running automation.


# Keys

Create, manage, and control enrollment keys used for secure device on-boarding across networks.

## **Overview**

Enrollment keys are used to securely authenticate and onboard devices into your networks. Each key defines which network a device may join and provides a controlled way to automate provisioning at scale.

The **Keys** page centralizes the management of all enrollment keys across your tenant, allowing administrators to review, create, rotate, disable, or delete keys as needed.

***

## **Auto Generated Keys**

When a new network is created in Netmaker, the platform automatically generates a default enrollment key for that network. This ensures that each network is immediately ready for device on-boarding without requiring any manual configuration.

![](/files/wTwJ6UupDs3WCjfs2oYP)

These keys inherit the network’s name and appear in the list as examples such as:

* **IoT Network**
* **Netmaker**
* **Private Mesh**
* **Turbo Link**
* **Zero Path**

Auto-generated keys are:

* **Pre-linked to their respective networks**
* **Valid by default**
* **Configured with unlimited expiration**

## Default Enrollment Keys

Enrollment keys are used by devices to join a network via the Netclient. Administrators can assign a **Default Enrollment Key** to each network to streamline and standardize device onboarding.

Each network can have **only one Default Enrollment Key at a time**. When set, this key is automatically used for device enrollment into that network unless another key is explicitly selected during the enrollment process.

When a Default Enrollment Key is configured, it **replaces the use of Auto Generated Keys as the default onboarding method** for that network, ensuring consistent and controlled provisioning behavior.

#### Key capabilities

* Each network supports only **one default enrollment key**
* Overrides Auto Generated Keys as the default onboarding mechanism for that network
* Automatically used for device enrollment unless another key is explicitly selected
* Administrators can change the default key at any time by selecting a different key
* Key tokens can be regenerated without recreating the key, maintaining continuity while improving security

#### Example

**Set as Default**

Use this action to designate a key as the default enrollment key for a network.

<figure><img src="/files/disjzHJG3QiMjeKNsFlJ" alt=""><figcaption></figcaption></figure>

## Key Token Regeneration

Administrators can regenerate a key’s token without recreating the key itself. This allows the existing key configuration (network assignment, settings, tags, and permissions) to remain unchanged while issuing a new secure token for device enrollment.

This is useful for maintaining continuity in deployments while rotating credentials for security or operational reasons.

#### How to regenerate a token

To regenerate a key token, open the desired key and click **Regenerate token**.

<figure><img src="/files/qKswQ2OirGvFvtE2vQn9" alt=""><figcaption></figcaption></figure>

Administrators can also regenerate a key token from the key list. Locate the desired key, click the **More (⋮) menu**, then select **Regenerate token**.<br>

<figure><img src="/files/UCJkF1jRqolx4e8vMh9F" alt=""><figcaption></figcaption></figure>

#### Key capabilities

* Regenerate key tokens without modifying the key configuration
* Preserve all existing settings, including networks, tags, and restrictions
* Maintain continuity for existing workflows while improving security
* Useful for credential rotation and incident response scenarios

## Managing Keys

### Creating a Custom Key

You may create additional keys to support use cases such as:

* **Temporary contractor access** – Issue time-bound keys that expire automatically
* **Short-lived staging environments** – Create limited-use keys for testing and development
* **Separate keys per team or device group** – Organize enrollment by department or function
* **Multi-network access** – Generate a single key that grants access to multiple networks simultaneously
* **Auto-tagging devices** – Automatically apply tags to devices during enrollment for easier organization and policy management
* **Auto-relay configuration** – Enable automatic gateway selection to relay traffic for devices behind restrictive firewalls or NAT

To create a new key:

{% stepper %}
{% step %}

### Navigate to the Keys interface

![](/files/3IeR6Wbw40dqjEAcPdqU)
{% endstep %}

{% step %}

### Click Create Key

{% endstep %}

{% step %}

### Enter a descriptive Name for the key

{% endstep %}

{% step %}

### Select the Type

* **Unlimited** – Key can be used without restrictions
* **Limited number of uses** – Key can only enroll a specific number of devices
* **Time bound** – Key is only valid until a specific date and time
  {% endstep %}

{% step %}

### Choose the target Network(s)

Select one or multiple networks devices can join.

<figure><img src="/files/VaYHoX92a8X5KST9vltR" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### (Optional) Enable Auto-select Gateway

Automatically assign the best available gateway.

![](/files/F12yeezGzBpleJZUQ10j)
{% endstep %}

{% step %}

### (Optional) Select a specific Gateway

Assign a specific gateway for devices using this key.

![](/files/08FaJlJZIw0fmerdwXHq)
{% endstep %}

{% step %}

### (Optional) Assign Tags

Tags will be automatically applied to all devices enrolled with this key.

![](/files/4l3f6G3V95VD7XouTAuh)
{% endstep %}

{% step %}

### Create the key and distribute securely

Click **Create Key** and securely distribute to authorized devices.

Keys that provide access to multiple networks or include pre-configured tags streamline device provisioning and reduce manual configuration overhead.
{% endstep %}
{% endstepper %}

### Editing Keys

Administrators can modify any key—including auto-generated ones—at any time. Permitted modifications are limited to **Gateways**, **Auto-select Gateway,** and **Tags**.

<figure><img src="/files/CkXHT8P3UpCmbuKv7vAB" alt=""><figcaption></figcaption></figure>

### Revoking Access

Keys can be deleted instantly. Expired keys cannot be used for new device enrollments.

<figure><img src="/files/5QF2jGtibrh1jf652xNW" alt=""><figcaption></figcaption></figure>

## Best Practices

Follow these best practices to manage enrollment keys effectively.

* **Apply expiration dates for temporary deployments** such as contractor projects or staging environments
* **Immediately delete keys that are no longer needed or may be compromised** to prevent unauthorized access
* **Leverage tags for automatic device organization** to streamline management and policy enforcement
* **Periodically regenerate key tokens** to reduce exposure risk and enforce credential hygiene.
* **Share keys through secure channels** like password managers or encrypted communication, not email or chat
* **Use descriptive naming conventions** that indicate purpose, team, and time period at a glance


# Multi-Factor Authentication

MFA adds a second verification step to secure your account

### Overview

Starting with **Netmaker v1.0.0**, **Multi-Factor Authentication (MFA)** is available to enhance account security. MFA adds a secondary verification step, helping prevent unauthorized access even if user credentials are exposed.

MFA is supported in both **Community Edition (CE)** and **Pro**, can be enforced globally by administrators, and is currently available **only for on-premises deployments**.

### How MFA Works

When MFA is enabled, users must provide:

* Their username and password (first factor).
* A time-based one-time password (TOTP) code from an authenticator app.

After entering your credentials, you will be prompted for a 6-digit verification code from your authenticator app before gaining access.

### Compatible Authenticators

Netmaker’s MFA uses the **TOTP standard**, meaning you can use **any TOTP-compatible authenticator app**, such as Google Authenticator, Authy, Microsoft Authenticator, or similar. If it supports TOTP, it will work with Netmaker.

### Enabling MFA for Your Account

You can enable Multi-Factor Authentication (MFA) to add a second layer of security to your Netmaker account.

{% stepper %}
{% step %}

### Open Account settings

In the Netmaker web UI, click on your profile icon in the lower-left corner and select **Account** from the menu.

![](/files/e7KcYG0M0XinQWVndTxS)
{% endstep %}

{% step %}

### Start setup

Click **Enable MFA**, then in the modal click **Start setup** and enter your password to continue.

![](/files/Ihksgb3brqBDVQYb0v7l)
{% endstep %}

{% step %}

### Scan the QR code

A QR code will be displayed — scan this code using your preferred TOTP-compatible authenticator app.

![](/files/pOs0xaRr6fcCcLPfaZ4W)
{% endstep %}

{% step %}

### Verify

Enter the 6-digit code from your authenticator app to verify, then click Done.
{% endstep %}
{% endstepper %}

### Global Enforcement

Administrators can require MFA for all users through global policy settings in the admin interface. Once enforced, users will be prompted to set up MFA at their next login.

To enable MFA enforcement, go to **Settings** > **Security & Authentication**, then switch on the **Enforce Multi-factor Authentication** toggle.

![](/files/4b1CNG6pXyG3OTlwo2S5)

### Logging in with MFA

After MFA is set up, the login process requires:

* Username & password
* TOTP verification code

If either factor is incorrect, access is denied.

### Resetting MFA

{% stepper %}
{% step %}

### Open Account settings

Log in with your MFA credentials. Click on your profile icon in the lower-left corner and select **Account** from the menu.
{% endstep %}

{% step %}

### Reset MFA

Click **Reset MFA**.
{% endstep %}

{% step %}

### Confirm

Confirm your password to complete the change.
{% endstep %}
{% endstepper %}

### Recovering Access

If you lose access to your authenticator app, you will need to contact your Netmaker **super administrator** for assistance. The super administrator can disable MFA for your account, allowing you to log in again and reconfigure MFA as needed. This prevents permanent lockouts and ensures you can securely restore access to your account.

### FAQs

<details>

<summary>Can MFA be enforced organization-wide?</summary>

Yes — administrators can enforce MFA globally for all users.

</details>

<details>

<summary>Is SMS-based MFA supported?</summary>

No — only TOTP-based MFA is supported in this version for enhanced security.

</details>


# Conditional Access

{% embed url="<https://media.netmaker.io/features/Conditional-Access.mp4>" %}

Providing network access always introduces a level of risk. Netmaker mitigates these risks through Zero Trust principles, which are implemented across a variety of features like SCIM Integration, MFA, and Access Controls.

Our features listed here under **Conditional Access** enable administrators to set additional conditions for network access, whether it's to meet compliance goals, or simply to enhance the safety of their networks.&#x20;

#### **Posture Checks**

Posture Checks enable administrators to set specific device requirements for their users, such as operating system and geolocation.

{% content-ref url="/pages/42b605135713d0ac1e93ead787ad27c424c18056" %}
[Posture Checks](/features/conditional-access/posture-checks)
{% endcontent-ref %}

#### **Device Approvals**

Device Approvals allow administrators to review specific devices before they are added to the network.

{% content-ref url="/pages/LvsUpOcc9tUXpP5cUMNn" %}
[Device Approvals](/features/conditional-access/device-approvals)
{% endcontent-ref %}

#### **Just-in-Time Access**

JIT Access provides a workflow in which users request temporary access, and administrators grant authorization for a limited time.&#x20;

{% content-ref url="/pages/P0TDrmpmeN5Mhkp4nOLF" %}
[Just In Time Access](/features/conditional-access/just-in-time-access)
{% endcontent-ref %}


# Posture Checks

Automated device compliance verification for network security

{% hint style="info" %}
PRO FEATURE — Posture Checks is available on Netmaker Pro

Status: BETA\
Minimum Client Version: 1.4.0 and above
{% endhint %}

### Overview

Device Posture Checks provide a **policy-driven mechanism** to evaluate the security and system state of client devices based on reported attributes. The goal is to ensure that only devices meeting defined posture requirements are considered compliant and allowed to operate within the platform.

This feature is intended to support **Zero Trust principles**, continuous compliance monitoring, and controlled access enforcement.

### What are Posture Checks?

Posture checks are security policies that validate device attributes against defined criteria. When a device fails to meet these requirements, it's flagged as non-compliant, allowing administrators to enforce security policies and maintain network integrity.

### Key Benefits

* **Enforce security standards** across all network devices
* **Prevent unauthorized access** from non-compliant devices
* **Monitor compliance** in real-time
* **Automate security policy** enforcement
* **Reduce security risks** from outdated or misconfigured devices

### Interface Overview

![](/files/zo8KH5QxXipRiHim3Ulr)

The Posture Checks interface consists of three main tabs:

* **Posture Checks** - Manage and view all posture check rules
* **Non-compliant Nodes** - View devices that fail posture checks
* **Non-compliant Users** - View users with non-compliant devices

Search and Actions

* **Search bar** - Quickly filter posture checks by name
* **Add posture check button** - Create new compliance rules
* **Refresh** - Update compliance status in real-time

### Posture Check Attributes

The following attributes can be validated:

{% stepper %}
{% step %}

### Operating System (OS)

* **Description:** Validates the device's operating system type
* **Use Case:** Restrict network access to approved OS platforms
* **Example Values:** `Android`, `iOS`, `Linux`, `Windows`
  {% endstep %}

{% step %}

### Client Version

* **Description:** Checks the installed Netmaker client version
* **Use Case:** Ensure clients have required features and security patches
* **Example Values:** `1.4.0+`
  {% endstep %}

{% step %}

### OS Version

* **Description:** Validates specific operating system version
* **Use Case:** Prevent outdated OS versions with known vulnerabilities
* **Example Values:** `10.0.26100+`
  {% endstep %}

{% step %}

### Kernel Version

* **Description:** Checks kernel version
* **Use Case:** Ensure systems have security-patched kernels
* **Example Values:** `24.04+`
  {% endstep %}

{% step %}

### OS Family

* **Description:** Groups operating systems by family
* **Use Case:** Apply broad OS category restrictions
* **Example Values:** `iOS`, `Android`, `Unix-like`
  {% endstep %}

{% step %}

### Auto Update

* **Description:** Verifies if automatic updates are enabled
* **Use Case:** Enforce update policies for security compliance
* **Example Values:** `True`, `False`
  {% endstep %}
  {% endstepper %}

### Creating a Posture Check

![](/files/ttEn4HRlLcCuWfCcGCTz)

#### Step-by-Step Guide

{% stepper %}
{% step %}

### Open the Creation Form

Click the **"+ Add posture check"** button in the top right corner of the dashboard.
{% endstep %}

{% step %}

### Enter Basic Information

**Name** (required)

* Provide a clear, descriptive name
* Use naming conventions like: `[Attribute]-[Requirement]`

**Description** (optional)

* Explain what the check validates and why
* Example: *"Ensures devices are running approved operating systems. Devices with unsupported OS types will be denied network access."*
  {% endstep %}

{% step %}

### Configure Check Parameters

**Attribute** (required)

* Click the dropdown to select the device property to validate
* Choose from: OS, Client Version, OS Version, Kernel Version, OS Family, Auto Update
* This determines what gets checked on each device

**Severity Level** (required)

* Select from dropdown: Critical, High, Medium, Low
* Align severity with your security policy priorities
* Consider impact on business operations

**Guidelines:**

* **Critical:** Use for security fundamentals (OS restrictions, auto-updates)
* **High:** Important security features (kernel versions, encryption)
* **Medium:** Standard compliance requirements
* **Low:** Recommended but flexible standards (client version suggestions)
  {% endstep %}

{% step %}

### Define Scope

**Tags** (optional, defaults to "All Resources")

* Select which network resources this check applies to
* Click the tag field to choose from available tags
* Use "All Resources" for network-wide policies
* Target specific tags for granular control (e.g., production servers, guest networks)

**User Groups** (required, defaults to "All Users")

* Select which user groups must comply with this check
* Click the user groups field to choose groups
* Options include:
  * "All Users" - Network-wide enforcement
  * Specific groups (e.g., "developers-network", "stest", "contractors")
* Mix and match for role-based compliance
  {% endstep %}

{% step %}

### Review and Create

* Double-check all settings
* Ensure allowed values match your device inventory
* Click **"Add"** to create the posture check
* The check will immediately become active
  {% endstep %}
  {% endstepper %}

### Monitoring Non-Compliance

#### Visibility on Nodes Interface

**Important:** Violated nodes and users are automatically flagged on the main Nodes screen, providing immediate visibility without switching tabs.

![](/files/MTTxRRXqSVQt6eLNSmE4)

**Visual Indicators:**

* **Warning icon (⚠️)** appears next to device names with posture check violations
* Devices with violations are easily identifiable in your nodes list
* Quick scanning of device status without leaving the main view
* Click on the warning icon **(⚠️)** for detailed violation information

This allows administrators to spot compliance issues at a glance while managing devices, without needing to navigate to dedicated compliance tabs.

#### Non-compliant Nodes Tab

![](/files/XszdSFaQxASmeVaygS6A)

Switch to this tab to view:

* Devices currently failing one or more posture checks
* Which specific checks each device is violating
* Device details (OS, version, user, etc.) for remediation planning
* Centralized view of all violations across your network

#### Non-compliant Users Tab

![](/files/EowLcQORHauD2Ourdx9g)

Switch to this tab to view:

* Users with one or more non-compliant devices
* Aggregate violation counts per user
* Pattern identification (e.g., entire teams with compliance issues)
* User-focused violation grouping for targeted communication

### Search and Filtering

Use the search bar to quickly find specific posture checks:

* Search by name (e.g., "OS", "version", "update")
* Filtering devices by compliance is useful when managing many posture checks

### Best Practices

Start with Critical Checks First

Begin your implementation with high-impact, critical security requirements:

* Operating system restrictions (prevent unauthorized OS types)
* Auto-update enforcement (ensure security patches)
* Minimum client version (guarantee feature support)

### Version Information

* **Feature Status:** BETA
* **Minimum Client Version:** v1.4.0
* **Minimum UI Version:** v1.4.0
* **Minimum Server Version:** v1.4.0
* **Edition Required:** Netmaker Pro


# Device Approvals

Defines how devices are approved and join a network

## Overview

Netmaker provides flexible device enrollment, allowing either automatic joins or admin approval through the Auto-Join setting.

## Network Join Flow

When a device attempts to join a Netmaker network, one of two things happens:

* It joins the network immediately (Auto-Join enabled)
* It waits for admin approval (Auto-Join disabled)

This allows teams to balance speed, automation, and security depending on the use case.

## Auto-Join

![](/files/9LO2ZFis3aH2GVmqfv7z)

### How it works

* When **Auto-Join is enabled**, any device using a valid enrollment key is added to the network instantly. No admin interaction is required; devices appear directly in the **Nodes** interface as active nodes.
* When **Auto-Join is disabled**, devices requesting access are placed in the **Pending Devices** window and require manual admin approval before joining.

### Enable or disable Auto-Join

{% stepper %}
{% step %}

### Navigate to All Networks

Go to the **All Networks** screen.

![](/files/vuBgD44yNbCRBUGKbZNk)
{% endstep %}

{% step %}

### Edit your network

Click **Edit** on the network you want to configure.

![](/files/iij74Mf7q6vHZ63gBUod)
{% endstep %}

{% step %}

### Toggle Auto-Join

Toggle **Auto-Join** on or off.

![](/files/NvJBxoLfCzS5UhrBnTzc)
{% endstep %}

{% step %}

### Save changes

Save the changes to apply the new Auto-Join setting.
{% endstep %}
{% endstepper %}

## Pending Devices

When **Auto-Join is disabled**, device enrollment requests are held for review under **Pending Devices**.

### Accessing Pending Devices

* Navigate to **Networks → Your Network → Nodes**
* Click **Pending devices** in the top-right corner

![](/files/WT88gxqjOLYyyUALuOY4)

* The panel shows how many requests are waiting for review

### What admins can do

From the **Pending Devices** panel, administrators can:

![](/files/Pb6JYq7TqwmvoTFxm7g8)

* **Approve** a device to allow it to join the network.
* **Decline** a device to deny access.
* Review **device name** and **request time** before deciding.

Approved devices immediately appear in the Nodes list and begin participating in the network.

{% hint style="warning" %}
Security Best Practices

* Enable Auto-Join in trusted internal or automated environments.
* Disable Auto-Join for externally accessible networks.
* Regularly monitor the Pending Devices list.
* Decline unexpected or unknown device requests.
  {% endhint %}

## Summary

The **Auto-Join** feature gives administrators control over how devices enter a Netmaker network. Whether prioritizing speed or security, these tools ensure device enrollment aligns with your operational and security requirements. By choosing the right configuration, teams can scale confidently while maintaining visibility and control over network access.


# Just In Time Access

Part of the Enterprise Plan, ideal for organizations requiring more flexibility

### Overview

JIT (Just-In-Time) Access is a security feature that allows network administrators to implement approval-based access control. Instead of granting permanent access to network resources, administrators can require users to request temporary access, which must be approved before the user can connect to the network.

**JIT Access can be enabled for all users or restricted to selected user groups, allowing administrators to apply approval-based access controls only where needed.**

&#x20;

This feature is particularly useful for:

•      Implementing zero-trust security principles

•      Providing temporary access to contractors or external users

•      Enforcing time-limited access to sensitive network resources

•      Maintaining detailed audit trails of network access

&#x20;

### Key Features

#### Request-Based Access

Users must submit a request to access the network, providing a reason for their access need. Administrators review these requests and can either approve or deny them based on business requirements and security policies.

#### Time-Limited Access

Administrators can explicitly set the duration that users are allowed access. This ensures that access automatically expires after the specified time period, reducing the risk of unauthorized or forgotten access permissions.

#### **Group-Based Access Control**

JIT Access can optionally be scoped to specific user groups within a network. Users within the configured groups must request access before connecting to the network.&#x20;

<figure><img src="/files/IESLkEJbnUWtHyfBFsG4" alt=""><figcaption></figcaption></figure>

Users belonging to configured groups must request access before connecting to the network. Upon approval, access is granted for a specified duration and automatically revoked when the approval period expires.

**Flexible Access Control**

Networks can be configured to:

* Require JIT approval for all users (Leave empty)
* Require JIT approval only for selected groups
* Exempt trusted groups from the JIT workflow

#### Request Management Dashboard

<figure><img src="/files/o8TGT7N6wFxb8pUzRttS" alt=""><figcaption></figcaption></figure>

The JIT Requests interface provides a comprehensive dashboard for managing all access requests with the following capabilities:

• View all requests across different states (Pending, Approved, Denied, Expired/Revoked)

• Filter and search through pending requests

• Quick approval or denial actions

• Track request timestamps and remaining time

#### Email Notifications

Email notifications keep both admins and users informed throughout the access request lifecycle:

Admin Notification (Access Request Received):

When a user requests access, the network admin receives an email containing:

• Requesting user name

• Network name

• Reason (if provided)

• Direct link to review the request

&#x20;

<figure><img src="/files/t2Ll2JI7ba1l3IvbCQkR" alt=""><figcaption></figcaption></figure>

User Notification (Access Approved/Denied):

When an admin processes a request, the user receives an email notification with the decision and relevant details.

&#x20;

<figure><img src="/files/6jKnFiqsnggCp60MfTxA" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
*Important: Email notifications depend on your email setup. If you're self-hosting Netmaker, you must* [*configure SMTP*](https://learn.netmaker.io/how-to-guides/how-to-secure-it-operations-with-netmaker#setting-up-smtp-self-hosted) *under server settings first. Without proper SMTP configuration, email notifications will not be sent.*
{% endhint %}

&#x20;

### Configuration

#### Enabling JIT Requests

To enable JIT Requests for a network:

1. Navigate to the JIT Requests interface of your network in the admin dashboard
2. Toggle the feature to 'Enabled'

<figure><img src="/files/GdcUwLi34SlzFG1BekA4" alt=""><figcaption></figcaption></figure>

**Note**: Once enabled, approval will be required before connecting to the network, but only for users accessing it via the [Netmaker Desktop](https://learn.netmaker.io/getting-started/server-and-client-management/client-installation/netmaker-desktop-installation?q=netmaker+desktop).

### User Experience

#### Accessing Networks via Netmaker Desktop

All users interact with JIT-enabled networks through the **Netmaker Desktop** application. The application provides a clean interface showing all available networks and their current access status.

#### Network Display States

In Netmaker Desktop, networks are displayed with different states depending on JIT configuration and current access status:

&#x20;

<figure><img src="/files/eGl04c1nxgdeEbx1Sg8d" alt=""><figcaption></figcaption></figure>

<table data-header-hidden><thead><tr><th width="249" valign="top"></th><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Display</td><td valign="top">State</td><td valign="top">User Action</td></tr><tr><td valign="top">Request button</td><td valign="top">Network requires JIT approval and user has no active access</td><td valign="top">Click 'Request' to submit an access request</td></tr><tr><td valign="top">Access request pending (grey)  </td><td valign="top">Request has been submitted and is awaiting administrator approval</td><td valign="top">Wait for administrator to approve or deny the request</td></tr><tr><td valign="top">Active (green check)</td><td valign="top">Access approved and currently active</td><td valign="top">Users can toggle the connection on or off within the approved access period</td></tr></tbody></table>

#### Requesting Access via Netmaker Desktop

When a user needs to access a JIT-enabled network through Netmaker Desktop:

1\.    User opens Netmaker Desktop application

2\.    User sees the list of available networks

3\.    For **JIT-enabled networks** without active access, a 'Request' button is displayed

4\.    User clicks 'Request' button

5\.    User provides a reason for access in the request dialog

6\.    Request is submitted to administrators for review

7\.    User waits for approval (request appears in admin dashboard as 'Pending')

8\.    Once approved, the network becomes active with a timer showing remaining access time

9\.    User can toggle the connection on/off during the approved time window

&#x20;

**Example from Netmaker Desktop:**&#x20;

<figure><img src="/files/QdJIV6jQ9fVa0I9yeYUH" alt=""><figcaption></figcaption></figure>

'**office-network**' shows a 'Request' button (needs to be requested), '**staging-internal**' displays 'Access request pending' (waiting for admin approval), and '**zero-path**' shows an active connection with toggle controls and an expiration countdown of 29 days and 23 hours.

&#x20;

### Managing Access Requests (Admin Dashboard)

#### JIT Requests Interface Overview

Administrators manage all access requests through the web-based admin dashboard. The request management interface displays all access requests with the following information:

<figure><img src="/files/QmaMO5PFsGACC6sXSC6x" alt=""><figcaption></figcaption></figure>

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Field</td><td valign="top">Description</td></tr><tr><td valign="top">User</td><td valign="top">Email address or identifier of the user requesting access</td></tr><tr><td valign="top">Requested</td><td valign="top">Timestamp showing when the access request was submitted (e.g., '5 minutes ago')</td></tr><tr><td valign="top">Status</td><td valign="top">Current state of the request: Pending, Approved, Denied, or Expired/Revoked</td></tr><tr><td valign="top">Reason</td><td valign="top">User-provided justification for why they need network access</td></tr><tr><td valign="top">Managed By</td><td valign="top">Administrator who processed the request </td></tr><tr><td valign="top">Time Left</td><td valign="top">Remaining duration of approved access </td></tr></tbody></table>

&#x20;

#### Approving Access Requests

To approve a pending access request:

1\. Review the request details including the user, reason, and request timestamp

2\. Click the 'Grant Access' button next to the request

<figure><img src="/files/3sQqxD3kDUZaSFoGWWQl" alt=""><figcaption></figcaption></figure>

3\. Specify the duration for which access should be granted

4\. Confirm the approval

&#x20;

The user will be notified of the approval. In Netmaker Desktop, the network will change from showing a 'Request' status to displaying an active connection with a countdown timer (e.g., 'Access expires in 29d 23h').

<figure><img src="/files/0e63RTXZvUrpUJS2fGIO" alt=""><figcaption></figcaption></figure>

&#x20;

#### Denying Access Requests

To deny a pending access request:

1\. Review the request details

2\. Click the 'Deny' button

<figure><img src="/files/iXNyvtDtCkHYAIiDaytx" alt=""><figcaption></figcaption></figure>

3\. Confirm the denial

&#x20;

The user will be notified of the denial and the 'Request' button will be available in Netmaker Desktop if they need to submit a new request with updated justification.

&#x20;

### Best Practices

#### For Administrators

1. Review requests promptly to minimize user wait times and maintain productivity
2. Set appropriate access durations based on the user's stated need, avoid long or short periods
3. Monitor the Expired/Revoked tab regularly to identify patterns in access requests
4. Use the search functionality to quickly find specific user requests
5. Consider user patterns - if a user regularly requests access, evaluate if a longer duration or different access model is appropriate

&#x20;

#### For Users

1. Provide clear, specific reasons for access requests to expedite approval<br>

   <figure><img src="/files/GLPW1F0rpU7NJYFft7Ve" alt=""><figcaption></figcaption></figure>

2. Request access in advance when possible to account for approval time

3. Monitor your access timer in Netmaker Desktop to know when your access will expire\ <br>

   <figure><img src="/files/5xd2U3lI8tSpoiUgHYEh" alt=""><figcaption></figcaption></figure>

4. Disconnect when finished to demonstrate good security practices, even if time remains

5. Plan ahead for extended work - if you need access for an entire day, mention this in your request reason

&#x20;

### Security Considerations

1. Audit Trail: All requests are logged with timestamps, user information, and reasons, providing a complete audit trail of network access<br>

   <figure><img src="/files/JA86KLnGjy9NAgPedaT3" alt=""><figcaption></figcaption></figure>
2. Principle of Least Privilege: Time-limited access ensures users only have access when needed, automatically revoking permissions after the approved duration
3. Zero Trust Architecture: Supports zero-trust principles by requiring explicit approval for each access instance, never granting permanent access by default
4. Compliance: Helps meet regulatory requirements for access control and monitoring, including SOC 2, ISO 27001, and other security frameworks
5. User Accountability: Requiring users to provide reasons for access creates accountability and discourages unnecessary access requests

&#x20;

### Troubleshooting

#### Users aren't receiving admin emails

1. Confirm email is configured on the server (self-hosted instances must configure SMTP under server settings)
2. Check spam filtering
3. Verify the admin's email address is correct

#### A user can't connect after being approved

1. Confirm the grant hasn't expired - check the countdown timer
2. Ask the user to refresh the network list in Netmaker Desktop
3. Confirm the user is trying to connect to the correct network

*If you experience any difficulties, we’re here to* [*help*](https://www.netmaker.io/contact)*.*

### Common Use Cases

#### 1. Contractor Access

Grant temporary access to external contractors for specific projects or maintenance windows without creating permanent accounts. Contractors use Netmaker Desktop to request access, and administrators can approve time-limited access matching the project timeline.

#### 2. Elevated Privilege Scenarios

Require approval for users needing temporary elevated access to sensitive network segments or resources. Even trusted employees can request JIT access for specific tasks that require higher permissions.

#### 3. Break-Glass Access

Implement emergency access procedures where users can request immediate access for critical situations, with full audit logging. Administrators can quickly review and approve urgent requests while maintaining security oversight.

#### 4. Shift-Based Access

Control access based on work shifts, requiring users to request access only during their scheduled hours. This ensures that off-duty staff don't have lingering network access.

#### 5. Temporary Remote Work

Employees working remotely on specific days can request access for that day only, rather than maintaining permanent VPN access. This is particularly useful for hybrid work environments.

&#x20;

### Technical Details

1. [User Management](https://learn.netmaker.io/features/user-management) enables administrators to create and manage users, assign roles, and control access to networks and resources.
2. [Netmaker Desktop](https://learn.netmaker.io/getting-started/server-and-client-management/client-installation/netmaker-desktop-installation) is the official netmaker client application used by users to securely access private networks, remote resources, and internet access.
3. [Admin Dashboard (NMUI)](https://learn.netmaker.io/references/user-interface?q=netm) is a web-based management interface used by administrators to configure, control, and monitor network resources.

### Summary

JIT Requests provides a powerful mechanism for implementing time-bound, approval-based access control to your network. By requiring explicit approval and setting time limits on access, this feature significantly enhances network security while maintaining flexibility for legitimate access needs.

The seamless integration with Netmaker Desktop ensures users have a simple, intuitive experience when requesting and using temporary access, while administrators benefit from a comprehensive dashboard that makes request management efficient and provides complete audit trails for compliance and security monitoring.

&#x20;


# Telemetry and Logging

{% embed url="<https://media.netmaker.io/features/Observability.mp4>" %}

Netmaker provides key observability features to administrators for reviewing the health and safety of their networks.

#### Metrics

Provides insights into network health with real-time data about connectivity status, traffic volume, and latency, across all of your devices.&#x20;

{% content-ref url="/pages/CJw4NRg85CQ9lteFmlRm" %}
[Metrics](/features/telemetry-and-logging/metrics)
{% endcontent-ref %}

#### User Logs

Provides a log of all user actions performed on the system.

{% content-ref url="/pages/Pz3RnOQpLgT9sKTTRF2u" %}
[User Logs](/features/telemetry-and-logging/activity/user-logs)
{% endcontent-ref %}

#### Network Flow Logs

Provides real-time data about network access events, including the source, destination, duration, and data transferred.

{% content-ref url="/pages/HGd1142ku7cpVT36AuJZ" %}
[Network Flow Logs](/features/telemetry-and-logging/activity/network-flow-logs)
{% endcontent-ref %}


# Metrics

Netmaker Pro offers analytics. With Analytics, admin users can view connectivity, latency and data transferred between two peers or nodes on a Netmaker network. Client analytics are also available. All of this data may be visualised in the Netmaker UI. In addition, Netmaker includes a custom exporter for Prometheus/Grafana integration to view the data as well.

{% hint style="info" %}
Metrics are collected over the encrypted Netmaker tunnel. Each Netmaker agent exposes a metrics server on a TCP port (default: **51821**), enabling secure retrieval of telemetry data without requiring public network exposure.
{% endhint %}

Below are the steps to view Analytics on your Netmaker Pro instance.

{% stepper %}
{% step %}

### View network metrics in the Netmaker Dashboard

To view the metrics in the Netmaker Dashboard:

* Select a network.
* Click the Analytics interface.
* Switch to any metric you are interested in, including metrics from clients.

{% hint style="info" %}
Metrics may take up to 5 minutes for nodes to report data.
{% endhint %}

If present, an analytics image for the dashboard will appear here.

![](/files/b1wZ4X9kM4IMAVwhIfEe)
{% endstep %}

{% step %}

### Grafana Dashboard

If your Netmaker instance includes the Prometheus/Grafana setup and is configured with the METRICS\_EXPORTER="on", you can also view your metrics via Grafana.

Access details example:

```plaintext
URL: "https://grafana.<YOUR_DOMAIN_NAME>"
Username: "admin"
Password: "admin"
```

Out-of-the-box Netmaker Grafana options include:

* Netmaker Metrics Dashboard
* Netmaker Network Graph

![Netmaker Grafana Dashboards](/files/05d46d8c58af87d531300f174f1cd8ff08fb9b20)

The Netmaker Metrics Dashboard lets you select and view data on individual nodes.

![Netmaker Grafana View 1](/files/be177ca9914134b514eb3525a020b5d403693e4c)

The Netmaker Network Graph view shows a network graph where you can hover nodes to see node statistics and hover edges to view connection information. Edge colors vary by connection status (green = connected, red = disconnected).

![Netmaker Grafana View 2](/files/9527e04d85e4c4e7976f146ed9d49c1b0850b694)
{% endstep %}

{% step %}

### Prometheus Dashboard

You can also view your metrics on the Prometheus dashboard. On first visit you may be prompted for credentials.

Access details example:

```plaintext
URL: "https://prometheus.<YOUR_DOMAIN_NAME>"
Username: "Netmaker-Prometheus"
Password: "<YOUR_LICENSE_KEY>"
```

{% endstep %}
{% endstepper %}


# Activity


# User Logs

Netmaker v0.99.0 introduces **User Logs**, a critical feature designed to enhance system transparency, traceability, and security. This feature records significant system events and user actions, providing administrators with clear visibility into changes within their network infrastructure.

### Purpose

Audit Logs are essential for:

* **Tracking Configuration Changes:** Monitor who changed what and when.
* **Enhancing Security:** Detect unauthorized or unexpected operations.
* **Compliance:** Assist in meeting organizational and regulatory audit requirements.
* **Troubleshooting:** Reconstruct event sequences to identify and resolve issues efficiently.

### What’s Covered?

The audit log currently tracks actions on all important Netmaker resources:

| Subject                  | Description                                           | Status    |
| ------------------------ | ----------------------------------------------------- | --------- |
| **Users**                | User-related operations (create, update, delete)      | ✅ Covered |
| **UserAccessToken**      | API tokens issued, revoked                            | ✅ Covered |
| **Nodes**                | Node creation, modification, deletion                 | ✅ Covered |
| **Settings**             | Platform settings changes                             | ✅ Covered |
| **ACLs**                 | ACL (Access Control List) changes                     | ✅ Covered |
| **Tags**                 | Tag creation, modification, deletion                  | ✅ Covered |
| **User Roles**           | User role assignments                                 | ✅ Covered |
| **User Groups**          | User groups creation, changes, removal                | ✅ Covered |
| **User Invites**         | User invites sent, revoked                            | ✅ Covered |
| **Pending Users**        | Pending user management (invites, approvals)          | ✅ Covered |
| **Egress**               | Egress gateway creation, changes, and removal.        | ✅ Covered |
| **Network**              | Network creation, configuration updates, deletion     | ✅ Covered |
| **Enrolment Keys**       | Enrolment key creation, updates, and removal          | ✅ Covered |
| **Desktop App Activity** | User connect/disconnect actions on the desktop client | ✅ Covered |


# Network Flow Logs

Detect suspicious activity, troubleshoot network issues, and identify security risks with detailed traffic analysis for faster resolution and better protection

## Overview

Traffic logs offer real-time visibility into network traffic on your Netmaker network, allowing you to monitor connections, analyze traffic patterns, and troubleshoot issues with detailed connection logs

**PRO FEATURE**

Traffic logs are available only on the Netmaker Business plan

**ENABLING TRAFFIC LOGS**

If Traffic Logs are not included in your plan, it must be enabled by the Netmaker team. To request activation:

**Contact Form:** <https://www.netmaker.io/contact>

**Status:** BETA

## What are Traffic Logs?

Traffic Logs capture detailed information about network connections flowing through your Netmaker network. Each log entry records the source, destination, protocol, ports, traffic direction, and data volume for comprehensive network visibility.

### Key Benefits

* Real-time visibility into all network traffic
* Troubleshoot connectivity issues with detailed connection data
* Monitor traffic patterns and bandwidth usage
* Identify suspicious activity or unauthorised connections

### Understanding the Traffic Logs Interface

Global Insights View

```plaintext
Sidebar → Analytics → Activity Tab → Traffic Logs
```

<figure><img src="/files/cZnJhf8jjnDQDVnn2iyk" alt=""><figcaption></figcaption></figure>

Each traffic log entry displays detailed information about a network event.&#x20;

Below is a breakdown of all components you'll see in a log entry:

### Log Entry Components

Each traffic log entry displays detailed information about a network event:

| Component       | Description                                    | Example                                              |
| --------------- | ---------------------------------------------- | ---------------------------------------------------- |
| Event           | Timestamp, end time, node name, and direction  | 9:03 AM, End: 9:03 AM, Node: inetgw, Inbound         |
| Source          | Origin of traffic (Node, User, External, etc.) | debian (node), 100.102.137.9:54618, <user@email.com> |
| Protocol & Port | Network protocol and destination port          | TCP 443, UDP 53, ICMP                                |
| Destination     | Target of traffic                              | inetgw (node), 140.82.113.26                         |
| Traffic         | Data transferred (download/upload)             | ↓ 60 B, ↑ 40 B                                       |

***

### Domain Visibility in Traffic Logs

Traffic Logs now include **domain names** for external destinations, making it easier to identify services and endpoints without relying solely on IP addresses.

This enhancement improves:

* Readability of logs
* Faster troubleshooting
* Better security analysis

Instead of seeing only an IP address:

```
34.160.111.145:443
```

You may now see:

```
api.example.com 
34.160.111.145:443
```

**Example:**

* Before: \
  `140.82.113.26:443`
* After: \
  `github.com`\
  `20.26.156.215:443`&#x20;

<figure><img src="/files/a9QyyHAbftA772I0MII9" alt=""><figcaption></figcaption></figure>

**Figure:** Traffic Logs showing domain names and addresses for external connections.

### Component Details

**Event Information:**

* **Timestamp:** Exact time the traffic event occurred (format: `HH:MM AM/PM`)
* **End Time:** When the traffic event is completed (format: `End: HH:MM AM/PM`)
* **Node:** The node that generated or received the traffic (format: `Node: [node-name]`)
* **Direction:** Traffic flow - **Inbound** (coming into node) or **Outbound** (leaving node)

**Source Types:**

* **Node:** Internal network node (e.g., `debian`, `inetgw`)
* **User:** User devices (e.g., `majdi@netmaker.io`)
* **Config Files:** Configuration-related traffic
* **External:** External IP addresses outside your network
* **Egress Route:** Traffic through egress gateways

**Protocol Types:**

* **TCP** - Transmission Control Protocol (reliable, connection-oriented)
* **UDP** - User Datagram Protocol (fast, connectionless)
* **ICMP** - Internet Control Message Protocol (network diagnostics)

**Destination Types:**

* **Node:** Internal network node
* **User:** User endpoint
* **Config Files:** Configuration endpoints
* **External:** External IP addresses (e.g., `140.82.113.26`)
* **Egress Route:** Egress gateway destinations

**Traffic Volume Indicators:**

* **↓ (Download):** Data received by the source node
* **↑ (Upload):** Data sent by the source node
* **Units:** B (bytes), KiB (kibibytes), MiB (mebibytes)

## Reading Traffic Log Entries

<figure><img src="/files/kvp6gLFUmhGtGiWksxUL" alt=""><figcaption></figcaption></figure>

### Example 1: Internal Node Communication (Inbound)

![](/files/og4FTRwdmtkYnA9ZZAVL)

```plaintext
EVENT: 9:51 AM
End: 9:51 AM
Node: inetgw
Direction: Inbound
SOURCE               PROTOCOL & PORT    DESTINATION         TRAFFIC
debian               TCP                inetgw              ↓ 60.00 (B)
100.102.137.9:44006  443                100.102.137.4:443   ↑ 40.00 (B)
```

**How to Read This:**

1. Reported by the i**netgw node**
2. **When:** The event occurred at 9:51 AM and ended at 9:51 AM
3. **Where:** Traffic passed through the `inetgw` node
4. **Direction:** Inbound (coming into inetgw)
5. **Source:** The `debian` node from IP 100.102.137.9, port 44006
6. **Protocol:** TCP on port 443 (HTTPS)
7. **Destination:** The `inetgw` node at IP 100.102.137.4, port 443
8. **Data Transfer:** 60 bytes received (↓), 40 bytes sent (↑)

**Interpretation:** **The debian node initiated** a secure HTTPS connection to the inetgw gateway, receiving 60 bytes and sending 40 bytes of data. This is typical of a small API call or status check.

### Example 2: Same Connection from Source Perspective (Outbound)

![](/files/7uMCKSvRzwpwwfS9Ho7w)

```plaintext
EVENT: 9:51 AM
End: 9:51 AM
Node: debian
Direction: Outbound

SOURCE               PROTOCOL & PORT    DESTINATION         TRAFFIC
debian               TCP                inetgw              ↓ 40.00 (B)
100.102.137.9:44006  443                100.102.137.4:443   ↑ 60.00 (B)
```

**How to Read This:**

1. Reported by the **debian node**
2. **When:** 9:51 AM (same event as Example 1)
3. **Where:** Traffic originated from the `debian` node
4. **Direction:** Outbound (leaving debian)
5. **Source:** The `debian` node at IP 100.102.137.9, port 44006
6. **Protocol:** TCP on port 443 (HTTPS)
7. **Destination:** The `inetgw` gateway at IP 100.102.137.4, port 443
8. **Data Transfer:** 40 bytes received (↓), 60 bytes sent (↑)

**Interpretation:** This is the same connection as Example 1, but reported by the **debian node.** Notice how the traffic values are reversed (↓40B/↑60B vs ↓60B/↑40B)

### Example 3: User Connection to External Service

![](/files/WxlQKG6Kg0wKHikiqRiZ)

```plaintext
EVENT: 9:50 AM
End: 9:51 AM
Node: inetgw
Direction: Inbound

SOURCE                   PROTOCOL & PORT    DESTINATION          TRAFFIC
majdi@netmaker.io        TCP                34.160.111.145       ↓ 2.36 (KiB)
100.102.137.21:38532     443                34.160.111.145:443   ↑ 4.03 (KiB)
```

**How to Read This:**

1. Reported by the **inetgw node**
2. **When:** Event started at 9:50 AM and ended at 9:51 AM
3. **Who:** User `majdi@netmaker.io` initiated the connection
4. **Where:** Traffic routed through the `inetgw` node (gateway)
5. **Direction:** Inbound through the gateway
6. **Source:** User at IP 100.102.137.21, port 38532
7. **Protocol:** TCP on port 443 (HTTPS)
8. **Destination:** External server at IP 34.160.111.145, port 443
9. **Data Transfer:** 2.36 KiB received (↓), 4.03 KiB sent (↑)

**Interpretation:** User <majdi@netmaker.io> connected through the inetgw gateway to an external server on HTTPS. The user downloaded 2.36 KiB and uploaded 4.03 KiB, suggesting they sent more data than they received—typical of uploading data or submitting form content to an external service.

## Common Traffic Patterns

### Small Data Transfers (< 1 KiB)

**What it means:** Control messages, API calls, heartbeats, status checks

**Examples:**

* ↓ 60.00 (B) / ↑ 40.00 (B)
* TCP port 443 connections with minimal data
* Quick request/response patterns

**Typical scenarios:**

* Health checks between nodes
* Authentication requests
* Configuration updates
* DNS queries

### Medium Data Transfers (1-100 KiB)

**What it means:** Web pages, API responses, small files

**Examples:**

* ↓ 4.33 (KiB) / ↑ 4.84 (KiB)
* HTTP/HTTPS web page loads
* JSON data exchanges

**Typical scenarios:**

* Loading web dashboards
* API data retrieval
* Configuration file transfers
* Log uploads

### Large Data Transfers (> 100 KiB)

**What it means:** File transfers, media, backups

**Examples:**

* ↓ 2.5 (MiB) / ↑ 1.2 (MiB)
* File downloads/uploads
* Database syncs

**Typical scenarios:**

* Software updates
* Backup operations
* Video streaming
* Large file transfers

## Using the Filter Feature

<figure><img src="/files/qfk0gVVarH1GNsmN6QKI" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}
Click the "Filter" button at the top of the Traffic Logs panel
{% endstep %}

{% step %}
Select your filter criteria: Time Range, Protocol, Direction, Source, Destination Types
{% endstep %}

{% step %}
Apply filters to see refined results
{% endstep %}

{% step %}
Reset to defaults to return to full view
{% endstep %}
{% endstepper %}

## Data Volume Reference

### Understanding Size Units

**Bytes (B):**

* Range: 1 - 999 B
* Typical for: Control messages, handshakes, small requests
* Examples: TCP SYN packets, HTTP headers, status checks

**Kibibytes (KiB):**

* 1 KiB = 1,024 bytes
* Range: 1 - 999 KiB
* Typical for: Web pages, API responses, small files
* Examples: HTML pages, JSON data, small images

**Mebibytes (MiB):**

* 1 MiB = 1,024 KiB = 1,048,576 bytes
* Range: 1+ MiB
* Typical for: Large files, media, backups
* Examples: Videos, software updates, database dumps

### Typical Traffic Volumes by Service

| Service        |   Typical Size | Example               |
| -------------- | -------------: | --------------------- |
| TCP Handshake  |       40-100 B | ↓ 60 B / ↑ 40 B       |
| DNS Query      |       50-150 B | ↓ 120 B / ↑ 80 B      |
| HTTP Header    |      200-800 B | ↓ 500 B / ↑ 300 B     |
| Small API Call |       1-10 KiB | ↓ 4.5 KiB / ↑ 2.1 KiB |
| Web Page       |     10-500 KiB | ↓ 250 KiB / ↑ 15 KiB  |
| Image          | 50 KiB - 5 MiB | ↓ 1.2 MiB / ↑ 500 B   |
| Video Stream   |  1-10+ MiB/sec | ↓ 8 MiB / ↑ 100 KiB   |

## Summary

Traffic Logs provides essential visibility into your network communications:

* Real-time monitoring of all network traffic
* Detailed information about each connection
* Flexible filtering to find relevant events
* Security monitoring to detect threats
* Performance troubleshooting to identify issues
* Compliance auditing to document activity

**To get started:** Please <https://www.netmaker.io/contact>


# SIEM Integration

Netmaker can stream audit and network activity events to supported Security Information and Event Management (SIEM) platforms, enabling centralized monitoring, alerting, compliance reporting, and security investigations.

Supported SIEM platforms include:

* Datadog
* Splunk
* Microsoft Sentinel
* Elastic Security

## Overview

The SIEM integration allows Netmaker to export platform events to an external security monitoring solution. Exported events can be correlated with logs and telemetry from other systems to provide greater visibility into network operations and administrative activity.

## Configure a SIEM Integration

1. Navigate to **Settings → Integrations**.<br>

<figure><img src="/files/uF8538MAlO4Z4bQ2HkNN" alt=""><figcaption></figcaption></figure>

1. Connect the desired SIEM provider.
2. Enter the provider-specific connection details and credentials.
3. Test the connection.
4. Save the integration.

Once configured, Netmaker will begin forwarding supported audit and activity events to the selected SIEM platform.

## Provider-Specific Configuration

Refer to the following guides for configuration details:

### Datadog

1. Create a Datadog API key<br>

   <figure><img src="/files/MmukCHWA0CYQumu8Ea69" alt=""><figcaption></figcaption></figure>
2. Enter the API key in Netmaker.<br>

   <figure><img src="/files/VuwTodYgAkyCq1fzhj5o" alt=""><figcaption></figcaption></figure>
3. In the **Datadog Site** field, select the region/site where your Datadog organization is hosted.
4. If your Datadog URL is [**https://us5.datadoghq.com**](https://us5.datadoghq.com), select **`us5.datadoghq.com (US5)`** from the dropdown.<br>

   <figure><img src="/files/DTttndQ5RG7s2Hjuc8Za" alt=""><figcaption></figcaption></figure>
5. Test and save the integration.<br>

   <figure><img src="/files/9eOEuYxkwTppunp3tmdR" alt=""><figcaption></figcaption></figure>

### Splunk

#### Step 1: Open HTTP Event Collector

1. Click **Settings** (top-right of the Splunk interface).

   <figure><img src="/files/BVUqWhTwEHq0HOoNMdUF" alt=""><figcaption></figcaption></figure>
2. Select **Data Inputs**.<br>

   <figure><img src="/files/CYMIcFPTKy5UcuObYYWB" alt=""><figcaption></figcaption></figure>
3. Click **HTTP Event Collector**.<br>

   <figure><img src="/files/wMCbvdKFGBGvclJxRSs4" alt=""><figcaption></figcaption></figure>
4. If HEC is disabled, enable it under **Global Settings**.<br>

   <figure><img src="/files/225XtSKwf3Y9cWvNPwgG" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/l0wyf14r0g718Gk5QwbV" alt=""><figcaption></figcaption></figure>

#### Step 2: Create a HEC Token

1. Click **New Token**.<br>

   <figure><img src="/files/5OqkQNqpIrvYapyhElC6" alt=""><figcaption></figcaption></figure>
2. Give it a name, such as **Netmaker SIEM**.
3. Choose the destination index (for example, `main`).<br>

   <figure><img src="/files/gfuPobZIvspObxtRHZKO" alt=""><figcaption></figcaption></figure>
4. Complete the wizard and click **Submit**.
5. Copy the generated **HEC Token**.

#### **Step 3: Copy the HTTP Event Collector (HEC) Endpoint**

Enter your Splunk Cloud instance URL as the **HEC Endpoint URL**.

For example, if your Splunk Cloud instance is:

```
https://prd-p-wvklf.splunkcloud.com
```

then enter:

```
https://prd-p-wvklf.splunkcloud.com
```

#### Step 4: Configure Netmaker

<figure><img src="/files/efV5PlZiXIdEt9gb7ZBV" alt=""><figcaption></figcaption></figure>

Enter the following values:

* **HEC Endpoint URL**

  ```
  https://http-inputs-prd-p-wvklf.splunkcloud.com/services/collector/event
  ```
* **HEC Token**
  * Paste the token you created in Splunk.
* **Test and save the integration.**

### Microsoft Sentinel

1. Create a Data Collection Endpoint (DCE) and Data Collection Rule (DCR).
2. Obtain the ingestion endpoint and credentials.
3. Enter the endpoint and credentials in Netmaker.
4. Test and save the integration.

### Elastic

#### 1. Check if You Already Have a Deployment

* Go to <https://cloud.elastic.co> and log in
* On the home screen, check **“Deployments”**

#### If you already have a deployment:

* Skip to **Step 3 (Open Deployment)**

#### If you don’t have a deployment:

* Click **“Create deployment”** and continue below

***

#### 2. Create a Deployment&#x20;

Click **“Create deployment”**, then configure:

* **Name:** e.g. `netmaker-security`
* **Cloud Provider:** AWS / GCP / Azure
* **Region:** closest to your Netmaker instance
* **Version:** latest Elasticsearch
* **Template:** Security or General Purpose

Optional settings

* Adjust sizing/resources if needed (defaults are usually fine)

**Finish setup**

* Click **“Create Deployment”**
* Wait until status becomes **Healthy**
* IMPORTANT: Save credentials:
  * Username: `elastic`
  * Password (shown only once)

***

#### 3. Open Your Deployment

* From the deployments list, click **“Manage”** on your deployment\ <br>

  <figure><img src="/files/fiEvuQS642VE0QvBoeGv" alt=""><figcaption></figcaption></figure>

***

#### 4. Get Elasticsearch Endpoint

* In the deployment overview, locate:

  <figure><img src="/files/pSBMY6PobUYRGHNufRLD" alt=""><figcaption></figcaption></figure>
* Click the **copy icon**&#x20;

***

#### 5. Create API Key (via Kibana)

#### Open project

* Click **“Open project”**<br>

  <figure><img src="/files/jOQTqhscwuOLz88pUaA2" alt=""><figcaption></figcaption></figure>

#### Create API key

* Click the **Settings (⚙️) icon** in the left sidebar

  <figure><img src="/files/fRBYqSd5JzW6x5rSV0wz" alt=""><figcaption></figcaption></figure>
* **Click API Keys**

  <figure><img src="/files/RZpQNBwhgzGUKT7bmCXH" alt=""><figcaption></figcaption></figure>
* Click **“Create API key”**<br>

  <figure><img src="/files/iYCsrvhfzL5EyWjURwdI" alt=""><figcaption></figcaption></figure>
* Name: `netmaker-integration`
* Copy and save it immediately (it won’t be shown again)

***

#### 6. Configure Netmaker Integration

Use the following values:

* **Elasticsearch Endpoint**
* **API Key**
* **Index name** (e.g. `netmaker-events` or custom)

***

#### 7. Final Step

Enter these values into your **Netmaker SIEM integration settings** and save.

## Verify the Integration

1. Click **Test Connection**.\ <br>

   <figure><img src="/files/srbPAW77hcUrTT9m2PVn" alt=""><figcaption></figcaption></figure>
2. Save the integration.
3. Generate a test event in Netmaker.
4. Confirm the event appears in your SIEM platform.


# NMCTL

NMCTL is a CLI tool for interacting with the Netmaker API.

## Quick Start

Start with getting the latest nmctl binary specific to your operating system from the link below:

```plaintext
https://github.com/gravitl/netmaker/releases/latest
```

Make sure the binary is executable with `chmod +x nmctl` and then move it into your /usr/sbin folder.

If everything is setup ok, you should be able to type `nmctl` and see the following:

```plaintext
CLI for interacting with Netmaker Server

Usage:
  nmctl [command]

Available Commands:
  acl             Manage Access Control Lists (ACLs)
  completion      Generate the autocompletion script for the specified shell
  context         Manage various netmaker server configurations
  dns             Manage DNS entries associated with a network
  enrollment_key  Manage Enrollment Keys
  ext_client      Manage Remote Access Clients
  help            Help about any command
  host            Manage hosts
  logs            Retrieve server logs
  metrics         Fetch metrics of nodes/networks
  network         Manage Netmaker Networks
  network_user    Manage Network Users
  node            Manage nodes associated with a network
  server          Get netmaker server information
  user            Manage users and permissions
  usergroup       Manage User Groups

Flags:
  -h, --help   help for nmctl

Use "nmctl [command] --help" for more information about a command.
```

Your CLI should be ready to go at this point.

### Context

Before running any commands, a context has to be set which stores the API endpoint information. This allows the CLI to know which server to communicate with, and the user account to use.

NMCLI supports connecting to both standalone (self-hosted) and SaaS(managed) tenants. This is specified with a flag. More details below.

### Connecting to standalone (self-hosted) tenants

Assuming your tenant is hosted at <https://api.netmaker.example.com/>

You can use your username and password that you use to sign in to the dashboard UI to set the context. Then you can set the CLI to use that context.

```plaintext
nmctl context set <context name> --endpoint=https://api.netmaker.example.com  --username=<username> --password=<password>  # create the context
nmctl context use <context name>  # apply the created context
```

You can also authenticate via OAuth with the following:

```plaintext
nmctl context set <context name> --endpoint=https://api.netmaker.example.com  --sso  # create the context for OAuth (Social Sign On)
nmctl context use <context name>  # apply the created context
```

### Connecting to SaaS (managed) tenants

You can also authenticate with a managed (SaaS) tenant with the following commands:

```plaintext
nmctl context set <context name> --saas --tenant_id=<tenant ID> --username=<username> --password=<password>  # create the context
nmctl context use <context name>  # apply the created context
```

You can also authenticate via OAuth with the following:

```plaintext
nmctl context set <context name> --saas --sso --tenant_id=<tenant ID>  # create the context for OAuth (Social Sign On)
nmctl context use <context name>  # apply the created context
```

### List and switch between contexts

You can see a list of all your contexts that you have created with the following:

```plaintext
nmctl context list
```

That list also tells you what context/tenant is currently selected.

You can switch to a different context by using the use subcommand:

```plaintext
nmctl context use <context name>
```

### Delete contexts

You can delete a context with the following:

```plaintext
nmctl context delete <context name>
```

## Network

Create a network with the name test\_net and CIDR 10.11.13.0/24.

```plaintext
nmctl network create --name="test_net" --ipv4_addr="10.11.13.0/24"
```

Fetch details of the created network.

```plaintext
nmctl network list
+----------+----------------------+----------------------+---------------------------+---------------------------+
|  NETID   | ADDRESS RANGE (IPV4) | ADDRESS RANGE (IPV6) |   NETWORK LAST MODIFIED   |    NODES LAST MODIFIED    |
+----------+----------------------+----------------------+---------------------------+---------------------------+
| test_net | 10.11.13.0/24        |                      | 2022-12-14T13:08:47+05:30 | 2022-12-14T13:08:47+05:30 |
+----------+----------------------+----------------------+---------------------------+---------------------------+
```

## Access Key

Create an access key for the created network with 100 uses. This key shall be used by nodes to join the network test\_net.

```plaintext
nmctl keys create test_net 100
{
  "name": "key-818a4ac3fe85a9d0",
  "value": "f0edf9ef08fa2b1a",
  "accessstring": "eyJhcZljb25uc3RyaW5nIjoiYXBpLm5ldG1ha2VyLmV6ZmxvLmluOjQ0MyIsIm5ldHdvcmsiOiJ0ZXN0X25ldCIsImtleSI6ImYwZWRmOWVmMDhmYTJiMWEiLCJsb2NhbHJhbmdlIjoiIn0=",
  "uses": 100,
  "expiration": null
}
```

## Nodes

Connect a node to the network using <https://docs.v2.netmaker.io/guide/getting-started/netclient> and the access key created above. Use the accessstring as token.

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

List all nodes. This displays information about each node such as the address assigned, id, name etc

```plaintext
nmctl node list
+--------------+---------------------------+---------+----------+--------+-----------------------+-------+--------------------------------------+
|     NAME     |         ADDRESSES         | VERSION | NETWORK  | EGRESS | REMOTE ACCESS GATEWAY | RELAY |                  ID                  |
+--------------+---------------------------+---------+----------+--------+-----------------------+-------+--------------------------------------+
| test_node    | 10.11.13.254              | v0.17.0 | test_net | no     | no                    | no    | 938d7861-55fc-40a9-970d-6d70acfc3a80 |
+--------------+---------------------------+---------+----------+--------+-----------------------+-------+--------------------------------------+
```

Using nmctl, we can turn the node into egress, remote access gateway or a relay. Lets turn the node into an remote access gateway by supplying the network name and node id as parameters.

```plaintext
nmctl node create_remote_access_gateway test_net 938d7861-55fc-40a9-970d-6d70acfc3a80
```

Fetching the node list once again we can see that our node has been turned into a remote access gateway.

```plaintext
nmctl node list
+--------------+---------------------------+---------+----------+--------+-----------------------+-------+--------------------------------------+
|     NAME     |         ADDRESSES         | VERSION | NETWORK  | EGRESS | REMOTE ACCESS GATEWAY | RELAY |                  ID                  |
+--------------+---------------------------+---------+----------+--------+-----------------------+-------+--------------------------------------+
| test_node    | 10.11.13.254              | v0.17.0 | test_net | no     | yes                   | no    | 938d7861-55fc-40a9-970d-6d70acfc3a80 |
+--------------+---------------------------+----------------------+--------+-----------------------+-------+--------------------------------------+
```

## Remote Access Clients

Adding a Remote Access Client (<https://docs.v2.netmaker.io/guide/features/remote-access-gateways-and-clients>) to the network is just as easy. Requires the network name and node id as input parameters.

```plaintext
nmctl ext_client create test_net 938d7861-55fc-40a9-970d-6d70acfc3a80
Success
```

List all available Remote Access Clients.

```plaintext
nmctl ext_client list
+--------------+---------+--------------+--------------+---------+-------------------------------+
|  CLIENT ID   | NETWORK | IPV4 ADDRESS | IPV6 ADDRESS | ENABLED |         LAST MODIFIED         |
+--------------+---------+--------------+--------------+---------+-------------------------------+
| limp-chicken |test_net | 10.11.13.2   |              | true    | 2022-11-23 18:28:57 +0530 IST |
+--------------+---------+--------------+--------------+---------+-------------------------------+
```

The wireguard config of an Remote Access Client can also be fetched with the network name and client id.

```plaintext
nmctl ext_client config test_net limp-chicken

[Interface]
Address = 10.11.13.2/32
PrivateKey = 4Ojhsn/uLcH6xta6zqokQ+GiRuZwesdzE2hDSa6vYWc=
MTU = 1280

[Peer]
PublicKey = h96G9R8qqHIm6OfFgIZNBlRE5uCumkSZv4Pwn2DVXEs=
AllowedIPs = 10.11.13.0/24
Endpoint = 138.209.145.214:51824
PersistentKeepalive = 20
```

## ACLs

Access Control between hosts can be managed via the NMCTL CLI. These settings allow the network admin to specify which hosts are allowed to communicate between each other.

### List

To list all access control settings for a network:

```plaintext
nmctl acl list <network>
```

### Allow / Deny

To allow communication between two hosts on a network:

```plaintext
nmctl acl allow <network> <host 1 ID> <host 2 ID>
```

To deny communication between two hosts:

```plaintext
nmctl acl deny <network> <host 1 ID> <host 2 ID>
```

Host IDs can be retrieved with the nmctl node list command.

The global –output flag can be used to format how a network’s ACLs are outputted.

## Help

Further information about any subcommand is available using the `--help` flag

```plaintext
nmctl subcommand --help
```

Example:

```plaintext
nmctl node --help
Manage nodes associated with a network

Usage:
  nmctl node [command]

Available Commands:
  create_egress                Turn a Node into a Egress
  create_remote_access_gateway Turn a Node into a Remote Access Gateway
  create_relay                 Turn a Node into a Relay
  delete                       Delete a Node
  delete_egress                Delete Egress role from a Node
  delete_remote_access_gateway Delete Remote Access Gateway role from a Node
  delete_relay                 Delete Relay role from a Node
  get                          Get a node by ID
  list                         List all nodes
  uncordon                     Get a node by ID
  update                       Update a Node

Flags:
  -h, --help     help for node

Use "nmctl node [command] --help" for more information about a command.
```

## NMCTL - standalone

A brief guide to using netmaker from the command line (without the UI)

{% stepper %}
{% step %}

### Assumptions

* using bash shell
* nmctl and jq have been installed
* netmaker server has been set up at <http://example.com/>. This can be a SaaS (managed) tenant as well.
  {% endstep %}

{% step %}

### Setup superadmin user — Set base domain

```plaintext
export NN_DOMAIN=example.com
```

{% endstep %}

{% step %}

### Setup superadmin user — Create SuperAdmin User

```plaintext
curl --location 'https://api.$NM_DOMAIN/api/users/adm/createsuperadmin' \
--header 'Content-Type: application/json' \
--data '{
"username":"superadmin",
"password":"NetmakerIsAwe$ome"
}'
```

{% endstep %}

{% step %}

### Setup superadmin user — Set Context

```plaintext
nmctl context set commandline --endpoint https://api.$NM_DOMAIN --username $USER --password $PASSWORD
```

{% endstep %}

{% step %}

### Setup superadmin user — Create Admin User

```plaintext
nmctl user create --admin --name $USER --password $PASSWORD
```

{% endstep %}

{% step %}

### Setup superadmin user — Create Normal User

```plaintext
nmctl user create --name <user> --password <user-password>
```

{% endstep %}
{% endstepper %}

### Normal Operations by user

(assume that users have been created by superadmin)

{% stepper %}
{% step %}

### Set username/password

```plaintext
export USER=<user>
export PASSWORD=<user-password>
```

{% endstep %}

{% step %}

### Set User Context

```plaintext
nmctl context set commandline --endpoint https://api.$NM_DOMAIN --username $USER --password $PASSWORD
nmctl context use commandline
```

{% endstep %}

{% step %}

### Create Network

```plaintext
nmctl network create --name mynetwork --ip4v_addr 10.10.10.0/24
```

{% endstep %}

{% step %}

### Create Enrollment Key — Unlimited

```plaintext
export KEY=$(nmctl enrollment_key create --network mynetwork --unlimited | jq .token)
```

{% endstep %}

{% step %}

### Create Enrollment Key — Limited Use (3)

```plaintext
export KEY=$(nmctl enrollment_key create --network mynetwork --uses 3 | jq .token)
```

{% endstep %}

{% step %}

### Create Enrollment Key — With Expiration Time (2 days)

```plaintext
export EXPIRES=$(date -d "+2 days" +$s)
export KEY=$(nmctl enrollment_key create --network mynetwork --expires $EXPIRES | jq .token)
```

{% endstep %}

{% step %}

### Join network

```plaintext
sudo netclient join -t $KEY
```

{% endstep %}
{% endstepper %}


# Kubernetes Operator

## Intro

<figure><img src="/files/ZOM8awOhOHrNmQYapNWP" alt=""><figcaption></figcaption></figure>

### What is the Netmaker Kubernetes Operator?

The **Netmaker Kubernetes Operator** securely connects your Kubernetes cluster to a **Netmaker WireGuard network**.

It allows:

* Kubernetes workloads to talk to **VMs, servers, and edge devices**
* Netmaker devices to securely access **Kubernetes services**
* All traffic to stay **private, encrypted, and zero-trust**

No manual VPN setup. No complex routing.

### Why Use the Netmaker Kubernetes Operator?

Modern infrastructure often spans multiple environments:

* **Kubernetes clusters** running containerised applications
* **Virtual machines** and bare-metal servers
* **Edge devices** and IoT deployments
* **Hybrid cloud** environments

Traditionally, connecting these different environments requires complex VPN configurations, firewall rules, and network routing. The Netmaker Kubernetes Operator simplifies this by:

* **Eliminating Network Complexity**: No need to manually configure VPNs or complex routing rules
* **Enabling Secure Communication**: All traffic flows through encrypted WireGuard tunnels
* **Providing Native Kubernetes Integration**: Use standard Kubernetes Services and annotations
* **Supporting Bidirectional Access**: Kubernetes workloads can reach Netmaker services, and Netmaker devices can reach Kubernetes services

### What Can You Do With the Operator?

The operator provides three main capabilities:

* **Egress Proxy**: Access Netmaker services (APIs, databases, etc.) from your Kubernetes applications using standard Kubernetes Service names
* **Ingress Proxy**: Expose your Kubernetes services to devices on your Netmaker network
* **API Proxy**: Securely access your Kubernetes API server through Netmaker tunnels with RBAC support that syncs with the users on Netmaker controlplane

## Key Concepts

### Netmaker Network

A Netmaker network is a WireGuard-based virtual network that connects devices across different locations. Devices on the network can communicate securely using private IP addresses assigned by Netmaker.

### Netclient

Netclient is the agent that runs on devices to connect them to a Netmaker network. The operator uses netclient as a sidecar container to provide WireGuard connectivity to Kubernetes pods.

### Operator

A Kubernetes operator is a controller that extends Kubernetes functionality. This operator watches for specific Kubernetes resources (like Services with annotations) and automatically configures networking to connect them with Netmaker networks.

### Cluster Egress vs Cluster Ingress

* **Egress Proxy**: Allows Kubernetes workloads to access services on the Netmaker network (Kubernetes → Netmaker)
* **Ingress Proxy**: Allows Netmaker devices to access services running in Kubernetes (Netmaker → Kubernetes)

## 🧩 Common Use Cases

* Cross-Environment Database Access: Connect your Kubernetes applications to databases running on servers in your Netmaker network, without exposing them to the public internet.
* Multi-Cluster Communication: Enable secure communication between workloads in different Kubernetes clusters through a shared Netmaker network.
* Edge-to-Cloud Connectivity: Connect edge devices and IoT devices in your Netmaker network to services running in your Kubernetes cluster.
* Secure API Access: Allow remote developers and systems to securely access your Kubernetes API server through WireGuard tunnels.
* Hybrid Cloud Networking: Unify networking across cloud and on-premises infrastructure through a single Netmaker network.

## Getting Started

### Prerequisites

{% stepper %}
{% step %}

### Kubernetes Cluster

* Kubernetes v1.11.3 or later
* Access via `kubectl`
* Sufficient permissions to create namespaces, deployments, and services
  {% endstep %}

{% step %}

### Netmaker Server

* Running and accessible
* At least one network is configured
* Admin access to generate tokens
  {% endstep %}

{% step %}

### Netmaker Network Token

* Generated from your Netmaker server
* Used to join the Kubernetes cluster to the network
* Keep this secure – you'll need it during installation
  {% endstep %}

{% step %}

### Helm

* Helm v3.0 or later (recommended installation method)
  {% endstep %}
  {% endstepper %}

### Installation

#### Add Helm Repository

{% code title="Add Helm repo" %}

```bash
helm repo add netmaker-k8s-ops https://downloads.netmaker.io/charts/
helm repo update
```

{% endcode %}

#### Install the Operator

{% code title="Helm install" %}

```bash
helm install netmaker-k8s-ops netmaker-k8s-ops/netmaker-k8s-ops \
  --namespace netmaker-k8s-ops-system \
  --create-namespace \
  --set image.repository=gravitl/netmaker-k8s-ops \
  --set image.tag=latest \
  --set netclient.token="YOUR_NETMAKER_TOKEN_HERE"
```

{% endcode %}

**With K8s Proxy configuration** (need netmaker API integration in auth mode for users sync):

**Auth MODE ( netmaker Pro server needed)**

```bash
helm install netmaker-k8s-ops netmaker-k8s-ops/netmaker-k8s-ops \
  --namespace netmaker-k8s-ops-system \
  --create-namespace \
  --set image.repository=gravitl/netmaker-k8s-ops \
  --set image.tag=latest \
  --set netclient.token="YOUR_NETMAKER_TOKEN_HERE" \
  --set manager.configMap.proxyMode="auth" \
  --set service.proxy.enabled=true \
  --set api.enabled=true \
  --set api.serverDomain="api.example.com" \
  --set api.token="your-api-token-here" \
  --set api.syncInterval="10"
```

**NOAUTH MODE**

```bash
helm install netmaker-k8s-ops netmaker-k8s-ops/netmaker-k8s-ops \
  --namespace netmaker-k8s-ops-system \
  --create-namespace \
  --set image.repository=gravitl/netmaker-k8s-ops \
  --set image.tag=latest \
  --set netclient.token="YOUR_NETMAKER_TOKEN_HERE" \
  --set manager.configMap.proxyMode="noauth" \
  --set service.proxy.enabled=true
```

{% hint style="info" %}
Using a Kubernetes Secret for the netclient token is recommended for production. Secrets are read from the operator namespace (`netmaker-k8s-ops-system`) by default.
{% endhint %}

#### Using Kubernetes Secret for token (recommended)

{% code title="Create token secret" %}

```bash
# Create secret
kubectl create secret generic netclient-token \
  --from-literal=token="YOUR_NETMAKER_TOKEN_HERE" \
  --namespace netmaker-k8s-ops-system
```

{% endcode %}

## Examples

### Cluster Egress

Expose services that are external to your Kubernetes cluster but available in your Netmaker network, making them accessible to your Kubernetes workloads.

Use Case: Allow Kubernetes applications to access Netmaker services (APIs, databases, etc.) using standard Kubernetes Service names.

{% code title="Cluster Egress Service example" %}

```yaml
apiVersion: v1
kind: Service
metadata:
  name: netmaker-api-egress
  namespace: default
  annotations:
    # Enable egress proxy functionality
    netmaker.io/egress: "enabled"
    # Option 1: Use Netmaker device IP address
    netmaker.io/egress-target-ip: "100.93.135.2"
    # Option 2: Use Netmaker device DNS name (uncomment to use DNS instead)
    # netmaker.io/egress-target-dns: "api.netmaker.internal"
    # Optional: Custom secret configuration for netclient token
    # Note: Secrets are always read from operator namespace (netmaker-k8s-ops-system) for security
    # netmaker.io/secret-name: "custom-netclient-token"      # Default: netclient-token
    # netmaker.io/secret-key: "token"                         # Default: token
spec:
  ports:
  - name: http
    port: 8082
    targetPort: 8082  # This is the port on the Netmaker device (standard Kubernetes way)
    protocol: TCP
  # Note: The selector is optional - the controller manages endpoints directly
  # But including it helps with Service discovery
  selector:
    app: netmaker-egress-proxy
    service-name: netmaker-api-egress
  type: ClusterIP
```

{% endcode %}

### Cluster Ingress

Expose Kubernetes services to devices on your Netmaker network, allowing Netmaker devices to access Kubernetes workloads.

Use Case: Enable Netmaker network devices to access Kubernetes services (APIs, databases, web apps) using Netmaker IPs or DNS names.

{% code title="Cluster Ingress Service example" %}

```yaml
# Example: Expose Kubernetes Service to Netmaker Network

# This Service creates an ingress proxy that allows Netmaker devices to access your K8s service

apiVersion: v1
kind: Service
metadata:
  name: my-api-ingress
  namespace: default
  annotations:
    # Enable ingress proxy functionality
    netmaker.io/ingress: "enabled"
    # Optional: Specify DNS name for this service on Netmaker network
    # netmaker.io/ingress-dns-name: "api.k8s.netmaker.internal"
    # Optional: Custom secret configuration for netclient token
    # Note: Secrets are always read from operator namespace (netmaker-k8s-ops-system) for security
    # netmaker.io/secret-name: "custom-netclient-token"      # Default: netclient-token
    # netmaker.io/secret-key: "token"                         # Default: token
spec:
  ports:
  - name: http
    port: 80
    targetPort: 8080  # Port your application listens on
    protocol: TCP
  selector:
    app: my-api  # Your application selector
  type: ClusterIP
```

{% endcode %}


# Netmaker SaaS


# Overview

Overview of the Netmaker SaaS

Netmaker SaaS is a cloud-based platform that simplifies the creation and management of secure, high-performance virtual networks across distributed environments. It enables businesses to connect devices, cloud services, and on-premise infrastructure using WireGuard-based VPNs. With features like multi-cloud support, automated network management, and easy deployment, Netmaker SaaS provides a scalable and efficient solution for secure networking without the need for complex configurations or hardware dependencies.

In other words, we provide the Netmaker Server software to you as a service, hosted on our virtual machines in the cloud. You have the flexibility to choose from nine regions worldwide for the location of your Netmaker tenant, based on the strategic requirements of your VPN network.

A Netmaker tenant is a single instance of the Netmaker server, either hosted in our cloud or hosted on your machine.

In addition to the Netmaker server, we also deploy a dedicated **endpoint machine** for each tenant, which functions as a general-purpose routing node for your VPN. With **Managed Endpoints**, you can route traffic into, out of, and between machines in your VPN without needing to deploy your own device in the cloud. For more information on the Managed Endpoint feature, refer to this blog post: <https://www.netmaker.io/resources/introducing-managed-endpoints-on-netmaker-vpn>

{% hint style="info" %}
Start a 14-day free trial: <https://account.netmaker.io/signup>

A payment method (Visa, Mastercard, US Bank Account, etc.) is required for the trial. If you cannot provide a payment method, a 30-days Business Evaluation is available free of charge — sign up with your business email: <https://account.netmaker.io/signup#business>
{% endhint %}


# Account Management

Account Management in Netmaker SaaS

The Netmaker SaaS has two web interfaces, the Account Management UI (AMUI) and the Netmaker UI (NMUI). You can tell between the two by looking at the address bar of your browser. AMUI's URL is <https://account.netmaker.io/>, while NMUI is <https://app.netmaker.io/>.

![](/files/Nm0QEendrbXIIgHkROf7)

The NMUI allows you to manage VPN resources of each *tenant*. It is the Netmaker application web UI — that's why it appears the same as the web UI of a self-hosted Netmaker Server.

![](/files/RnbnphqF4QpThPJo7KC9)

The Account Management UI (AMUI) on Netmaker SaaS allows you full control of your profile information, payment method information, and invoicing details on our cloud platform. This is where you will be able to manage your tenants, monitor bill payments & usage, and manage users of each tenant.

When you visit the login or signup pages, you're interacting with the AMUI. If you only have one tenant, you'll be automatically redirected to that tenant's NMUI after logging in. If you have multiple tenants, you'll be taken to the Tenants page (AMUI), where you can select the specific tenant you want to access.

If you are in the NMUI and wish to navigate to the AMUI, you can click on your username in the lower-left corner of the screen and then click on Manage Account.

![](/files/Z3af2UeUaKBEAysJFPRL)

### Profile Page

The **Profile page** serves as a management interface for your **Netmaker SaaS global account settings** and **user preferences.** The Profile page is where you can set your payment method, invoice details, and account profile details.

![](/files/4j2OJjP77KUX53qePK0c)

### Tenants Page

The **Tenants page** is used for managing **multi-tenancy** within the Netmaker SaaS platform. Multi-tenancy allows you to divide your infrastructure into isolated environments, each with its own users, networks, and resources. The tenants page typically allows an administrator to:

* **Create and Manage Tenants**: Set up different tenants, which could represent different teams, organizations, or business units.
* **Assign Users to Tenants**: Control which users belong to which tenant, enforcing role-based access control within the tenant’s environment.
* **Tenant Isolation**: Ensure that each tenant’s resources (such as VPN networks, gateways, etc.) are isolated and cannot be accessed by other tenants.
* **View and Edit Tenant Configurations**: Modify configurations related to each tenant, such as network settings, permissions, and access controls.
* **Monitor Activity per Tenant**: Track network usage and activity logs specific to a tenant for auditing or troubleshooting.

This feature is particularly useful for organizations with multiple departments or clients who need segregated VPN networks for security and management purposes.

![](/files/mREzqvdrF06OTJFoz3D7)

There are two types of tenants, each succinctly described in the image below.

![](/files/yVQETIUWbl2ayC9rRSzk)


# FAQ

Frequently asked questions (FAQ) about the Netmaker SaaS

<details>

<summary><strong>What is a Tenant on SaaS?</strong></summary>

A: <https://help.netmaker.io/en/articles/9891089-what-is-a-tenant-on-saas>

</details>

<details>

<summary><strong>What is Managed Endpoint and what can i use it for?</strong></summary>

A: <https://help.netmaker.io/en/articles/9903171-what-is-managed-endpoint-and-what-can-i-use-it-for>

</details>

<details>

<summary><strong>How to add billing address on my invoice?</strong></summary>

A: Go to <https://account.netmaker.io/profile> and then click the drawer “Optional Details for Invoice” to open it. Input the necessary information and then click Save. You’ll see the changes in your next invoice.

</details>

<details>

<summary><strong>Does Netmaker SaaS support IPv6 like its Self-hosted counterpart?</strong></summary>

A: You can create IPv4, IPv6, or dual-stack networks in Netmaker SaaS, and add both IPv4 and dual-stack machines. However, IPv6-only machines are not yet supported. We are actively working to enable IPv6 support for our load balancer, which manages traffic for Netmaker SaaS tenants. In the meantime, you can host your own instance of Netmaker on a dual-stack server to accommodate IPv6-only machines.

</details>

<details>

<summary><strong>How do I find my Tenant ID?</strong></summary>

A: <https://help.netmaker.io/en/articles/9974164-how-to-find-server-url-or-tenant-id>

</details>

<details>

<summary><strong>While checking my account I noticed a strange host that I haven't added, or at least can't recollect doing so. I have already removed it, but I'd like to know what it was?</strong></summary>

A: That was the Managed Endpoint associated with your server, which was provided so that you can use it as a Failover, Relay, Remote Access Gateway, etc. It's a dedicated netclient maintained on our infrastructure to perform network functions. You're welcome to remove it from your networks if you prefer not to have any external hosts, but we would recommend in that case designating another machine in your network as a Failover at the very least, to maintain good network availability.

</details>

<details>

<summary><strong>I have noticed that in the Metrics / Clients it says the total sent for some of my locations is very high. Are these numbers right?</strong></summary>

A: It's a known issue with traffic metrics. We are working on a fix that will be available in future releases.

</details>

<details>

<summary><strong>How do I close my account?</strong></summary>

A: <https://help.netmaker.io/en/articles/9892517-how-to-cancel-your-netmaker-subscription-a-step-by-step-guide>

</details>


# How To Guides

This section provides practical, step-by-step instructions for common Netmaker tasks — including setup, configuration, troubleshooting, and feature usage.

## Identity Provider Integration Guide

A quick-start guide for integrating Identity Providers like Google Workspace, Azure AD, Okta, GitHub, and OIDC with Netmaker. Includes setup steps for OAuth, API permissions, and user/group sync.

* Identity Provider Integration Guide
* IdP Integration – Technical implementation guide

## Integrating Non-native Devices

Guide for integrating devices that are not natively supported by Netmaker.

## How To Run Netclient On OpenWRT

Instructions for running the Netclient on OpenWRT devices.

## How to Setup a Full Mesh Site-to-Site VPN with Netmaker

Guide for configuring a full-mesh site-to-site VPN topology using Netmaker.

## How to Secure IT Operations with Netmaker

This document explains how to use Netmaker to secure IT operations with private, encrypted networks, covering traffic control, scalability, and zero-trust best practices for cloud, on-prem, and hybrid infrastructures.

## Generate Config Files using API and NMCTL

Instructions for generating Netclient configuration files using the Netmaker API and the nmctl CLI tool.

## Stabilize Netclient Connections Behind NAT

Guidance on stabilizing Netclient connections for clients located behind NAT.

## Securely Interconnecting EC2 Instances Across Private Amazon VPC Subnets Using Netmaker

Guide for securely connecting EC2 instances across private VPC subnets with Netmaker.

## NAT Traversal

Information and steps related to NAT traversal techniques and configuration.

## External Guides

Collection of external resources and guides related to Netmaker.

If you'd like, I can:

* Convert this index into GitBook cards with links (if you provide URLs for each guide), or
* Create individual pages for any of these guides from source content you supply.


# Identity Provider Integration Guide

IdP Integration – Technical implementation guide

## Identity Provider Integration Guides

Each supported identity provider (Google, Microsoft Entra ID, Okta, GitHub, and OIDC) includes **detailed configuration instructions within its integration modal under Settings → Security & Authentication,** ensuring a simple and well-guided setup process.

![](/files/lm8QMPokly1nqAjVZKJA)

## Integrating Google Workspace

![](/files/bXd1k66i1uIGJfE1IcA5)

### Prerequisites

Ensure you have a Google account with the following permissions:

* Create or manage projects
* Manage OAuth Credentials and Consent screen

If you do not have these permissions, please contact your Google Workspace administrator.

{% stepper %}
{% step %}

### Create a Google Cloud Project and Configure OAuth

Go to the [Google Cloud Console](https://console.cloud.google.com/).

* If you haven't already, create or select a project.
* Navigate to **APIs & Services** → **OAuth consent screen**.
  * Choose **Internal** (for Workspace users only).
  * Fill in application name, support email, and developer contact info.
* Save and continue.
  {% endstep %}

{% step %}

### Create OAuth2 Credentials

* Go to **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth client ID**.
* Choose **Web application**.
* Add <https://api.{NM\\_BASE\\_DOMAIN}/api/oauth/callback> as an Authorized redirect URI.
* Save and copy Client ID and Client Secret.
  {% endstep %}

{% step %}

### Configure API Permissions

* Navigate to **Google Cloud Console** → **APIs and services** → **Enabled APIs and services** → **Enable APIs and services**.
* Search "Admin SDK API" and click **Enable**.
* Navigate to **APIs and services** → **Credentials** → **Create credentials → Service account**.
* Configure the service account details:
  * Name: Give the service account a meaningful name.
  * ID: Choose a unique ID for the service account.
  * Description: Provide a brief description outlining its purpose.

Set Permissions:

* Role: Assign the Service Account Token Creator role to this account.

This permission enables the service account to generate short-lived access tokens on behalf of other service accounts.

* Copy the service account email address.
* Create a service account key.

{% hint style="warning" %}
Make sure the `constraints/iam.disableServiceAccountKeyCreation` policy is **not enforced**, as it's required for Netmaker to create Service Account keys.

If you do not have the required permissions to modify this policy, contact your GCP Organization Administrator. The role required to adjust this policy is `roles/orgpolicy.policyAdmin` (assignable only at the organization level).
{% endhint %}

**Steps to update the policy (if needed):**

1. Switch to your Organization using the top-left dropdown in the Google Cloud Console.
2. Go to IAM & Admin → IAM and assign yourself the role mentioned above.
3. Disable the `constraints/iam.disableServiceAccountKeyCreation` constraint in the Organization Policies
   {% endstep %}

{% step %}

### Delegate Domain-wide Access

* Navigate to [Admin Console](https://admin.google.com/) → **Security → Access and data control → API controls → Domain-wide delegate → Manage Domain-Wide Delegation.**
* Add new and configure the Service Account client ID and the following scopes:

```plaintext
https://www.googleapis.com/auth/admin.directory.group.readonly
```

```plaintext
https://www.googleapis.com/auth/admin.directory.group.member.readonly
```

```plaintext
https://www.googleapis.com/auth/admin.directory.user.readonly
```

{% endstep %}

{% step %}

### Grant Scopes in Admin Console

* Navigate to **Admin Console** → **Account** → **Admin roles**.
* Click **Create new role**.
* Configure role name and enable the following API privileges:
  * Groups → Read
  * Users → Read
* Once the role is created, click **Assign Admin** → **Assign service accounts**, and enter the email address of the service account we created.
  {% endstep %}

{% step %}

### Configure Netmaker

1. Navigate to the Netmaker Dashboard → Settings → Security & Authentication. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
2. Click **Integrate** under **Google Workspace**.
3. Configure the OAuth Client ID and Client secret.
4. Enter the email of a Workspace admin for user/group access.
5. Upload the Service Account JSON file.
6. Optionally, configure synchronization. (By default, synchronization is enabled.)
7. Optionally, configure prefixes for users and groups to be synced from IdP. (By default, all users and groups are synced.)
8. Click **Finish**.
   {% endstep %}
   {% endstepper %}

## Integrating Microsoft Entra ID (Azure AD)

![](/files/is970RfAkVkK5aiCKmhX)

### Prerequisites

Ensure you have an Azure account with the following permissions:

* Create Microsoft Entra ID apps
* Manage Microsoft Entra ID apps

If you do not have these permissions, please contact your Azure administrator.

{% stepper %}
{% step %}

### Create and Configure Microsoft Entra ID Application

* Log in to the [Azure Portal](https://portal.azure.com/).
* Select **Microsoft Entra ID** from the list of services.
* Click on **+ Add**.
* Select **App registration** and fill in the form:

  * Name: `Netmaker`
  * Supported Account Types: Accounts in this organizational directory only (Default Directory only - Single tenant)
  * Platform: `Web Application`
  * Authorized redirect URI: <https://api.{NM\\_BASE\\_DOMAIN}/api/oauth/callback>

  Example: <https://api.nm.167-172-115-84.nip.io/api/oauth/callback>
* Click **Register** to create the application.
  {% endstep %}

{% step %}

### Grant API Permissions

* In your registered app, navigate to **API permissions** in the left-hand menu.
* Click **+ Add a permission**:
  * Choose **Microsoft Graph**.
  * Select the **Application permissions** tab.
* Under **Select permissions**, add:
  * `User.Read.All`
  * `Group.Read.All`
* Click **Add permissions**.
* Grant admin consent by clicking **Grant admin consent for Default Directory**, then confirm by clicking **Yes**.
  {% endstep %}

{% step %}

### Generate a Client Secret

* Go to **Certificates & secrets** in the left-hand menu.
* Click **+ New client secret**.
* Add a description (e.g., `Netmaker`) and click **Add**.
* Copy the Client Secret Value immediately — you’ll need this for Netmaker configuration.
  {% endstep %}

{% step %}

### Retrieve Application (Client) ID and Directory (Tenant) ID

* In the left-hand menu, select **Overview**.
* Copy the following values:
  * Application (Client) ID
  * Directory (Tenant) ID
    {% endstep %}

{% step %}

### Configure Synchronization Settings (Optional)

* Synchronization Interval: `24` hours (default)
* Groups to Synchronize:
  * By default, all groups are synchronized. To filter by prefix, specify the prefix (case-sensitive).
* Users to Synchronize:
  * By default, all users are synchronized. To filter by prefix, specify the prefix (case-sensitive)
    {% endstep %}
    {% endstepper %}

## Integrating Okta

![](/files/wMxds8YSR4KjMVa6lC75)

### Prerequisites

Ensure you have access to an Okta Admin account with permissions to:

* Create and manage applications
* Generate API tokens

If you do not have these permissions, please contact your Okta administrator.

{% stepper %}
{% step %}

### Create and Configure Okta Application

* Log in to the Okta Admin Console.
* Navigate to **Applications** → **Applications**, then click **Create App Integration**.
* In the **Create App Integration** dialog:
  * Sign-in method: Select **OIDC - OpenID Connect**
  * Application type: Choose **Web Application**
* Fill in the application details:
  * App integration name: `Netmaker`
  * Sign-in redirect URIs: `https://api.{NM_BASE_DOMAIN}/api/oauth/callback`
* Click **Save**
  {% endstep %}

{% step %}

### Collect Application Credentials

* After saving, go to the app’s **General** tab and locate **Client Credentials**.
* Copy the following values:
  * Client ID
  * Client Secret
* Navigate to the **Sign On** tab:
  * Scroll to **OpenID Connect ID Token**
  * Click **Edit**
  * Change **Issuer** from **Dynamic** to **Okta URL**
  * Click **Save**
* Copy the Okta URL — this will serve as the Issuer URL in the Netmaker configuration.
  {% endstep %}

{% step %}

### Generate an API Token (Optional – For Sync)

* In the Okta Admin Console, go to **Security** → **API** → **Tokens**.
* Click **Create token** and fill out the form:
  * Name: `Netmaker`
  * API call origin: Select a suitable value based on your organization's policy. If unsure, choose **Any IP**.
* Click **Create token**
* Copy the token value immediately — this will be used for synchronization.
  {% endstep %}
  {% endstepper %}

## Integrating GitHub

![](/files/FDHzq8bDGtlLfWzydFXe)

### Prerequisites

Ensure you have a GitHub account with the following permission:

* Ability to register an OAuth application

{% stepper %}
{% step %}

### Register an OAuth Application in GitHub

* Go to [GitHub Developer Settings](https://github.com/settings/developers).
* Under **OAuth Apps**, click **New OAuth App**.
* Fill in the form with the following values:

| Field                      | Value                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| Application Name           | Netmaker                                                                                              |
| Homepage URL               | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io></p>                    |
| Application Description    | Authorization for Netmaker                                                                            |
| Authorization Callback URL | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io/api/oauth/callback></p> |

* Click **Register Application**.
  {% endstep %}

{% step %}

### Enter Client Credentials

* After registering the app, you will receive a Client ID and a Client Secret.
* In the Netmaker dashboard: Go to **Settings → Security & Authentication.** ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
* Choose **GitHub** as the provider, and enter the Client ID and Client Secret obtained from GitHub. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
  {% endstep %}
  {% endstepper %}

## Integrating Generic OpenID (OIDC) Provider

![](/files/B0nwy6hTJ3Bbo9Fow7ow)

### Prerequisites

Ensure you have the necessary permissions to register an OAuth (OIDC) application with your Identity Provider (IdP).

If you lack these permissions, please contact your IdP administrator.

{% stepper %}
{% step %}

### Register an OAuth Application in Your OIDC Provider

* Navigate to your OIDC provider’s application settings page.
* Find and select the option to add/register a new OAuth (OIDC) application.
* Fill in the application form with the following details:

| Field                            | Value                                                                                                 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Application Name                 | Netmaker                                                                                              |
| Application Description          | Authorization for Netmaker                                                                            |
| Homepage URL / Authorized Origin | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io></p>                    |
| Authorization Callback URL       | <p>\[Enter your Netmaker callback URL]<br>e.g: <https://dashboard.netmaker.io/api/oauth/callback></p> |

* Complete the registration to generate the required credentials.
  {% endstep %}

{% step %}

### Enter Client Credentials

* Once your OIDC application is registered, make sure to note the following values:
  * Client ID
  * Client Secret
  * OIDC Issuer URL (e.g., <https://corp.okta.com/oauth2/default>)
* In the Netmaker dashboard: Go to **Settings → Security & Authentication.** ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
* Select **OIDC** as the provider. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)
* Enter the Client ID, Client Secret, and OIDC Issuer URL from your OIDC application. ![](https://docs.netmaker.io/docs/how-to-guides/Base64-Image-Removed)

Reference for OIDC: <https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid\\_connect>
{% endstep %}
{% endstepper %}

## OAuth Users

Users are able to join a Netmaker server via OAuth by clicking the “Continue with SSO” button on the dashboard’s login page.

![](/files/QWyd7akDq6MHygG9gMj1)


# Netmaker Desktop - Intune Deployment Guide

This guide walks you through deploying Netmaker Desktop to Windows devices using Microsoft Intune, including automatic configuration and startup.

### **📦 Overview**

This deployment will:

* Install Netmaker Desktop silently
* Configure the client with your Netmaker server
* Ensure Netmaker starts automatically on user login
* Launch the app immediately after installation

***

### **🧾 Prerequisites**

Before proceeding, ensure:

* You have access to **Microsoft Intune**
* You have the Netmaker Desktop installer:

  netmaker-desktop-installer.exe
* You know your Netmaker server address:

  <https://api.domain>

***

### **⚙️ Step 1 - Prepare Deployment Package**

Create a folder with:

netmaker-intune-package/

├── netmaker-desktop-installer.exe

├── install.ps1

***

### **📝 Step 2 - Configure Installation Script**

Create a file named:

install.ps1

Paste the script below and **replace your server domain**:

"server": "api.domain"   # <<< REPLACE THIS

```powershell
$ErrorActionPreference = "Stop"

# -------------------------------
# Logging Helpers
# -------------------------------
function Log-Info {
    param([string]$msg)
    Write-Output "[INFO] $msg"
}

function Log-Error {
    param([string]$msg)
    Write-Output "[ERROR] $msg"
}

function Log-Success {
    param([string]$msg)
    Write-Output "[SUCCESS] $msg"
}

# -------------------------------
# Paths
# -------------------------------
$FolderPath = "C:\Users\Public\netmaker-rac"
$FilePath   = "$FolderPath\ctx.json"
$ExePath    = ".\netmaker-desktop-installer.exe"
$AppPath    = "C:\Program Files\Netmaker Desktop\netmaker-desktop.exe"
$TaskName   = "NetmakerDesktopStartup"

# -------------------------------
# JSON content
# -------------------------------
$JsonContent = @'
{
  "server": "server.domain"
}
'@

try {

    # -------------------------------
    # Create folder
    # -------------------------------
    Log-Info "Creating config directory..."
    if (!(Test-Path $FolderPath)) {
        New-Item -ItemType Directory -Path $FolderPath -Force | Out-Null
    }

    # -------------------------------
    # Write JSON
    # -------------------------------
    Log-Info "Writing ctx.json..."
    $JsonContent | Set-Content -Path $FilePath -Encoding ASCII -Force

    # Validate JSON
    Log-Info "Validating configuration..."
    Get-Content $FilePath | ConvertFrom-Json | Out-Null

    # -------------------------------
    # Verify installer
    # -------------------------------
    Log-Info "Checking installer..."
    if (!(Test-Path $ExePath)) {
        Log-Error "Installer EXE not found"
        exit 1
    }

    # -------------------------------
    # Install
    # -------------------------------
    Log-Info "Installing Netmaker Desktop..."
    Start-Process $ExePath -ArgumentList "/quiet /norestart" -Wait

    # -------------------------------
    # Verify install
    # -------------------------------
    Log-Info "Verifying installation..."
    if (!(Test-Path $AppPath)) {
        Log-Error "Netmaker executable not found after installation"
        exit 1
    }

    # -------------------------------
    # Scheduled Task
    # -------------------------------
    Log-Info "Configuring startup task..."

    if (schtasks /Query /TN $TaskName 2>$null) {
        schtasks /Delete /TN $TaskName /F | Out-Null
    }

    schtasks /Create `
        /TN $TaskName `
        /TR "`"$AppPath`"" `
        /SC ONLOGON `
        /RL HIGHEST `
        /F | Out-Null

    # -------------------------------
    # Launch app
    # -------------------------------
    Log-Info "Launching Netmaker Desktop..."
    Start-Process -FilePath $AppPath

    Log-Success "Installation completed successfully"
    exit 0

}
catch {
    Log-Error $_.Exception.Message
    exit 1
}
```

***

#### **🔧 What the script does**

* Creates config file:

  C:\Users\Public\netmaker-rac\ctx.json
* Installs Netmaker silently
* Verifies installation
* Creates startup task
* Launches Netmaker

***

### **📁 Step 3 - Package for Intune**

Use Microsoft Win32 packaging tool:

IntuneWinAppUtil.exe -c \<folder> -s install.ps1 -o \<output-folder>

This generates:

netmaker.intunewin

***

### **☁️ Step 4 - Upload to Intune**

In Intune:

Apps → Windows → Add → Win32 app

Upload:

netmaker.intunewin

***

### **⚙️ Step 5 - Configure App Settings**

#### **🔹 Install command**

powershell.exe -ExecutionPolicy Bypass -File install.ps1

#### **🔹 Uninstall command (optional)**

"C:\Program Files\Netmaker Desktop\uninstall.exe" /quiet

***

### **🖥️ Step 6 - Detection Rule**

Set detection rule:

File exists:

C:\Program Files\Netmaker Desktop\netmaker-desktop.exe

***

### **👥 Step 7 - Assign to Users/Devices**

* Assign to:
  * Device group OR
  * User group

Recommended:

👉 Assign to **Devices** for consistency

***

### **🔄 Step 8 - Deployment Behavior**

Set:

* Install behavior: **System**
* Logon requirement: **Whether or not user is logged in**
* Device restart: **No specific action**

***

### **🔁 Step 9 - Verify Deployment**

After deployment:

#### **✅ Check installation**

C:\Program Files\Netmaker Desktop\netmaker-desktop.exe

#### **✅ Check config file**

C:\Users\Public\netmaker-rac\ctx.json

#### **✅ Check scheduled task**

schtasks /Query /TN NetmakerDesktopStartup

***

### **🚀 What happens on user machine**

* Netmaker installs silently
* Config is applied automatically
* App starts immediately
* App launches on every login

***

### **⚠️ Troubleshooting**

#### **❌ Installer not found**

* Ensure EXE is packaged with script

***

#### **❌ App not launching**

* Check scheduled task:

schtasks /Query /TN NetmakerDesktopStartup

***

#### **❌ JSON config invalid**

* Verify:

{

"server": "your-domain"

}

***

#### **❌ App not detected by Intune**

* Confirm detection path:

C:\Program Files\Netmaker Desktop\netmaker-desktop.exe

***

### **🔐 Security Notes**

* Script runs with **elevated privileges**
* Configuration stored in:

  C:\Users\Public\\
* Ensure server domain is correct and trusted


# Integrating Non-native Devices

## Introduction

Netmaker manages WireGuard configurations through the Netclient and the Netmaker Desktop (formerly Remote Access Client, RAC) installed on the hosts and on the external clients respectively. Basically Netmaker makes WireGuard configurations, which are inherently static, dynamic. As you setup and change your network, Netmaker propagates these changes in the configuration to the affected machines installed with either Netclient or Netmaker Desktop (or RAC mobile).

However in some cases, it might not be ideal or even possible to install Netclient or Netmaker Desktop on some of your machines/devices. In these cases, Netmaker will rely upon your intervention to install WireGuard on these machines/devices and then to manually set up or change their WireGuard configurations whenever necessary. Basically, you just need to get the current WireGuard configuration (or VPN config files) from your Netmaker Gateway on the Netmaker web UI and then stick it to your device in order for it to connect to your Netmaker network.

## Generating a WireGuard Configuration File on Remote Access Gateway

Netmaker allows you to generate and manage your VPN configuration files. For instructions on how to make a node a Gateway and on how to create/generate VPN configuration files.

You can also get the WireGuard VPN configuration by following these steps:

{% stepper %}
{% step %}

### Navigate to Gateways

Navigate to your network’s Gateways page. You should see the Gateways table.
{% endstep %}

{% step %}

### Select Gateway

If you have multiple gateways, select the specific one by clicking on its row if it hasn’t been selected already.
{% endstep %}

{% step %}

### Open Config Files

Click on the Config Files button.
{% endstep %}

{% step %}

### Find the VPN Configuration

If necessary, find the VPN configuration by inputting its name in the Search box.
{% endstep %}

{% step %}

### View, Download or Scan QR

Once you’ve located the configuration file, hover over or click on its ‘kebab’ icon to the right-hand side of the row. A context menu should show up similar to the screenshot below.

![Get WireGuard Client Config](/files/6f4b266f00f2731545b3dc610b5982b19fb022f9)

You can view and copy the configuration file by clicking on the ‘View Config’ option, or click on the ‘Download’ option to get a copy of the configuration file. You could also scan the QR code.

![View WIreGuard Client Config](/files/09f0fb52933ea7b0c8a2b5c0df70d4360aebbae6)
{% endstep %}
{% endstepper %}

Once you have the configuration information or the configuration file, you can now apply it to your router, IoT, or other edge devices.

## Routers and Firewall Appliances (Virtual or Bare metal)

While Netclient can be installed on some routers and firewall appliances after which you can then configure as egress gateways, it is generally ideal to use these devices’ built-in VPN feature for seamless integration. Since most modern VPN routers and firewall appliances today support WireGuard, they can connect to a Netmaker network as an external client, after which you can then responsibly expose the resources behind these routers by inputting specific IP address ranges in the ‘Additional Addresses’ field. For more information on the Egressing External Clients, please refer to this link [here](/features/egress#egressing-external-clients).

![Client additional IP addresses range](/files/ad472bfd970ec46f2b3db9f73af37b85bab6e18c)

The general guidelines for integrating routers and firewall appliances (FWA) to Netmaker are the following:

* Before doing any further configuration, take note of your current firmware version and back up the current configuration settings
* Upgrade your firmware if necessary
* Install WireGuard via your router’s or FWA’s Package Manager. Usually this can be done from its web interface (GUI) instead of from its shell (CLI)
* Input the VPN configuration information from Netmaker; or upload the configuration file if your device supports it
* If necessary, create a routing entry for the WireGuard tunnel interface
* Create tight and specific firewall rules for traffic going in and out between the VPN interface and your LAN \[or depending on your use case, your specific device, interface/port, VLAN, DMZ, WAN, etc.]

### pfSense

This guide will help you set up WireGuard on pfSense 2.7.2. We will connect to a Netmaker network via a Remote Access Gateway.

{% stepper %}
{% step %}

### Install WireGuard package

Install WireGuard using the Package Manager in System -> Package Manager -> Available Packages.

![pfSense Package Manager](/files/eb1a35d4d8ae8c4085c6169d8b427825ce875bf8)
{% endstep %}

{% step %}

### Create WireGuard tunnel

Go to VPN -> WireGuard -> Tunnels, and then create a new WireGuard tunnel using the configuration information provided by Netmaker. Click on the Generate button under the Interface Keys fields before pasting the Private Key (from the configuration file generated by Netmaker). Save or submit the form and then take note of the tunnel interface name.

![pfSense Tunnel Configuration](/files/75d5ad0b04c2ff17a148f887e070dd53465aadaa)
{% endstep %}

{% step %}

### Create a peer

Go to VPN -> WireGuard -> Peers, and then create a peer. Input the necessary configuration information similar to the image shown.

![pfSense Peer Configuration](/files/52de8e5ab53ae549270ca1673e85c87ddd0e9d06)
{% endstep %}

{% step %}

### Enable WireGuard

Enable WireGuard in VPN -> WireGuard -> Settings, and then click on the Apply Changes button. Make sure that the ‘handshake’ icon is green under the Status tab before proceeding any further.

![pfSense enable WireGuard](/files/bfb12cde80644a0ea993499341b29cac488a105d)
{% endstep %}

{% step %}

### Assign interface

Go to Interfaces -> Assignments, and then assign or add a new interface for the WireGuard tunnel you created earlier. Take note of the interface name (for example OPT1).

![pfSense assign WireGuard tunnel interface](/files/1dabf3344f9e4035eeee3228683794ff797783c6)
{% endstep %}

{% step %}

### Configure interface settings

Go to Interfaces -> \[OPT1], tick the ‘Enable interface’ checkbox, input the MTU, static IP address, and the Netmaker network prefix.

![pfSense go to the WireGuard tunnel interface](/files/000b9c427de626bedb6d9f620cc8818407644ffb) ![pfSense enable WireGuard tunnel interface](/files/b8eaa378ab0e9d7cc649c97239d36aa50624722b)

If you’re trying to connect to a Netmaker Internet Gateway, click on the ‘Add a new gateway’ button. Depending on your use case, you may tick the Default Gateway checkbox so that all internet traffic will route through the Netmaker Internet Gateway. Then go to System -> General Setup and, depending on your use case, select the Netmaker Internet Gateway in the DNS Server Settings so that domain name resolution traffic will pass through it instead of the other gateways.

![pfSense create an internet gateway](/files/546fd36efcbbde1433bfc3328d018dccc3f586e3)
{% endstep %}

{% step %}

### Create firewall rule (if needed)

If you just need to connect to an Internet Gateway, you don’t need to do this step. Otherwise, create a Firewall rule allowing traffic from the Netmaker network to the target resource. In this guide we allow ICMP traffic to the LAN so that we can do pings. Go to Firewall -> Rules -> \[OPT1] and add a rule similar to the screenshots below.

![pfSense add firewall rule](/files/108e73b6c3b8a9787ce9a2c294aafa860c9f51a3) ![pfSense add firewall rule - form](/files/9ca23854fb4d7ebf68ca2e4153d66094e4930322)

After saving the firewall rule, nodes from your Netmaker network should now be able to ping the egress ranges you’ve specified, and vice versa. Edit the firewall rule or create another one specific to your needs.
{% endstep %}
{% endstepper %}

### OPNsense

This guide will help you set up WireGuard on OPNsense 24.1\_1. We will connect to a Netmaker network via a Remote Access Gateway.

{% stepper %}
{% step %}

### Install WireGuard (if needed)

WireGuard comes pre-installed on OPNsense 24.1\_1. For OPNsense 23.7.12 and below, install WireGuard as a plug-in in System -> Firmware -> Plugins.
{% endstep %}

{% step %}

### Create tunnel instance

Go to VPN -> WireGuard -> Settings -> Instances, and then create a new WireGuard tunnel instance using the configuration information provided by Netmaker. Click on the Generate \[gear] icon in the Public Key field before pasting the Private Key (from the configuration file generated by Netmaker). Save and then take note of the tunnel interface name.

![OPNsense Tunnel Configuration](/files/8509ffef96b2a8885f3a1be304daa79a593a6b7a)
{% endstep %}

{% step %}

### Create peer

Go to VPN -> WireGuard -> Settings -> Peers, and then create a WireGuard peer using the information provided by Netmaker.

![OPNsense Peer Configuration](/files/5095ebd633822c57a5cc96b0d4ab113ac57ce25d)
{% endstep %}

{% step %}

### Enable WireGuard

Enable WireGuard in VPN -> WireGuard -> Settings -> General. Then click on the Apply Changes button.

![OPNsense enable WireGuard](/files/52e3a5741d35943c7131b8ab904145d0fdae4ec3)
{% endstep %}

{% step %}

### Assign interface

Go to Interfaces -> Assignments, and then assign or add a new interface for the WireGuard tunnel you created in the previous step. Take note of the interface name (for example OPT1).

![OPNsense assign WireGuard tunnel interface](/files/0d901054d2cfa30fe7f0efa7c22a99e949ff2324)
{% endstep %}

{% step %}

### Enable interface

Go to Interfaces -> \[OPT1], and then tick the ‘Enable interface’ and the ‘Prevent interface removal’ checkboxes.

![OPNsense enable WireGuard tunnel interface](/files/95ef991a9087d2d3a411cc1cf7eda63f01a58201)
{% endstep %}

{% step %}

### Create gateway and route

Create a route to the Netmaker network by first creating a gateway. Go to System -> Gateways -> Configuration, then click on the add icon and specify the tunnel interface \[OPT1] and its IP.

![OPNsense add gateway](/files/f7a3d13675bcf48c56e21a441db31b0a62bc1965)

Add the necessary routing entry. Go to System -> Routes -> Configuration, then click on the ‘add’ icon and specify a route to the Netmaker network via the gateway created in the previous step.

![OPNsense add routing entry](/files/965feb1d9a3c3685e0c8e5bcc38a0e6a721644ba)
{% endstep %}

{% step %}

### Create firewall rule

Create a Firewall rule for WireGuard allowing traffic between it and the target resource. In this guide we allow ICMP traffic between WireGuard tunnel interface and the LAN so that we can do pings. Go to Firewall -> Rules -> \[OPT1] and add a rule similar to the screenshot below.

![OPNsense add firewall rule - form](/files/f69572c4c136de11cd9bbd9bf831ea50cf561ce2)

After saving the firewall rule, devices in your LAN should now be able to ping machines in your Netmaker network, and vice versa. Edit the firewall rule or create one that suits your needs.
{% endstep %}
{% endstepper %}

### MikroTik

This guide will help you set up WireGuard on MikroTik 7.15.3. We will connect to a Netmaker network via a Remote Access Gateway.

{% stepper %}
{% step %}

### Ensure WireGuard is available

WireGuard comes pre-installed on MikroTik 7.15.3 so you don’t have to do anything.
{% endstep %}

{% step %}

### Apply WireGuard configuration via CLI

Given a sample WireGuard configuration below, access MikroTik’s CLI and issue the corresponding commands.

![Sample WireGuard configuration for MikroTik](/files/5fdd22e21907ff08dcc8471b666e3782be6625e0)

WireGuard interface configuration:

{% code title="MikroTik - WireGuard interface" %}

```plaintext
/interface/wireguard
add name=wg-netmaker mtu=1420 private-key="iMfHqGANXMJHGMBKwuo89txiU3/9edC20TxWpFtmU2Y="
```

{% endcode %}

Peer configuration:

{% code title="MikroTik - Peer" %}

```plaintext
/interface/wireguard/peers
add allowed-address=10.40.70.0/24 endpoint-address=188.166.235.45 endpoint-port=51821 interface=wg-netmaker public-key="GM80g/eeXgkOrk0yYtdhhU73ETHffpojG2Ewd+N4kXI=" persistent-keepalive=20 client-dns=159.159.159.159
```

{% endcode %}

IP and routing configuration:

{% code title="MikroTik - IP and routing" %}

```plaintext
/ip/address
add address=10.40.70.254/32 interface=wg-netmaker
/ip/route
add dst-address=10.40.70.0/24 gateway=wg-netmaker
```

{% endcode %}

And that’s it. Devices from your LAN should now be able to reach machines in your Netmaker network, and vice versa.

For more information, please refer to this guide from MikroTik’s documentation page: <https://help.mikrotik.com/docs/display/ROS/WireGuard>

Routing internet traffic to a Netmaker Internet Gateway is also possible by adding the necessary firewall NAT rules. Please refer to the MikroTik documentation for more information.
{% endstep %}
{% endstepper %}

### OpenWrt

This guide will help you set up WireGuard on OpenWrt 23.05.2. We will connect to a Netmaker network via a Remote Access Gateway.

{% stepper %}
{% step %}

### Install WireGuard packages

Go to System -> Software. Click on the Update lists… button then search for WireGuard. Install WireGuard-tools and luci-proto-WireGuard (for Web GUI). Reboot.

![OpenWrt software manager](/files/5a05babb720d5afc656b177da62a556eabc328c0)
{% endstep %}

{% step %}

### Add WireGuard interface

Go to Network -> Interfaces, and then add a new WireGuard tunnel interface.

![OpenWrt - create tunnel interface](/files/551423b2537d83ec6a28a2726cb8c4d203a86e22)
{% endstep %}

{% step %}

### Import configuration

Click on the Load Configuration…, paste the WireGuard configuration and then click Import settings.

![OpenWrt - import WireGuard configuration](/files/d17161a60a2e742d4e05cab6a9cc41b2b675fe0e)
{% endstep %}

{% step %}

### Route Allowed IPs

Go to the Peers tab. Edit the generated peer, tick the Route Allowed IPs field. Save and apply the changes.

![OpenWrt - route allowed IPs](/files/4b8ba8a5784ff8c7b844c4a5952b332b285ea258)
{% endstep %}

{% step %}

### Check handshake

Go to Status -> WireGuard and make sure that a handshake has taken place. If successful, OpenWrt should be able to reach the Netmaker Remote Access Gateway but not the other way around.

![OpenWrt - WireGuard tunnel status](/files/99f9fb41ea997164e5b5f20bac9c0285f44eb050)
{% endstep %}

{% step %}

### Configure firewall zone

Go to Network -> Firewall, and then add a zone allowing traffic between the WireGuard tunnel and the LAN. Please add your own version of Firewall rules that are tight and specific to your needs. Save and apply the changes.

![OpenWrt - Firewall configuration](/files/193f047e09d2b99e4e8a85e6d3ac89edf9b1e63f)

Routing internet traffic to a Netmaker Internet Gateway is also possible by adding the necessary firewall NAT rules. Please refer to the OpenWrt documentation for more information.
{% endstep %}
{% endstepper %}

### Other routers

Please refer to these links for instructions on how to configure WireGuard:

* TP-Link - <https://www.tp-link.com/fr/support/faq/3772/>
* Asus - <https://www.asus.com/support/faq/1048281/>
* GL.iNet - <https://docs.gl-inet.com/router/en/3/tutorials/WireGuard\\_client/#setup-WireGuard-client>
* Teltonika - <https://wiki.teltonika-networks.com/view/WireGuard\\_Configuration\\_Example>
* pcWRT - <https://www.pcwrt.com/2019/12/how-to-set-up-a-WireGuard-vpn-client-connection-on-the-pcwrt-router/>
* DD-WRT - <https://windscribe.com/knowledge-base/articles/WireGuard-router-setup-guide-dd-wrt>

## Note on the Router Guides

The router guides assume that machines behind your router or firewall appliance point to it as the gateway. If in your case they don't you have two options:

{% stepper %}
{% step %}

### Add postrouting masquerade rule on your router

For example, on MikroTik you can execute the command:

{% code title="MikroTik - NAT masquerade example" %}

```plaintext
/ip firewall nat
add chain=srcnat action=masquerade out-interface=bridge1
```

{% endcode %}

This assumes that your LAN is bridged. If not you can leave out the `out-interface`. But a blanket masquerade rule is not recommended. add `dst-address=<ip-of-your-device-in-same-network-as-mikrotik>`
{% endstep %}

{% step %}

### Add static routes

Option 1 - on the machines that are in the same network as your router; to route all Netmaker VLAN traffic to the router that is running WireGuard.

Option 2 - on the default gateway; to route all Netmaker VLAN traffic to the router that is running WireGuard.
{% endstep %}
{% endstepper %}

## Internet of Things (IoT Devices)

Please refer to these links for instructions on how to configure WireGuard:

* IOTstack - <https://sensorsiot.github.io/IOTstack/Containers/WireGuard/>
* Embedded Linux - <https://www.toradex.com/blog/embedded-linux-vpn-application>
* lwIP IP stack - <https://github.com/smartalock/WireGuard-lwip>

## Other Devices

For other devices not covered above, please refer to your device’s documentation for instructions on how to install and configure WireGuard.

## Disclaimer

The information provided by us on this how-to guide is for general informational purposes only. All information on this page is provided in good faith, however we make no representation or warranty of any kind, express or implied, regarding the accuracy, adequacy, validity, reliability, availability or completeness of any information on the page.

Under no circumstance shall we have any liability to you for any loss or damage of any kind incurred as a result of the use of this how-to guide or reliance on any information provided on the page. Your use of the how-to guide and your reliance on any information on the page is solely at your own risk.


# How To Run Netclient On OpenWRT

{% stepper %}
{% step %}

### Step 1: Setup Storage

Installing large packages on OpenWRT can be challenging due to limited storage space on many routers. To expand your firmware's space to install more packages, refer to this OpenWRT article:

<https://openwrt.org/docs/guide-user/additional-software/extroot\\_configuration>
{% endstep %}

{% step %}

### Step 2: Install WireGuard

Netmaker uses WireGuard for VPN communication. Ensure that your OpenWRT device has WireGuard installed. It’s recommended to install WireGuard via the web UI:

* Go to System → Software
* Click the “Update lists…” button, then search for WireGuard
* Install wireguard-tools and luci-proto-wireguard (for the web GUI)
* Reboot
  {% endstep %}

{% step %}

### Step 3: Install and Configure Netclient

Netclient can be run as a Docker container or installed directly on the host machine. Note: Docker Netclients on version 0.24.3 and earlier have a known bug fixed in 0.25.0.

To install the kernel version, copy and paste the install command (remove sudo if running on OpenWRT) and execute it. You can then join a Netmaker network using the enrollment key or by using the netclient join command.

*NOTE: Netclient versions 1.2.0 and 1.4.0 cannot be installed directly on OpenWRT. Workaround: install Netclient version 1.0.0 and let it auto-upgrade to v1.4.0 (or whatever version your server uses).*

![](/files/Q0sskXw5uNDocGrHERXI)

As of Netclient v0.25.0, installation may show this error:

error running command: /etc/init.d/netclient stop

This has no known consequence on OpenWRT and can be ignored.

Alternative: run Netclient as a Docker container on OpenWRT. See the OpenWRT Docker guide:

<https://openwrt.org/docs/guide-user/virtualization/docker\\_host>

Install Docker and Docker Client with:

```plaintext
opkg update
opkg install dockerd docker
```

Once installed, run and join Netclient with the `docker run` command. Consider adding `--restart=always` so the container runs after router boot.

![](/files/HkzAEBUdzAJd8ov6sVjt)

Notes:

* After joining, OpenWRT will be able to access resources within the Netmaker network.
* By default, devices on the Netmaker network will not be able to ping the OpenWRT machine, and OpenWRT will not act as a Remote Access Gateway, Relay, Egress Gateway, or Internet Gateway until firewall rules are adjusted. This is expected because OpenWRT’s firewall blocks that traffic by default.
  {% endstep %}

{% step %}

### Step 4: Register the Tunnel Interface

The tunnel interface that Netclient creates is recognized as a device named by default "netmaker." Create a new unmanaged interface via LuCI:

Network → Interfaces → Add new interface

* Name: netmakerif (any name)
* Protocol: Unmanaged
* Device: netmaker

![](/files/16b8d2e5982c06bb5dd6f9583ad7d2a7ca499a28)

Click "Create interface". In the modal form, if you are running CoreDNS on your Netmaker server, go to Advanced Settings and specify the public IP of the server in "Use custom DNS servers". Click Save.

![](/files/6d75f1d8716e8480850f81eaa3d3f2b9a255090e)

To persist changes, click "Save & Apply" and then reboot the router.

![](/files/8898ac44cce079dc81c83055e6ef37ee3503e2d0)
{% endstep %}

{% step %}

### Step 5: Create Firewall Zone

Create a firewall zone for the Netmaker interface via LuCI:

Network → Firewall → Zones → Add

* Name: netmakerzn (or any other name)
* Input: ACCEPT
* Output: ACCEPT
* Forward: ACCEPT
* Masquerading: on
* MSS Clamping: on
* Covered networks: netmakerif (or your custom interface name)

Allow forward to destination zones:

* Select LAN and/or any other internal zones to allow Netmaker resources to reach devices in these zones (useful if OpenWRT is an Egress Gateway).
* Select WAN if you intend to use OpenWRT as an Internet Gateway / exit node.

Allow forward from source zones:

* Select your LAN and/or other internal zones to allow machines there to reach Netmaker resources (required if using this device as a gateway in site-to-site setups). Leave blank otherwise.

Click Save, then Save & Apply.

![](/files/041c7ad2905c56f6c704e56ec760ab6eeec59893)

After saving, the firewall zone table should include the new entry.
{% endstep %}

{% step %}

### Step 6: Add Port Forwarding Rules (for Remote Access Gateway)

Only necessary if OpenWRT should function as a Remote Access Gateway. Create a port forward via LuCI:

Network → Firewall → Port Forwards → Add

Create port forwarding rules from WAN to "netmakerzn".

* Name: netmaker (or any other name)
* Protocol: TCP/UDP
* Source Zone: WAN
* External port: 51821 (or any port; default 51821). To find the port: in NMUI, open the Netmaker network → Remote Access tab → find OpenWRT → view the VPN config. In the \[Peer] section, look for the number after the IP address in Endpoint.
* Destination zone: netmakerzn (or the name from Step 5)
* Internal IP address: Netmaker IP address of OpenWRT
* Internal Port: 51821

Click Save, then Save & Apply.

![](/files/8e60139c85db9940bba83f881a7848d5ea692d15)

It is crucial to review routes and firewall rules configured by Netclient on your OpenWRT device.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
If you choose to run Netclient in Docker, you may need to create users and groups and set appropriate folder permissions. For simplicity in demos, containers are sometimes run as root, but consider security implications for production.
{% endhint %}

{% hint style="warning" %}
Disclaimer

The information in this guide is for general informational purposes only. No warranty is made regarding the accuracy, reliability, or completeness of the information. Use this guide at your own risk. The authors and maintainers are not liable for any loss or damage resulting from the use of this guide.
{% endhint %}


# How to Setup a Full Mesh Site-to-Site VPN with Netmaker

> “I have three sites: a data center, an office, and an edge location. I want network resources at each site to access network resources at the other sites without having to install a software client on every machine in each location.” – Netmaker User

If you have a similar use case, this guide is for you. While it is sleek to install Netclient or the Remote Access Gateway (RAC) on every machine in your network for seamless end-to-end encrypted traffic, there are cases where that might not be ideal or even possible. Fortunately, Netmaker is fully capable of enabling the interconnection of various network types across different sites via a secure full mesh Virtual Private Network (VPN). This allows encrypted Layer 3 (L3) network communication among different sites.

![](/files/e369d333ab7dcc4188eabfc419596a6ce9ca46d0)

## Guide Overview

In this guide we’re going to create a full mesh site-to-site VPN for a multinational corporation. Our job is to establish a secure and scalable virtual network infrastructure that connects corporate headquarters with regional branches and remote offices to support the distributed nature of its IT system. This infrastructure combines cloud computing with on-premise servers, allowing for both centralized control and localized operations where needed.

## Implementation Methods

Netmaker provides flexibility in implementation based on how networks are configured. While uniform deployment across all sites may be ideal, this guide will demonstrate four practical methods of interconnecting sites. For simplicity of this guide, the final result will be a full mesh site-to-site VPN setup across four crucial subsidiary sites of the corporation.

* Site 1 — corporate cloud infrastructure hosted in a Virtual Private Cloud (VPC) network (front-facing servers and backend servers).
* Site 2 — branch behind an OpenWRT router capable of running Netclient (on-premise servers, workstations, network devices).
* Site 3 — remote office behind a NAT router not capable of running Netclient (workstations, on-premise servers).
* Site 4 — another remote office behind a NAT router not capable of running Netclient.

We will begin by interconnecting Site 1 and Site 2 and then expand from there.

## Initial Setup

Since we are not installing VPN software on every machine, it is essential to ensure that the sites and the Netmaker network do not have overlapping address ranges. For example, connecting two sites that both use the `192.168.1.0/24` network will not work. Similarly, connecting a site using the `192.168.1.0/24` network to another using the `192.168.0.0/16` network will cause issues. This rule also applies to Virtual LANs (VLANs).

In this guide, we will use the following address spaces:

* Netmaker Network: `100.100.0.0/16`
* Site 1 (VPC Network): `10.124.0.0/20`
* Site 2 (Behind OpenWRT with Netclient): `172.16.0.0/16`
* Site 3 (Behind NAT Router without Netclient): `192.168.123.0/24`
* Site 4 (Behind NAT Router without Netclient): `192.168.111.0/24`

As you can see, there is no overlap between the network spaces above.

This guide assumes you have access to your Netmaker server. Let's start by creating the Netmaker network that will interconnect all these networks across the sites. We will name it "site-to-site-mesh-vpn". For added functionality, we will create a dual-stack network.

![](/files/RoiQHy2ZVOaOItrHpFyV)

Next, create an enrollment key for the network to allow machines to join. We will call it "mesh-vpn-key".

![](/files/0ae84d11e16beefb97cc48bac673711485c083bf)

Now that we have everything set up, we can proceed with interconnecting the first two sites.

## Interconnecting Site 1 and Site 2

Site 1 is hosted in a VPC Network without a router. It often contains public-facing web servers and backend servers without public addresses. Because some cloud-hosted servers must initiate connections with other sites, a two-way communication is required.

For Site 1, deploy a virtual machine with Netclient to act as the secure tunnel gateway (tunnel gateway / tunnel router). In Netmaker, the Egress Gateway feature handles encrypted traffic going out from different sites into the VPC network. For outgoing traffic from the VPC to other sites, configure routing either on the initiating devices or via the VPC’s routing capabilities (see “Set Up Routes in Site 1’s VPC Network”).

For Site 2, use the OpenWRT router (capable of running Netclient and with WireGuard in kernel) as the tunnel gateway.

By the end of this section, you should have a VPN setup where hosts in Site 1 and Site 2 can reach one another as if on adjacent LANs.

![](/files/c3ca777cbf3419c22510b47925e85494fdf098d3)

Steps overview:

{% stepper %}
{% step %}

### Install and Setup Netclient

We only need to install Netclient on the VPN tunnel gateway at each site, not on every device in the network.

Notes:

* Netclient uses UDP port 51821 by default — allow inbound/outbound UDP 51821 on cloud firewalls if applicable.
* For Site 1, install Netclient on the public Ubuntu VM that will act as the Egress Gateway.

Procedure:

1. After logging in to Netmaker server, go to the network ("site-to-site-mesh-vpn"), click "Add Nodes", and then "Add New Device".
2. Choose platform and architecture (e.g., Linux AMD64). Copy the installation command and execute it on your machine. After installation, copy and execute the join command on the Ubuntu machine. Click Finish to close the modal.

![](/files/bY6BKJsMQkOToeDLkKXR)

After a short while the machine should appear in the Netmaker UI under Devices.

For Site 2 (OpenWRT), follow the guide: <https://docs.netmaker.io/docs/how-to-guides/how-to-run-netclient-on-openwrt>

When configuring the Firewall Zone on OpenWRT, specify “LAN zone” in both “Allow forward to destination zones” and “Allow forward from source zones”. ![](https://docs.netmaker.io/Base64-Image-Removed)
{% endstep %}

{% step %}

### Set the Machines as Egress Gateways

With each site’s gateway joined to "site-to-site-mesh-vpn", configure them as Egress Gateways.

1. Go to the Egress page and click "Add Route".&#x20;

   <figure><img src="/files/3e2c49dc03d6b3f788040cbebe228355c68451d9" alt=""><figcaption></figcaption></figure>
2. In the modal, give the route a descriptive name. Leave "Enable NAT for egress traffic" enabled initially (you can disable later if you need original source IPs). <br>

   <figure><img src="/files/1b5c0cae645ea29242e96ad49646825d782a5634" alt=""><figcaption></figcaption></figure>
3. Select the Egress Gateway machine for Site 1, then click Next. <br>

   <figure><img src="/files/0462efecfdc02fdc02c52d558f8cb2c41b43b5fa" alt=""><figcaption></figcaption></figure>
4. Set an access policy for the egress route: click "Add Resources Policy", enable it, set Source to All Resources, then Finish. &#x20;

   <figure><img src="/files/21005c0dcd451ec9b700e8b035070c67c632e1b6" alt=""><figcaption></figcaption></figure>

You should see the newly created route in the Egress table and the access policy under Access Control.&#x20;

You can expose whole networks (e.g., `10.124.0.0/20`) or specific ranges and individual IPs (e.g., `10.124.0.1/32`, `10.124.0.2/32`, `10.124.0.5/32`) by creating multiple egress routes. ![](https://docs.netmaker.io/Base64-Image-Removed)
{% endstep %}

{% step %}

### Verify Two-Way Connectivity and Configure Site 2 Egress

At this point:

* Site 2’s machines should be able to reach Site 1’s exposed addresses.
* Site 1’s machines may not be able to reach Site 2 yet because Site 1’s hosts are not using the Site 1 Egress Gateway as their default gateway.

To enable Site 1 → Site 2 traffic:

1. Configure the OpenWRT router (Site 2) as an Egress Gateway in Netmaker and expose Site 2’s network (or subset).&#x20;

   <figure><img src="/files/016ac032b49450e055864da8604d42753880f5b5" alt=""><figcaption></figcaption></figure>

After configuring Site 2 as an Egress Gateway:

* Site 1’s Egress Gateway machine will be able to reach devices in Site 2.
* Other machines in Site 1 still need routes pointing to the Site 1 tunnel gateway in order to reach Site 2 (see next step).<br>

  <figure><img src="/files/204b204427bfb33e3a7487b2a2a90390822b33cd" alt=""><figcaption></figcaption></figure>

{% endstep %}
{% endstepper %}

### Set Up Routes in Site 1’s VPC Network

Static routes in the VPC must point to the local IP address of the machine functioning as the tunnel gateway. Typical routes to add:

* Routes to each remote site (e.g., Site 2’s `172.16.0.0/16`).
* Route to the Netmaker VPN network (optional, `100.100.0.0/16`).
* Routes to any other egress external client address ranges (optional).

Where to add the routes depends on your cloud provider:

* VPC-level global routing table (preferred where supported).
* Or add to each VM’s routing table (tedious but viable).

For this demonstration we add a static route on the Site 1 File Server (Ubuntu) using netplan.

Edit the netplan YAML file (typically `/etc/netplan/<your-machine-default-config>.yml`) and add a `routes:` entry under the appropriate interface (e.g., `eth1`), routing `172.16.0.0/16` via the Site 1 Egress Gateway IP (e.g., `10.124.0.6`).

![](/files/7bcad1c1799b4716b4c2e272bf4ea855f12e93c5)

Note: Some providers (e.g., Google Cloud) may override VM netplan changes — consult your provider for persistent static route methods.

For Site 2 there’s no need to add static routes to each device because the OpenWRT router is the default gateway for the local network.

Once static routes are in place on Site 1 hosts (or at VPC-level), devices from Site 1 should reach devices from Site 2 and vice versa.

## Disabling NAT for Egress Traffic

By default we enabled NAT (Masquerade NAT) for egress traffic. NAT causes the Egress Gateway’s IP to be used as the source IP when traffic reaches its destination, which simplifies connectivity but hides original client IPs.

If you require original source IPs (for IP-based allowlisting or security controls), disable NAT for egress traffic on both Site 1 and Site 2 Egress Gateways.

Trade-offs:

* With NAT disabled, only hosts that have proper routes pointing to the tunnel gateway (or when you configure routes globally at the VPC level) will be reachable from the other site.
* If you do not configure global routes, only the hosts that have static routes will be reachable.

![](/files/c2cbbfefc4fe944712be61f06c5b95e3c78b7623)

## Site-to-Site IPv4 Over IPv6 Tunnel

Netmaker v0.99.0+ supports IPv4-over-IPv6 tunnels (encapsulating IPv4 in IPv6). If you use IPv4-over-IPv6, OpenWRT requires an additional firewall/NAT rule to disable address rewrite:

* Go to Firewall → NAT Rules and add a rule set to `ACCEPT - Disable address rewrite`.
* Save and Apply changes.

![](/files/04a4857ebdfd2439c088c3c8a2594868f8ac9055)

This ensures seamless two-way communication for IPv4-over-IPv6 scenarios.

## More to come

Stay tuned for additional methods that interconnect Sites 3 and 4.


# How to Secure IT Operations with Netmaker

This document explains how Netmaker enhances IT security through private, encrypted networking, covering traffic control, scalability, and zero-trust practices across cloud, on-prem, and hybrid environments.

It also describes how to securely access resources across remote sites, supporting distributed teams, remote workers, and field operations. It further enables secure connectivity for on-site users accessing infrastructure hosted in other locations, such as production systems in different regions or countries.

The example illustrates how users can securely connect to critical remote resources, ensuring reliable and protected access across all environments.

![](/files/07dd65e64d4bffbe0d88257b1de0be545c97a3c1)

As illustrated in the diagram, users initiate access through a Gateway within the Netmaker network. The Gateway then routes traffic to Egress Gateways—machines connected to both their respective remote site networks and the Netmaker network. In this scenario, the Egress Gateways operate behind NAT routers.

This tunnel-based connection provides end users with encrypted access to remote site resources, such as intranet or file servers, ensuring secure and seamless communication with the target network.

## Prerequisites

* Access to a running Netmaker server, either self-hosted or hosted in the cloud (SaaS).
* A Linux machine at the remote location.
* Access to the router at the remote location, or at least sufficient access to add a Port Forwarding rule.
* OAuth integrated on the Netmaker server (refer here for more information: [Integrating OAuth](https://learn.netmaker.io/how-to-guides/identity-provider-integration-guide))

## General Steps

{% stepper %}
{% step %}

### Plan your network

Ensure the remote sites, the Netmaker network, and optionally the end-user network do not have overlapping address ranges. Overlaps can cause traffic to prefer directly connected devices rather than the intended remote resources.

Example address spaces used in this guide:

* Netmaker network: 100.100.0.0/16
* Remote Site: 192.168.254.0/24
* User network: 192.168.111.0/24

Network name used in this guide: "my-org-vpn".

For detailed instructions on creating a VPN network in Netmaker, see: [Create Networks](https://learn.netmaker.io/getting-started/walkthrough/how-to-create-networks).
{% endstep %}

{% step %}

### Set up remote access with a Gateway

A Gateway (Ingress Gateway) should be publicly reachable. The Netmaker server or Managed Endpoint (SaaS) can act as the RAGw, or you can add a separate machine.

Only UDP port 51821 needs to be exposed for Netclient communication.

Ubuntu example (UFW):

```plaintext
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 51821/udp

# if ufw is not yet enabled,
sudo ufw enable

# if ufw is already enabled,
sudo ufw reload
```

{% hint style="info" %}
You can use nftables as a replacement if you're using Linux machines that have deprecated iptables.
{% endhint %}
{% endstep %}

{% step %}

### Set up Egress Gateways

Egress Gateways are Linux machines running Netclient on the remote site's network that expose internal routes into the Netmaker VPN.

To join machines to the Netmaker VPN: see [Add Non-User Devices](https://learn.netmaker.io/getting-started/about/how-it-works/0.-overview#add-non-user-devices). Only UDP port 51821 needs to be exposed as with a Gateway.

Steps to create and configure an Egress Gateway in the Netmaker Admin UI:

{% stepper %}
{% step %}

### Create an Egress

* In the Netmaker VPN network, open the Egress tab.
* Click Create Egress.
* Select the machine from the host dropdown.
* Leave “NAT egress traffic” enabled and click Create Egress.
  {% endstep %}

{% step %}

### Add external routes

* Under the Egress Gateways table, click the newly created host.
* Click the “Add external route” button.
* In the Update Egress modal, click “Add range”.
* To expose an entire LAN, specify the network (e.g., 192.168.254.0/24). To expose specific hosts, use individual addresses (for example 192.168.254.3/32).
  {% endstep %}
  {% endstepper %}

<figure><img src="/files/Z4culLgjkm4QHH787K0C" alt=""><figcaption></figcaption></figure>

If the Egress Gateway is behind NAT, set a static listening port for that host to avoid relays or unexpected UDP port changes:

{% stepper %}
{% step %}

* Login to the Netmaker server.
* Navigate to Hosts, find the Egress Gateway host, hover the kebab icon and click Edit Host.
* Enable the Static Port switch.
* Click Update Device.
  {% endstep %}
  {% endstepper %}

![](/files/hQR9RnFJRE1ACeCQBQzH)
{% endstep %}

{% step %}

### Add port forwarding rules on the remote site's router

Routers frequently block unsolicited inbound traffic. Add a port forwarding rule for UDP 51821 to the Egress Gateway private IP to allow encrypted VPN traffic into the private network.

Example on a Mikrotik router (web UI):

* IP => Firewall => NAT => Add New
* In Action, set “To Addresses” to the Egress Gateway private IP.
* Apply and OK.

![](/files/b865081ab71c10d83793c85ee4c324242f079375) ![](/files/9ca85d2f1eaeacbfda39e2e7227cb3f4e581ef73) ![](/files/81130bfda960743e50383e1644a96e940c22b18d)

Please refer to your router’s documentation for specific instructions.
{% endstep %}

{% step %}

### Onboard users

Provide users with access via one of these methods:

* Give users credentials (Basic Auth) — Self-hosted only.
* Send invites (email) — requires SMTP on Self-hosted, or available on SaaS.
* Let users sign up themselves using OAuth/SSO.

Refer to [User Management](https://learn.netmaker.io/features/user-management).

We demonstrate assigning the Service User role. Service Users use the Netmaker Desktop app to log in; this is preferred to sharing config files.
{% endstep %}
{% endstepper %}

***

### Setup a Gateway

{% content-ref url="/pages/8023dcd81897c9bc7f43477add0ae990e6caf0ac" %}
[Gateways](/features/gateways)
{% endcontent-ref %}

### Setup Egress Gateways

{% content-ref url="/pages/JzR5OuRy0q2ubwhXsqhS" %}
[How to Add Egress](/getting-started/walkthrough/how-to-add-egress)
{% endcontent-ref %}

## Onboarding Users — Methods and UI Steps

### Giving users their login credentials (Basic Auth — Self-hosted)

{% stepper %}
{% step %}

### Create a basic account

* Login to the Netmaker Admin UI.
* Navigate to User Management.
* Click on "Create User" button
* Input Username and Password, tick Service User.
* Select a group to assign the user.
* Click Create User.

<figure><img src="/files/OkaZO6EbKLyKI78QCw8T" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

Instruct users to download and run the [Netmaker Desktop](https://learn.netmaker.io/getting-started/server-and-client-management/client-installation/netmaker-desktop-installation) and log in using the provided username and password, or via SSO if OAuth/IdP is configured.

### Inviting Service Users (email invites)

This method uses email addresses as usernames. Users set their own password or use SSO. Invites are sent via email.

Note: SMTP configuration is required for Self-hosted Netmaker. SaaS Netmaker has SMTP configured.

#### Setting up SMTP (Self-hosted)

Configure an SMTP provider (for example, a Gmail app password via <https://myaccount.google.com/apppasswords>) and set it up in the admin UI Dashboard under **Settings → Email Configuration.**

<figure><img src="/files/QJG8VNIhKJdyVHOT8tbt" alt=""><figcaption></figcaption></figure>

#### Invite flow

{% stepper %}
{% step %}

* Login to the Netmaker Admin UI.
* Navigate to User Management.
* Click on "Create User" button
* Specify email(s), tick Service User.
* Select a group to assign the user.
* Click Create User Invite(s), then Finish.

<figure><img src="/files/n7g99wmErqHpqXejaTw0" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

You can invite multiple emails separated by commas (no spaces needed). Ask users to check their email and use the invitation link.

#### End-user signup via invite link

Users follow the invite link and can sign up using SSO (Google, Microsoft, Okta, GitHub) or provide their own password. The chosen method is what they will use with Netmaker Desktop.\ <br>

<figure><img src="/files/VvUM9TP60NX9zPyAIiC0" alt=""><figcaption></figcaption></figure>

### Letting users sign up by themselves (SSO/OAuth)

If OAuth is integrated on your Self-hosted Netmaker server, users can self-signup via Netmaker Desktop or web UI:

* Example server domain: my-netmaker.my-org.com
* Web UI: <https://dashboard.my-netmaker.my-org.com>
* Netmaker Desktop Server field: api.my-netmaker.my-org.com&#x20;

Once users sign up via OAuth/SSO, admins must approve and grant access:

{% stepper %}
{% step %}

* Login as admin or superadmin.
* Navigate to User Management → Pending Users.
* Find the user and click Approve (confirm OK).
* Go to Users tab, find the user and click their email.
* Select Service User in Platform Access Level.
* Under Additional Roles Per Network, for “my-org-vpn” select the Remote Access Gateway host.
* Click Update User.

<figure><img src="/files/6FdsIu3kI4gVnjKEbbxi" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

After approval, the user can login using Netmaker Desktop and access the assigned Gateway.

## Using Netmaker Desktop to Access a Server in a Remote Site Network

Service Users use Netmaker Desktop. They must specify the server to connect to:

* Self-hosted: domain prefixed with api. (as given by the admin).
* SaaS: Tenant ID (GUID) from Tenants table.<br>

<figure><img src="/files/jcLyfmkyo95JeO9aIJvI" alt=""><figcaption></figcaption></figure>

Example connection (demo server `dentest.clustercat.com`): authenticate with the invited user credentials or log in with OAuth/SSO as applicable. After logging in, the assigned Gateway appears — click Connect.

If the RAGw has multiple endpoints, the endpoint chooser (›) allows selecting IPv4 vs IPv6 endpoint.

A WireGuard tunnel interface is created on the client. Traffic is routed: client → Remote Access Gateway (100.100.0.2) → Egress Gateway (100.100.0.3) → target server (e.g., 192.168.254.4).

![](/files/nDiw45ODBxAMKKixRUQP)

Example: SSH to the remote server’s private IP over the tunnel works because application traffic is encapsulated within the WireGuard tunnel. Only UDP 51821 needs to be open on RAGw and Egress Gateway; no other ports need exposure for services in the remote LAN.

![](/files/YQSWXOTQN3mgLQ9s5oyZ)

Hope you find this guide helpful and informational.

***


# Generate Config Files using API and NMCTL

Power users may wish to bulk-create and manage WireGuard config files for their network. For this, we recommend using the API or NMCTL.

## Generating Clients via API

Static client configurations can be generated using the createExtClient endpoint of the netmaker API. Authorization to the API is required to access relevant endpoints.

{% stepper %}
{% step %}

### Authenticate and get a JWT

Generate and grab a JWT token from the authenticate API endpoint using the following curl command (<https://openapi.netmaker.io/#tag/authenticate/operation/authenticateUser>):

{% code title="Authenticate and get JWT" %}

```bash
curl -X POST --location 'https://api.netmaker.example.com/api/users/adm/authenticate' \
  --header 'Content-Type: application/json' \
  --data '{ "username":"<netmaker username>", "password":"<netmaker password>" }'
```

{% endcode %}

Copy the JWT token printed to the terminal to use for subsequent API requests.

![](/files/a19fa3d977ad49585cf4308a9beca1185269b140)
{% endstep %}

{% step %}

### Identify the Remote Access Gateway (Host Network ID)

The createExtClient endpoint requires the netmaker network name and the Remote Access Gateway’s Host Network ID (also referred to as Device Network ID). To get the Host Network ID, navigate to the netmaker network and click the host name to reveal the id.

![](https://docs.netmaker.io/Base64-Image-Removed)
{% endstep %}

{% step %}

### Create a static client via API

Use the extclients endpoint to generate a static client configuration. The endpoint documentation: <https://openapi.netmaker.io/#tag/ext\\_client/operation/createExtClient>

Replace , , and in the command below:

{% code title="Create static client" %}

```bash
curl -X POST -L "https://api.netmaker.example.com/api/extclients/<network name>/<host network id>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AuthToken>" \
  --data '{"clientid":"SiteC"}'
```

{% endcode %}

On successful execution, the POST request returns no body or error. To list all static client configurations for a network:

{% code title="List static clients" %}

```bash
curl -X GET -L "https://api.netmaker.example.com/api/extclients/<network name>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AuthToken>"
```

{% endcode %}

To retrieve the WireGuard config for a specific static client:

{% code title="Get WireGuard config for static client" %}

```bash
curl -X GET -L "https://api.netmaker.example.com/api/extclients/<network name>/<static client id>/file" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AuthToken>"
```

{% endcode %}

The extclients API endpoint can be used to generate, delete, and remotely manage static client configurations in bulk and can be integrated into automation systems.
{% endstep %}
{% endstepper %}

***

## Create Clients via NMCTL

NMCTL is a CLI utility for interacting with the netmaker server. It authenticates and makes API calls to the netmaker server via a CLI.

### Setup NMCTL

{% stepper %}
{% step %}

1. Download the latest NMCTL tool from: <https://github.com/gravitl/netmaker/releases/latest>

Make sure to download the build that matches your CPU and OS architecture.
{% endstep %}

{% step %}
2\. Ensure the nmctl binary is executable (set executable permissions) after downloading.
{% endstep %}

{% step %}
3\. Authenticate and add the netmaker server to the CLI context.

Run the following to set a context (replace placeholders):

{% code title="Set context" %}

```bash
nmctl context set <context name> --endpoint=https://api.netmaker.example.com --username=<username> --password=<password>
```

{% endcode %}

Then use the context:

{% code title="Use context" %}

```bash
nmctl context use <context name>
```

{% endcode %}

The context name should be unique to identify and manage multiple netmaker servers via nmctl.
{% endstep %}
{% endstepper %}

### Create Client

{% stepper %}
{% step %}
Identify two pieces of information:

* The netmaker network name where the gateway resides and where static clients will be created.
* The Host Network ID of the Remote Access Gateway (Device Network ID). To obtain it, navigate to the netmaker network and click the host name to reveal the id.

![](/files/roWI0abVoU2MtJqNmCJj)
{% endstep %}

{% step %}
Generate a static client configuration:

{% code title="Create static client with nmctl" %}

```bash
nmctl ext_client create <network name> <host network id> --id <static client id>
```

{% endcode %}

The static client id must be unique to identify and manage different client configurations.
{% endstep %}

{% step %}
If the command responds with "Success", the static client was created successfully.
{% endstep %}
{% endstepper %}

### Get Client

Retrieve the static client configuration created above:

{% code title="Retrieve static client config" %}

```bash
nmctl ext_client config <network name> <static client id>
```

{% endcode %}

This will return the WireGuard configuration file for the static client, usable for setting up the WireGuard plugin on the device.

![](/files/6118a6a958c9948cb72ac3286fed3b9a178249e6)

### Other Options with NMCTL

NMCTL provides options to delete and update static clients. To view available ext\_client commands:

{% code title="nmctl ext\_client help" %}

```bash
nmctl ext_client --help
```

{% endcode %}

![](/files/98f961123bd7b13745807a701578b181a16b5cf9)


# Stabilize Netclient Connections Behind NAT

For sites behind NAT routers, you can stabilize the connection to the netclient by setting up port forwarding, and setting a static port for the Netclient.

## Port Forwarding

Set up port forwarding rules to forward traffic from the WAN to the machine with Netclient installed. Use custom ports such as 55555.

Here is an example of setting up port forwarding to a generic Linux machine that uses an iptables firewall.

{% stepper %}
{% step %}

### Enable IP forwarding at the kernel level

By default, most systems have forwarding turned off. To turn port forwarding on permanently, edit the /etc/sysctl.conf file with sudo privileges:

{% code title="/etc/sysctl.conf" %}

```
```

{% endcode %}

```
sudo nano /etc/sysctl.conf
```

Inside the file, add this line at the bottom:

```
```

```
net.ipv4.ip_forward=1
```

Save and close the file.
{% endstep %}

{% step %}

### Apply sysctl settings

Apply the settings you added:

```
```

```bash
sudo sysctl -p
```

Then load the system-wide settings:

```
```

```bash
sudo sysctl --system
```

{% endstep %}

{% step %}

### Identify WAN and LAN interfaces

Find the WAN and LAN interfaces on the machine using:

```
```

```bash
ip a
```

(Example image)&#x20;
{% endstep %}

{% step %}

### Add DNAT rule to forward incoming traffic

Use the -j DNAT target of the PREROUTING chain in the nat table to forward incoming packets to the internal IP and port. Replace {PUBLIC\_IP} and {INTERNAL\_IP} with your values:

```
```

```bash
iptables -t nat -A PREROUTING -i eth0 -p udp -d {PUBLIC_IP} --dport 55555 -j DNAT --to {INTERNAL_IP}:55555
```

{% endstep %}

{% step %}

### Configure IP masquerading (SNAT)

Allow LAN nodes with private IP addresses to communicate with external public networks by masquerading outbound traffic on the external interface (e.g., eth0):

```
```

```bash
iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
```

{% endstep %}

{% step %}

### Result

Now the port forwarding rule for UDP port 55555 is set on the Linux machine and can be used for WireGuard/Netclient connections.
{% endstep %}
{% endstepper %}

<figure><img src="/files/9e1d9ba672c17df47d00e8df85f896a532c9536a" alt=""><figcaption></figcaption></figure>

## Assign Static Port

To stabilize connections for sites behind NAT routers, set each Netclient host port to "static" and specify the custom port from above (for example, 55555). You can configure this in the Netmaker web UI by going to "Hosts" and then "Edit Host" on the specific netclient hosts.

![](/files/DJ2aDxlzCdTed9WNrZql)


# Securely Interconnecting EC2 Instances Across Private Amazon VPC Subnets Using Netmaker

### Overview

Amazon Virtual Private Cloud (VPC) lets you provision a logically isolated networking environment with full control. A VPC contains one or more **subnets**, which are IP address ranges. Subnets can be **public** or **private**:

* **Public Subnets** have a direct route to an Internet Gateway. Resources in these subnets can access the internet directly.
* **Private Subnets** lack a direct internet route and require a **NAT device** (NAT Gateway or NAT Instance) to initiate outbound internet connections.

![](/files/65d4ab4d009f94f5098929fa5533140392e5aee0)

AWS provides two NAT options:

* **NAT Gateway** (fully managed by Amazon): Allows private subnet resources to access the internet, but does **not support port forwarding**.
* **NAT Instance**: A self-managed EC2 instance that supports **port forwarding**.

Additionally, **Security Groups** act as virtual firewalls, controlling inbound and outbound traffic for associated resources.

***

### Goal

Connecting devices behind NAT or restrictive firewalls can sometimes be tricky. This guide helps you securely interconnect EC2 instances within private subnets across different VPCs—whether or not those instances have Netclient installed. It covers both **Netmaker Pro** and **Community Edition** scenarios.

![](/files/401f33db6eefb16397eaa1d3e49a5214c8979c9a)

***

### Prerequisites

Netclient uses **UDP port 443** by default to communicate with other Netclients. This port must be allowed in your security group. Additionally, Netclient uses **TCP port 51821** by default for endpoint detection and metrics collection. Although not required, we recommend allowing this port in your security group as well.

For more information about the advantages of the endpoint detection feature, see: <https://help.netmaker.io/en/articles/10026438-what-is-endpoint-detection>

![](/files/f49079f0fd5d6b5bf4aae7b665c325b37bbb0412)

If a firewall is running on your EC2 instances, you’ll also need to allow these ports on each instance.

It’s also a good idea to temporarily enable **ICMP traffic** for testing purposes.

***

### Advantages of Netmaker Pro

Netmaker Pro is fully capable of interconnecting hard-to-reach edge devices with minimal intervention. It allows you to designate a publicly reachable device—such as the Netmaker Server—as a **Failover Node**. With this feature, Netmaker detects if peers are unable to communicate directly (for example, EC2 instances in different private subnets behind NAT). Netmaker will automatically reroute traffic through the Failover Node, enabling those peers to connect via that node.

![](/files/1af2ecce3da7319a822f8315e36fb9cc2e0642f5)

See: <https://docs.netmaker.io/docs/features/failover-servers-pro>

You can only designate one device as a Failover Node per VPN network. Note that this feature only works if the EC2 instances are running **Netclient**.

For larger deployments, Netmaker Pro also provides a **\[Relay] Gateway** feature. You can assign multiple Relay Gateways and control which nodes they relay traffic for. A Relay Gateway can be any public machine (or an EC2 instance running Netclient in a public subnet) which relays traffic to EC2 instances in a private subnet within the same VPC.

![](/files/81e57216d99b9a2f8e5050dfdf1a46dbed18c3c5)

See: <https://docs.netmaker.io/docs/features/gateways#relay-configuration>

If using a Failover Node or Relay Gateway is not an option—such as when using the **Community Edition** of Netmaker, or when aiming to minimize traffic hops—then additional manual configuration on AWS and on the devices is needed.

***

## For Community Edition Users

Note: Relay Gateway becomes available in Community Edition starting version 0.90.0.

To enable EC2 instances in different private subnets to communicate with each other, manual configurations—such as setting port forwarding and routing rules—are necessary.

As noted earlier, port forwarding can only be performed on a **NAT Instance**, not on a **NAT Gateway**. The sections below first cover NAT Instance setups, then NAT Gateway scenarios.

![](/files/d48ee85d7c32d092cfe958752ec41220cd4f8158)

First, plan the UDP port range you'll use. If you have multiple EC2 instances behind a specific NAT Instance, each must have its own unique port number. The dynamic/private port range **49152–65535** is suitable. If you have multiple private subnets, you may reuse the same port range across them (for example, 51821–52821), though it's recommended to use different port numbers per subnet due to observed AWS quirks.

Create a security group allowing the full chosen port range. This range must be allowed **both** on the public subnet (where the NAT Instance resides) and on the private subnet security groups.

On your NAT Instance, add port forwarding rules using iptables. Example for forwarding UDP port 51821 to a target instance at 192.168.0.140:

```bash
iptables -t nat -A PREROUTING -p udp --dport 51821 -m addrtype --dst-type LOCAL -j DNAT --to-destination 192.168.0.140:51821
```

You’ll need one corresponding rule for each EC2 instance running Netclient behind the NAT Instance.

Review configured rules:

```bash
iptables -t nat -v -L PREROUTING -n --line-number
```

Delete a rule by number:

```bash
iptables -t nat -D PREROUTING <rule-number>
```

Once everything looks good, save the rules using `iptables-save`/`iptables-restore` or the `iptables-persistent` package.

Your rules should look similar to the following screenshot:

![](/files/1259d149deb231621b81d8626fbf509844e8f0a7)

Then, in the NMUI, go to the **Devices** page and set each device's port to static using its corresponding port number.

![](/files/a9ca6e6703beb3d82531b223002f3f95341ab008)

After these steps, EC2 instances behind the NAT Instance should be able to securely communicate with other nodes in the Netmaker network via the encrypted tunnel.

***

## Securely Interconnecting EC2 Instances Behind a NAT Gateway

This scenario is similar to a full-mesh site-to-site setup but specific to AWS.

In this setup, you do **not** need to install Netclient (or anything at all) on EC2 instances in the private subnet behind a NAT Gateway. Instead, run Netclient on another EC2 instance in the public subnet (same VPC) to act as a secure tunnel gateway into your Netmaker network.

![](/files/ff990bb86fd6b91db9b274537e0be4f8a4e536b3)

Important: AWS does **not** route typical private subnet traffic to the public subnet by default. Therefore, your Netmaker network must use the **Shared Address Space**: 100.64.0.0 – 100.127.255.255 (recommended).

Once the public EC2 instance with Netclient has joined your Netmaker network, configure it as an **Egress Gateway**, exposing either the entire private subnet or specific hosts. Example subnets:

* Public subnet: 192.168.56.0/28
* Private subnet: 192.168.56.128/28

You can expose the entire private subnet (192.168.56.128/28) or individual hosts (e.g., 192.168.56.130/32, 192.168.56.135/32).

You may enable or disable **NAT for egress traffic**:

* If NAT is enabled, source addresses of traffic entering the private subnet will appear as the **Egress Gateway's Netmaker IP**.
* If NAT is disabled, the source address will be the requesting node's IP from within the Netmaker network.

If NAT is enabled, nodes in your Netmaker network can initiate and reach EC2 instances in the private subnet—but the private subnet hosts cannot initiate to the Netmaker network unless you add routes (see below).

![](/files/1d3e524dcf4da16000612a8bfc7b8e5bd7742fc0)

To allow two-way communication, add a route in your VPC so that traffic from the private subnet knows how to reach the Netmaker network via the Egress Gateway. For example, if your Netmaker network is 100.110.0.0/24, add a route pointing that prefix to the Egress Gateway instance.

![](/files/24e42f8e2d32d7477221d36a3c94bb79c5a66e78)

Additionally, because the Egress Gateway instance is not always the source or destination of the traffic it handles, **disable source/destination checks** on it. To do this:

{% stepper %}
{% step %}
Select the EC2 instance in the AWS console.
{% endstep %}

{% step %}
Go to Actions > Networking > Change source/destination check.
{% endstep %}

{% step %}
Tick the Stop checkbox and save.
{% endstep %}
{% endstepper %}

![](/files/ee0fe5e304d9ec7f9c04bb853cac98761f53776b) ![](/files/3397729dde677a27eee0cd38481a35d87380a64a)

After adding the appropriate VPC routes and disabling source/destination checks, two-way communication should be possible between EC2 instances in the private subnet and nodes in your Netmaker network.

Note: Route management is manual. If new egress ranges are added, you must manually add a VPC routing entry for each new range.

***


# NAT Traversal

Netmaker makes it easy to create secure, peer-to-peer networks over the internet — even when nodes are behind NAT (Network Address Translation). This guide walks you through ensuring that your VPN network is taking advantage of the NAT Traversal functionalities of Netmaker.

NAT (Network Address Translation) traversal is a technique that allows devices behind NAT firewalls to establish direct connections with each other or with devices on the public internet. Netmaker leverages WireGuard, STUN, and TURN servers to achieve this when direct connections aren't possible.

### Use Gateways

{% content-ref url="/pages/8023dcd81897c9bc7f43477add0ae990e6caf0ac" %}
[Gateways](/features/gateways)
{% endcontent-ref %}

### Ensure STUN Servers are Running

As of v0.18.0, Netmaker uses a STUN server (Session Traversal Utilities for NAT). STUN helps communications protocols detect and traverse NATs that are between two endpoints. By default, Netmaker uses publicly available STUN servers. You may set up your own STUN servers to augment or replace the public ones by updating the STUN\_LIST to include the STUN servers you want to use.

Two resources for installing your own STUN/TURN server:

* <https://github.com/coturn/coturn>
* <https://ourcodeworld.com/articles/read/1175/how-to-create-and-configure-your-own-stun-turn-server-with-coturn-in-ubuntu-18-04>
* <https://cloudkul.com/blog/how-to-install-turn-stun-server-on-aws-ubuntu-20-04/>

### References and Other Sources

* <https://learn.netmaker.io/how-to-guides/integrating-non-native-devices>
* <https://learn.netmaker.io/how-to-guides/how-to-setup-a-full-mesh-site-to-site-vpn-with-netmaker>
* <https://learn.netmaker.io/getting-started/server-and-client-management/client-installation/netclient-installation/stabilize-netclient-connections-behind-nat>
* <https://learn.netmaker.io/how-to-guides/securely-interconnecting-ec2-instances-across-private-amazon-vpc-subnets-using-netmaker>


# External Guides

Netmaker has many use cases, from a basic virtual network to an office gateway VPN to a Kubernetes underlay. It can be a bit overwhelming to figure out where to start. If you don’t find your use case here, but think Netmaker is a good fit, let us know!

## Video Tutorials

* [Intro/Overview](https://youtu.be/PWLPT320Ybo): Tutorial on first-time usage, setting up a mesh network.
* [Site-to-Site Gateway](https://youtu.be/krCKBJhwwDk): Tutorial on setting up site-to-site connections, allowing peers to access external networks via gateways.
* [IPv6 and Private DNS](https://youtu.be/b4diaKWUcXI): Tutorial on dual-stack IPv6 in Netmaker and Private DNS management (separate topics).
* [Kubernetes Networking](https://youtu.be/z2jvlFVU3dw): Tutorial on setting up cross-cloud Kubernetes clusters using Netmaker.

## Written Tutorials

* [K3s Cross-cloud cluster](https://itnext.io/how-to-deploy-a-single-kubernetes-cluster-across-multiple-clouds-using-k3s-and-wireguard-a5ae176a6e81): Tutorial on setting up cross-cloud K3s clusters using Netmaker.
* [MicroK8s Cross-cloud cluster](https://itnext.io/how-to-deploy-a-cross-cloud-kubernetes-cluster-with-built-in-disaster-recovery-bbce27fcc9d7): Tutorial on setting up cross-cloud MicroK8s clusters using Netmaker.
* [Secure access to private services](https://afeiszli.medium.com/how-to-enable-secure-access-to-your-hosted-services-using-netmaker-and-wireguard-1b3282d4b7aa): Tutorial on setting up secure Nextcloud with Netmaker.


# How to Use Netmaker with a Reverse Proxy

{% embed url="<https://www.youtube.com/watch?v=CGw4Kc424VE>" %}

### Overview <a href="#id-6114" id="id-6114"></a>

If you would like to publicly expose a service in your local network, you likely need a reverse proxy. You want the local service to be reachable over the public internet, but you want to do it securely. This article shows you how to use Netmaker to help reverse proxy traffic with WireGuard tunnels, and expose your local services to the world.

In this example, we assume you already have:

1. a Netmaker server
2. a local service (in this example, a web server)

With these in mind, you simply need to:

a. Join the Netmaker network from the local resource or

b. set up a forwarding node in the local network (Egress)

After that, you will&#x20;

1. deploy a reverse proxy server in the cloud
2. deploy a Netmaker node on that server.

After this is completed, your service will now be accessible to the internet, using a secure tunnel over the web.

### 1. Make the Service Accessible from Netmaker

To make the service accessible from Netmaker, you need to either deploy the Netclient on the local server, or set up forwarding to the local server using the Netclient and Egress from a co-located server.

See the documentation on deploying the Netclient [here](/getting-started/operations-field-guide/deploying-the-netclient).

If you've done this on the same server as your service, you can move on to the next step.

<figure><img src="/files/8NmYczZtFBZULN7vYya4" alt="" width="308"><figcaption></figcaption></figure>

#### Join the Network from a co-located device and forward traffic <a href="#a1ce" id="a1ce"></a>

Using a forwarding node (Egress) allows you to easily forward traffic to the target service. This is also a great approach if you have multiple services in the local environment you would like to expose. To deploy egress, check out the documentation [here](/features/egress).

<figure><img src="/files/4zi9wuxngcdy5CpSjmJ9" alt="" width="308"><figcaption></figcaption></figure>

### 2. Deploy a Reverse Proxy and Netclient Node in the Cloud <a href="#c4da" id="c4da"></a>

Next, we need a public service running in the cloud to forward our traffic. You will need to deploy a server to use for this purpose, which should have a public IP.

Once that is deployed, you will need a reverse proxy. For this example, we'll use [Caddy](https://caddyserver.com/).

On your node that will run the proxy:

1. Install docker if it’s not installed.
2. Install the Netclient and join the network, as in Step 1.
3. Create a file /root/Caddyfile as follows:

```
 http://yyy.yyy.yyy.yyy {
    reverse_proxy http://xxx.xxx.xxx.xxx:8090
}
```

xxx.xxx.xxx.xxx is replaced by:

a. The private IP address of the Netclient in the local (if Netclient is deployed on the same server as the webserver) or

b. The local address of the webserver (if Netclient has been set up as Egress)

yyy.yyy.yyy.yyy is replaces by:

* the public IP address of the server hosting the proxy.

Create a file /root/docker-compose.yml as follows:

```
version: "3.4"services:
  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    network_mode: host # Wants ports 80 and 443!
    volumes:
      - /root/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_conf:/config
volumes:
  caddy_data: {}
  caddy_conf: {}
```

Run `docker-compose up -d` and confirm that the container starts as shown by a message like this

```
Creating caddy ... done
```

Run `docker ps` and confirm that `caddy`is in the list

### 3. Test Reaching Your Service from Another PC <a href="#id-6075" id="id-6075"></a>

From your browser, try reaching the public IP by visiting this URL from a browser

```
http://yyy.yyy.yyy.yyy:8090
```

### Conclusion <a href="#cf6a" id="cf6a"></a>

You’ve been able to reach your local service from a machine on another physical network via the secure Netmaker network indirectly (via the reverse proxy). Congratulations!

You’ll want to clean up by urning off the service: close the main.go process on your web server which you can do by killing the process after getting the PID via

```
ps -eaf | grep main.go
```


# Set up a Static IP User VPN for Whitelisting, with WireGuard and Netmaker

This guide is intended for IT administrators who want to route user traffic through a static IP address for whitelisting purposes.

Why this is useful:

* Provide support staff with a single IP to whitelist on a customer firewall so support traffic can reach on-site services.
* Give a customer a single outbound, whitelisted IP by installing the VPN client locally and routing outbound traffic through your endpoint.

Netmaker lets you deploy an endpoint and route all internet-bound traffic through it; that endpoint’s public IP is what you can whitelist on firewalls. Follow the steps below.

{% stepper %}
{% step %}

### Log into your Netmaker dashboard

In your Netmaker dashboard (on-prem or cloud) you will see a Node already deployed. In the cloud version you select a region for your endpoint. On-prem, the server can act as an endpoint.

You can use the existing endpoint to route traffic, or deploy your own if you have a specific IP you want to use.

![Netmaker dashboard screenshot](/files/ff4e6ccb9fbf952ad19ea79e5760c8ad968ab2da)
{% endstep %}

{% step %}

### (optional) Deploy an endpoint

If you want to use a pre-existing IP, deploy the netclient on a device with that IP (note: must run Linux).

Click the “+Add device” button in the dashboard and follow the steps.

![Add device screenshot](/files/2e8d79e491262e3b58b40a5be8cd0850aa857e07)
{% endstep %}

{% step %}

### Set as Gateway to Internet

Once the node is visible in your dashboard, set it as a Gateway to route traffic from other VPN devices to the internet.

* Navigate to the “Gateways” screen.
* Click “+ Create Gateway” and select the node.<br>

  <figure><img src="/files/VY8yc2t7f12p4KPfB1cI" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Invite Users

As an administrator, invite users to use the VPN:

* Add their email addresses (or create usernames manually).
* Grant them access to the platform. (If using Pro, you can enable IDP sync to join automatically.)
* When inviting, select “Service Users” — this grants only the ability to use the VPN client.
* Add them to the group with access to the network (typically “\[network name] User Group”).
* Click “Create User Invites”.

<figure><img src="/files/qo0DQp7Otu7pxeexEkHo" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### User Access

Users need to:

* Download the VPN client from: <http://netmaker.io/download>
* Install the client.
* Log in with their credentials (username/password or OAuth).
* Select the network and toggle to connect/disconnect.

While connected, all the user’s internet traffic will flow through the endpoint you deployed.

![Client download/connection screenshots](/files/096ad5818de577a7560827d1179a003c71ad982e)

<figure><img src="/files/y9qSbE0zMQ3MeJgOkRir" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/TsCZBJuM3cGTI5DFpxJw" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

<figure><img src="/files/XJrhZzJeU5aEe1ysk7Sz" alt=""><figcaption></figcaption></figure>

{% endstep %}
{% endstepper %}

### That’s it!

Use the public IP of the endpoint when whitelisting traffic, and your users will have access.


# Remote Access VPN to Azure with WireGuard

![Header image](/files/3e98b0232abd2cde93de328de5cbc23eafcbe6a5)

### **Introduction**

When working with Microsoft Azure, it is common to deploy resources that should not be publicly accessible, such as Windows Servers or internal services. These resources are typically hosted within a **Virtual Network (VNet)** and secured using subnets and network security rules.

The key challenge is: **how can you securely access these private resources from outside Azure?**

Azure provides a native solution through **Azure VPN Gateway**. However, this option can become costly as the number of users, devices, or connections increases.

A lightweight and cost-effective alternative is to use **WireGuard®** in combination with **Netmaker**. This approach allows you to build a secure private network and remotely access Azure resources without relying on expensive managed VPN services.

> **Note:** Azure Active Directory is now known as **Microsoft Entra ID**. This guide focuses on network-level access and does not require identity-based integration.

By the end of this guide, you will have a **secure VPN gateway deployed in Azure**, enabling remote access to private resources using a WireGuard client.

## Scenario

In this scenario:

* A **Windows Server 2019 Datacenter** instance is deployed in Azure
* The server is **not exposed to the public internet**
* It is accessible only via its **private IP address** (e.g., `10.0.0.4`) within the Virtual Network

#### **Objective**

Establish secure access to the Windows Server using **Remote Desktop Protocol (RDP)** over a **WireGuard VPN tunnel**, routed through an Azure-based gateway device.

![Virtual network subnet](/files/ba26d5199c3f8165e4694c2ef863c3117920b456)

### **Architecture Overview**

* A gateway device (running Netmaker and WireGuard) is deployed on an Azure Virtual Machine
* The gateway resides within the same Virtual Network as the target resources
* A client device connects securely to the gateway using WireGuard
* Traffic is routed through the tunnel, enabling private access to Azure resources

### **Implementation Steps**

#### **Deploy the Gateway Device (Egress Node)**

Deploy a Virtual Machine in Azure that will act as the VPN gateway (egress node).

#### **Recommended Configuration**

* **Deployment Type:** Virtual Machine (recommended for simplicity and stability)
* **Operating System:** Ubuntu 24.04 LTS or newer
* **Instance Size:** Small (e.g., B1s or equivalent)
* **Networking Configuration:**
  * Must be part of the **same Virtual Network and subnet** as the target resources
  * Must have a **Public IP address** assigned
  * Must allow inbound traffic for:
    * **SSH (TCP 22)** — for administrative access
    * **WireGuard (UDP 51821)** — default Netmaker port\
      *(Optional: allow a range such as 51821–51830/UDP if needed for multiple peers)*

***

### **Gateway Requirements Checklist**

Ensure that the gateway VM meets the following requirements:

* Connectivity to internal Azure resources (same VNet/subnet)
* Public IP address assigned
* SSH access enabled (port 22)
* WireGuard UDP port exposed (default: 51821)
* Linux-based operating system (Ubuntu recommended)

{% stepper %}
{% step %}

### Add the Egress Device to Netmaker

1. Sign up at <https://app.netmaker.io> (or self-host Netmaker).
2. Use the default network and access key (the account will typically have a network named “netmaker” and an access key named “netmaker”). In the author’s screenshots the network/key are named “azure-gw” — either is fine.
3. In the Netmaker admin UI: click on Add device.
4. Follow the on-screen instructions: SSH to the VM, download and install the netclient, and join the network.\ <br>

   <figure><img src="/files/ReUhE4cQv54TqeTvbSCx" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### **Create an Egress Route**

In the **Netmaker Admin UI**:

1. Go to your **Network**
2. Open the **Egress / Routes section**
3. Click **“Add Route”**<br>

   <figure><img src="/files/sUpxbpONVovhla1dRmv6" alt=""><figcaption></figcaption></figure>
4. In the **Create New Egress Route** window:<br>

   * Enter a **Name**
   * (Optional) Add a **Description**
   * Configure **NAT (Direct)**
   * Set the **Egress Target** (e.g., your Azure subnet `10.0.0.0/24`)

   <figure><img src="/files/NTbnqEgek5IiHNPXXcDo" alt=""><figcaption></figcaption></figure>
5. Click **Next**
6. Select the **node (gateway device)** that will act as the Egress<br>

   <figure><img src="/files/b5czxS3Fn9ds3DqpRPrj" alt=""><figcaption></figcaption></figure>
7. (Optional) Configure **access policies**<br>

   <figure><img src="/files/McNvhMNwDz6q9Yc5TXV3" alt=""><figcaption></figcaption></figure>
8. Click **Finish**

After creation, the device is prepared to serve traffic to the target destination.
{% endstep %}

{% step %}

### Configure Gateway

1. The Gateway allows generating WireGuard config files that route through the gateway device into the network.
2. Download the generated WireGuard config file and run it using any standard WireGuard client on your local machine.

{% content-ref url="/pages/p29XsHMCd06A3OOepszC" %}
[How to Create and Configure Gateways](/getting-started/walkthrough/how-to-create-and-configure-gateways)
{% endcontent-ref %}

If everything is configured correctly you should be able to RDP to the Windows Server using its private IP (10.0.0.4 in the example) over the WireGuard tunnel.

![RDP over private IP screenshot](/files/3423f7bf18aeac9a8fd329a89281539e9124d3d7)

You can generate additional clients to provide access for multiple users.
{% endstep %}
{% endstepper %}

## Summary

{% stepper %}
{% step %}
Configured Azure for a remote access gateway.
{% endstep %}

{% step %}
Configured an Azure VM instance to act as the remote access gateway.
{% endstep %}

{% step %}
Generated and ran a WireGuard config file locally to access a private Windows server via the gateway.
{% endstep %}
{% endstepper %}


# Create AWS Remote Access VPN with WireGuard - deprecated

![A laptop accessing an AWS VPC via WireGuard](/files/354fac8ae1589ca6422dc585d3604d9868d8478f)

## Intro

An AWS account typically consists of multiple VPCs and private subnets. You may wish to provide remote access to private subnets or endpoints on AWS without exposing them publicly.

AWS has their own remote access VPN solution called “AWS Client VPN”. However, this can be unnecessarily expensive. With several users and endpoints, you can easily spend hundreds of dollars per month.

You can build a solution using WireGuard® and Netmaker for free. Follow these steps, and you should be up and running in about 30 minutes.

By the end of this tutorial, you will have a gateway device running on AWS, on which you can easily attach WireGuard clients to access private AWS resources.

## Scenario

![Private Rocket Chat instance on AWS](/files/5235849e163d618248b1be63e3c150bd32565abf)

In this example, Rocket Chat runs on AWS and is only accessible over the VPC address (172.31.95.26). We want a developer to be able to log into Rocket Chat using this private address.

For your setup, this can be any private IPs or subnets on AWS, as long as the addresses are accessible from the gateway device (EC2 instance).

## Step 1: Deploy the Gateway Device

Select a device in AWS to act as your VPN gateway. This can be a container or EC2 instance, but must be Linux-based. You can use an existing instance, but if deploying a new instance, Ubuntu 22.04 is recommended. You can use t2.micro, as it is not resource intensive.

This device must have access to the target devices or subnets, so make sure it is deployed in the correct availability zone, and that the target devices’ security settings allow traffic from the gateway device.

Lastly, the device must be accessible publicly over the WireGuard port, which by default for Netmaker is 51821, so open 51821/udp to 0.0.0.0/0 in the Security settings, and make sure it has a publicly reachable IP (e.g. Elastic IP address).

Gateway Requirements:

* Device Type: EC2 Instance or Container (EC2 Instance recommended)
* OS: Linux (Ubuntu 22.04 recommended)
* Size: any (t2.micro recommended)
* Network Settings: Must have a public endpoint, and expose 51821/udp publicly

![Gateway EC2 Instance on AWS](/files/3e37ab69c4ef99598e8f1adaa283ba988f63feb1)

## Step 2: Add Gateway Device to Netmaker

{% content-ref url="/pages/8023dcd81897c9bc7f43477add0ae990e6caf0ac" %}
[Gateways](/features/gateways)
{% endcontent-ref %}

## Step 3: Configure Egress

Click on “Add route”. Set the gateway device as an egress to the target IP address in AWS. In the example this is 172.31.95.26/32; modify as appropriate and provide multiple ranges if necessary.

<figure><img src="/files/ozmnOHvQfiEuTvpu5pid" alt=""><figcaption></figcaption></figure>

Configure your Egress Gateway:

<figure><img src="/files/mwh2zrg2cB9GOO3CXYkf" alt=""><figcaption></figcaption></figure>

The device is now prepared to serve traffic to the target destination.

## Step 4: Configure  Gateway

{% content-ref url="/pages/p29XsHMCd06A3OOepszC" %}
[How to Create and Configure Gateways](/getting-started/walkthrough/how-to-create-and-configure-gateways)
{% endcontent-ref %}

![Download the WireGuard config file](/files/b1800e3ef5edbcdb058c536cce78bb7749898284) ![Run the WireGuard config file](/files/b1c3a49b362678750212e33edd40c8cdd40315a4)

If everything has gone correctly, the private address should now be accessible from the local device:

![Accessing the private Rocket Chat instance in the browser](/files/18d913afabc6fca9df5475a3ca4dec984f5c22b7)

You can generate additional clients as necessary, so your gateway provides access for a whole team.

## Summary

{% stepper %}
{% step %}

### Configure AWS for a netmaker gateway.

{% endstep %}

{% step %}

### Configure an EC2 instance to act as the remote access gateway.

{% endstep %}

{% step %}

### Generate and run a WireGuard config file locally to access AWS via the gateway.

{% endstep %}
{% endstepper %}


# How to deploy a single Kubernetes cluster across multiple clouds using k3s and WireGuard - deprecate

Kubernetes is hard enough, and now your boss tells you to migrate your application from AWS to Azure, split your back end and front end between public and private data centers, and deploy to six different environments simultaneously.

Before you decide to quit your brand new DevOps job, let's see if we can set this up an easier way.

You look around and find a whole slew of tools out there for managing multiple Kubernetes clusters across environments, and many may even help you deploy your app. However, this all raises an important question: Why run multiple Kubernetes clusters at all?

Kubernetes is a control plane plus managed worker nodes. Why can’t you just deploy these worker nodes to different environments and be done with it?

There are two answers you’ll typically hear:

* You can't do that because of latency.
* You can't do that because of security.

I’m here to tell you that you can do it, and that it’s easier than you might have thought.

The Solution

* You can't do that because of latency. Use k3s: the latency problem with Kubernetes is often due to etcd, which is sensitive to lower performance environments. k3s lets you use SQL which doesn’t have that issue. An alternative approach might be to co-locate your masters while having distributed workers.
* You can't do that because of security. Run this over WireGuard to create encrypted tunnels between all your nodes to keep traffic secure while minimizing latency. For dynamic networks, use a WireGuard management tool; this guide uses Netmaker (<https://github.com/gravitl/netmaker>). Alternatives mentioned: Kilo, Wormhole, Ansible scripts, or other WireGuard config managers (links in the original).

If you prefer a visual walkthrough, there is a YouTube tutorial: <https://youtu.be/z2jvlFVU3dw>

Setup (overview and notes)

* This guide is a short demonstration only. It does not cover DNS, storage, or High Availability. Do not treat this as production-ready without adding those layers.
* Get a few cloud VMs with public IPs. Example used by the author: one Linode, two AWS EC2s, and a home network machine. Three will act as the cluster, and one runs Netmaker.
* Install Ubuntu 20.04 on each machine (systemd-based Linux recommended).
* On each cluster node, install wireguard-tools (e.g. apt install wireguard-tools).
* On the Netmaker VM, install Docker and docker-compose:
  * Docker: <https://docs.docker.com/engine/install/ubuntu/>
  * docker-compose: <https://docs.docker.com/compose/install/>
* Ensure ports 80, 8081, and 50051 are open on the Netmaker VM.

Part 1: Netmaker Install / WireGuard Setup

We’ll create a flat, secure network for cluster nodes: a virtual subnet 10.11.11.0/24 and add nodes to it.

On the Netmaker VM

{% stepper %}
{% step %}

### Prepare Netmaker (on Netmaker VM)

SSH to the Netmaker VM:

```bash
ssh root@netmaker-vm
```

Download the docker-compose file:

```bash
wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/master/docker-compose.nodns.yml
```

Replace the backend address placeholder in docker-compose.yml:

```bash
sed -i 's/your-backend/< Your VM IP Address Here >/g' docker-compose.yml
```

Start Netmaker:

```bash
sudo docker-compose up -d
```

Now head to the IP of that VM to access the Netmaker UI, create a user and log in.
{% endstep %}

{% step %}

### Create network and access key

* In the Netmaker UI, click "Create Network". Name it `k3s` with address range `10.11.11.0/24`.
* Click "Access Keys", select your network (k3s), create a key (e.g. `k3s-key`) and give it uses (e.g. 1000).
* Copy the install script and the access KEY (look for the curl -sfL … | KEY=… sh - command). You'll use this on each cluster VM.
  {% endstep %}
  {% endstepper %}

Deploy Netclient on cluster VMs

Note: Make sure `wireguard-tools` is installed on each cluster VM before running the netclient install.

{% stepper %}
{% step %}

### Verify WireGuard tooling

On each cluster VM:

```bash
which wg-quick
```

Switch to root:

```bash
sudo su -
```

{% endstep %}

{% step %}

### Install netclient

Run the Netmaker install script on each cluster VM, replacing `<YOUR ACCESS KEY FROM NETMAKER>` with your access key:

```bash
curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/v0.3/scripts/netclient-install.sh | KEY=<YOUR ACCESS KEY FROM NETMAKER> sh -
```

{% endstep %}

{% step %}

### Verify WireGuard interface

On each node, check WireGuard:

```bash
wg show
```

If `wg show` shows the interface on each node, Netmaker/Netclient is running correctly. Check the Netmaker UI — you should see all nodes online (green).
{% endstep %}
{% endstepper %}

Part 2: K3s Installation

Master (server) node

* SSH to the node that will be your master and become root:

```bash
sudo su -
```

* Find the WireGuard-private address (look for an address under the nm-k3s interface):

```bash
ip a
```

If Netmaker was installed on the master first, this will likely be `10.11.11.1`. Use that address in the K3s install command; otherwise replace it with the address observed.

Install k3s on the master:

```bash
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --node-ip 10.11.11.1 --node-external-ip 10.11.11.1 --flannel-iface nm-k3s" sh -
```

Wait \~5 minutes for k3s to start, then check status:

```bash
systemctl status k3s
kubectl get nodes
kubectl get pods --all-namespaces
```

Get the node token needed by workers:

```bash
cat /var/lib/rancher/k3s/server/node-token
```

Worker nodes

On each worker node:

```bash
sudo su -
ip a
```

From `ip a` get the node's WireGuard-private IP (e.g. `10.11.11.X`). Then on the worker run (replace `< TOKEN VAL >` with the server node-token, `10.11.11.X` with the worker's WireGuard IP, and `10.11.11.MASTER` with the master WireGuard IP):

```bash
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="agent --server https://10.11.11.MASTER:6443 --token < TOKEN VAL > --node-ip 10.11.11.X --node-external-ip 10.11.11.X --flannel-iface nm-k3s" sh -
```

Check the agent status:

```bash
systemctl status k3s-agent
```

Back on the master, verify nodes and pods:

```bash
sudo kubectl get nodes
sudo kubectl get pods --all-namespaces -o wide
```

If nodes and pods are present and ready, the cluster spanning multiple locations is created.

Part 4: Testing

Deploy simple pingtest pods to verify pod-to-pod connectivity across clouds.

* Create pingtest resources (YAML provided by the author): <https://pastebin.com/BSqLnP57>

```bash
kubectl create namespace pingtest
kubectl apply -f pingtest.yaml
kubectl get pods -n pingtest -o wide
```

You should see pods scheduled across different nodes. Exec into a pingtest pod and ping other pod IPs to verify connectivity.

Next, test the service network across clouds by deploying nginx with a ClusterIP/load-balancer service.

* nginx YAML provided by the author: <https://pastebin.com/ttadjjDA>

```bash
kubectl create namespace nginx
kubectl apply -f nginx.yaml -n nginx
```

From a pingtest pod that’s on a different host than the nginx pods:

```bash
kubectl exec -ti <pingtest-pod-name> -n pingtest -- sh
wget nginx.nginx.svc.cluster.local
```

If you successfully retrieve the document, the cluster service network is working across clouds.

Conclusion

You created a single Kubernetes cluster that spans multiple clouds using k3s and WireGuard. To add more nodes later: run the Netmaker install script and the k3s install script on the new node.

Next steps (not covered here): set up High Availability with multiple masters, add Ingress, configure distributed storage, or deploy Netmaker inside the cluster so it becomes part of it instead of running on an extra VM.




---

[Next Page](/llms-full.txt/1)