Netmaker Release 0.3.5
Alex Feiszli
Jun 03, 2021
CONTENTS
1 About 3 1.1 About...... 3
2 Architecture 5 2.1 Architecture...... 5
3 Quick Start 11 3.1 Quick Start...... 11
4 Server Installation 17 4.1 Server Installation...... 17
5 Client Installation 29 5.1 Client Installation...... 29
6 External Clients 33 6.1 External Clients...... 33
7 Guides 35 7.1 Using Netmaker...... 35
8 API Reference 37 8.1 API Reference...... 37
9 Troubleshooting 41 9.1 Troubleshooting...... 41
10 Support 43 10.1 Support...... 43
11 Contributing 47 11.1 Contribute...... 47
12 Code of Conduct 49 12.1 Code of Conduct...... 49
13 Licensing 51 13.1 License...... 51
i ii Netmaker, Release 0.3.5
Netmaker is a platform for creating and managing fast, secure, and dynamic virtual overlay networks using WireGuard. This documentation covers Netmaker’s installation, usage, troubleshooting, and customization, as well as reference documents for the API, UI and Agent configuration. All of the source code for Netmaker is on GitHub.
CONTENTS 1 Netmaker, Release 0.3.5
2 CONTENTS CHAPTER ONE
ABOUT
A quick overview of Netmaker, explaining what it is, how it works, and why you should be using it.
1.1 About
1.1.1 What is Netmaker?
Netmaker is a tool for creating and managing virtual overlay networks. If you have at least two machines with internet access which you need to connect with a secure tunnel, Netmaker is for you. If you have thousands of servers spread across multiple locations, data centers, or clouds, Netmaker is also for you. Netmaker connects machines securely, wherever they are.
Netmaker takes those machines and creates a flat network so that they can all talk to each other easily and securely. If you’re familiar with AWS, it’s like a VPC but made up of arbitrary computers. From the machine’s perspective, all these other machines are in the same neighborhood, even if they’re spread all over the world. Netmaker has many similarities to Tailscale, ZeroTier, and Nebula. What makes Netmaker different is its speed and flexibility. Netmaker is faster because it uses kernel WireGuard. It is more dynamic because the server andagentsare fully configurable, which lets you handle all sorts of different use cases.
3 Netmaker, Release 0.3.5
1.1.2 How Does Netmaker Work?
Netmaker relies on WireGuard to create tunnels between machines. At its core, Netmaker is managing WireGuard across machines to create sensible networks. Technically, Netmaker is two things: • the admin server, called Netmaker • the agent, called Netclient As the network manager, you interact with the server to create and manage networks and devices. The server holds configurations for these networks and devices, which are retrieved by the netclients (agent). The netclient is installed on any machine you would like to add to a given network, whether that machine is a VM, Server, or IoT device. The netclient reaches out to the server, and the server tells it how it should configure the network. By doing this across many machines simultaneously, we create a dynamic, fully configurable virtual networks. The Netmaker server does not typically route traffic. Otherwise, this would be a hub-and-spoke model, which isvery slow. Instead, Netmaker just tells the machines on the network how they can reach each other directly. This is called a full mesh network and is much faster. Even if the server goes down, as long as none of the existing machines change substantially, your network will still run just fine.
1.1.3 Use Cases for Netmaker
There are many use cases for Netmaker. In fact, you could probably be using it right now. This list is not all- encompassing, but provides a sample of how you might want to use Netmaker. Guided setup for many of these use cases can be found in the Using Netmaker documentation. 0. Automate creation of a WireGuard mesh network 1. Create a flat, secure network between cloud environments and data centers 2. Provide secure access to IoT devices, remote servers, and client sites. 3. Secure a home or office network 4. Add a layer of encryption to an existing network 5. Secure site-to-site connections 6. Manage cryptocurrency proof-of-stake machines 7. Create a dynamic and secure Kubernetes underlay network
4 Chapter 1. About CHAPTER TWO
ARCHITECTURE
A technical overview of Netmaker, including design decisions and limitations.
2.1 Architecture
Pictured Above: A diagram of Netmaker’s Architecture.
2.1.1 Core Concepts
Familiarity with several core concepts will help when you encounter them later on in the documentation.
WireGuard
WireGuard is a relatively new but very important technology which was recently added to the Linux kernel. WireGuard creates very fast but simple encrypted tunnels between devices. From the WireGuard 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 tunnelling solutions will cause a significant increase in your network latency. WireGuard is thefirst to achieve near over-the-line network speeds, meaning you see no signigifant performance impact. With the release of WireGuard, there is little reason to use any other existing tunnel encryption technology.
5 Netmaker, Release 0.3.5
Mesh Network
When we refer to a mesh network in these documents we are typically referring to a “full mesh.”
A full mesh network 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 insome 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 external clients 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 which enables users to create mesh networks between their devices. Netmaker can create both full and partial mesh networks depending on the use case. When we refer to Netmaker in aggregate, we are typically referring to Netmaker and the netclient, as well as other supporting services such as CoreDNS, MongoDB, and UI webserver. From an end user perspective, they typically interact with the Netmaker UI, or even just run the install script for the netclient on their devices. The other components run in the background invisibly. 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 a machine to a network. 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.
6 Chapter 2. Architecture Netmaker, Release 0.3.5
Node
A machine in a Netmaker network, which is managed by the Netclient, is referred to as a Node, as you will see in the UI. A Node can be a VM, a bare metal server, a desktop computer, an IoT device, or any other number of internet-connected machines on which the netclient is installed. A node is simply an endpoint in the network, which can send traffic to all the other nodes, and recieve traffic from all of the other nodes.
SystemD
SystemD is a system service manager for a wide array of Linux operating systems. Not all Linux distributions have adopted systemd, but, for better or worse, it has become a fairly common standard in the Linux world. That said, any non-Linux operating system will not have systemd, and many Linux/Unix distributionshave alternative system service managers. Netmaker’s netclient, the agent which controls networking on all nodes, relies heavily on systemd as of version 0.3. This reliance is being reduced but is currently a core dependency, causing most of the limitations and incompatibilities. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices.
2.1.2 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. 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 as a GRPC server to the machines in the network. GRPC is much faster and more efficient than standard API calls, which increases the speed of transactions. For this reason,the Netmaker server exposes two ports: The default for the API is 8081, and the default for GRPC is 50051. Either the API or the GRPC server can be disabled on any given Netmaker instance can be disabled, allowing you to deploy two different servers for managing the API (which is largely for the admin’s use) and GRPC (which is largely for thenodes’ use). Most server settings are configurable via a config file, or by environment variables (which take precedence). Ifthe server finds neither of these, it sets sensible defaults, including things like the server’s reachable IP, ports, andwhich “modes” to run in. These modes include client mode and dns mode. Either of these can be disabled but are enabled by default. Client mode allows you to treat the Netmaker host machine (operating system) as a network Node, installing the netclient and controlling the host network. DNS mode has the server write config settings for CoreDNS, a separate component and nameserver, which picks up the config settings to manage node DNS. The Netmaker server interacts with (as of v0.3) a MongoDB instance, which holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.
2.1. Architecture 7 Netmaker, Release 0.3.5
Netclient
The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker GitHub Repository. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.3, it requires systemd in order to manage the host system appropriately. It may be installable, and it may even make the machine a part of the mesh network, but it will not function in entirely (see Compatible Systems for more info) without systemd. The netclient is installed via a simple bash script, which pulls the latest binary and runs install command. The install command registers the machine with the Netmaker server 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 manualnode signup), it will be registered in the Netmaker network, which will return configuration details about how to set upthe local network. The netclient then sets itself up in systemd, and configures WireGuard. At this point it should be part of the network. On a periodic basis (systemd timer), the netclient performs a “check in.” It will authenticate with the server, and check to see if anything has changed in the network. It will also post changes about its own local configuration if there. If there has been a change, the server will return new configurations and the netclient will reconfigure the network. The check in process is what 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.
MongoDB
As of v0.3, Netmaker uses MongoDB as its database, and interacts with a MongoDB instance to store and retrieve information about nodes, networks, and users. Netmaker is rapidly evolving, and MongoDB provides a flexible database structure that accelerates development. However, MongoDB is also the heaviest component of Netmaker (high cpu/memory consumption), and is set to be replaced by a lighter-weight, SQL-based database in the future.
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. In a typical configuration, the Netmaker UI is run on Nginx as aDocker 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, andDNS.
CoreDNS v0.3 introduced the concept of private DNS management for nodes. This requires a nameserver, and CoreDNS is the chosen nameserver. CoreDNS is lightweight and extensible. CoreDNS loads dns settings from a simple file, managed by Netmaker, and serves out DNS info for managed nodes. DNS can be tricky, and DNS management is currently only supported on a small set of devices, specifically those running systemd-resolved. However, the Netmaker CoreDNS instance can be added manually as a nameserver to other devices. DNS mode can also be turned off. Worth considering is that CoreDNS requires port 53 on the Netmaker host system, which may cause conflicts depending on your operating system. This is explained in the Server Installation guide.
8 Chapter 2. Architecture Netmaker, Release 0.3.5
2.1.3 Technical Process
Below is a high level, step-by-step overview of the flow of communications within Netmaker (assuming Netmaker has already been installed): 1. Admin creates a new network with a subnet, for instance 10.10.10.0/24 2. Admin creates an access key for signing up new nodes 3. Both of the above requests are routed to the server via an API call from the front end 4. Admin runs the netclient install script on any given node (machine). 5. Netclient decodes key, which contains the GRPC server location and port 6. Netclient retrieves/sets local information, including open ports for WireGuard, public IP, and generating key pairs for peers 7. Netclient reaches out to GRPC server with this information, authenticating via access key. 8. Netmaker server verifies information and creates the node, setting default values for any missing information. 9. Timestamp is set for the network (see #16). 10. Netmaker returns settings as response to netclient. Some settings may be added or modified based on the network. 11. Netclient recieves response. If successful, it takes any additional info returned from Netmaker and configures the local system/WireGuard 12. Netclient sends another request to Netmaker’s GRPC server, this time to retrieve the peers list (all other clients in the network). 13. Netmaker sends back peers list, including current known configurations of all nodes in network. 14. Netclient configures WireGuard with this information. At this point, the node is fully configured as a partofthe network and should be able to reach the other nodes via private address. 15. Netclient begins daemon (system timer) to run check in’s with the server. It awaits changes, reporting local changes, and retrieving changes from any other nodes in the network. 16. Other netclients on the network, upon checking in with the Netmaker server, will see that the timestamp has updated, and they will retrieve a new peers list, completing the update cycle.
2.1.4 Compatible Systems for Netclient
To manage a node automatically, the Netmaker client (netclient) requires systemd-based linux. Compatible systems include:
• Fedora • Ubuntu • Debian • Mint • SUSE • RHEL • Raspian. • Arch • CentOS
2.1. Architecture 9 Netmaker, Release 0.3.5
• CoreOS To manage DNS (optional), the node must have systemd-resolved. Systems that have this enabled include: • Arch • Debian • Ubuntu • SUSE
2.1.5 Limitations
Install limitations mostly include platform-specific limitations, such as needing systemd or systemd-resolved (see above). In addition the Netmaker platform has some additional limitations: • Double NAT: Netmaker is currently unable to route traffic for devices behind a “double NAT”. • CGNAT: Netmaker is currently unable to route traffic for for devices behind a “carrier-grade NAT”. • Windows/iPhone/Android: To reiterate the systemd limitation, Netmaker is not currently configured to support “end user” devices such as Windows desktops and phones generally. In v0.4, Netmaker will introduce external device gateways to allow this traffic (and many other sorts of devices).
10 Chapter 2. Architecture CHAPTER THREE
QUICK START
A quick start guide to getting up and running with Netmaker and WireGuard as quickly as possible.
3.1 Quick Start
3.1.1 Introduction
This is a guide to getting up and running with Netmaker as quickly as possible. By default, Netmaker ships with DNS Mode, Client Mode, and Secure GRPC enabled. However, these features require special permissions and are not necessary for a simple setup, so we are going to deploy without them. To learn more about enabling these features, check out the installation docs.
3.1.2 Prerequisites
1. A Linux server to host Netmaker, with an external IP reachable by your nodes (will be referred to as your-host in document). 2. Docker and Docker Compose installed on the above server. Follow the official Docker instructions for installing Docker and Docker Compose on your system. 3. All network nodes should be systemd-based (see Compatibility under Architecture docs)
3.1.3 Install
1. ssh root@your-host 2. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/ master/scripts/docker-compose.slim.yml 3. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml 4. docker-compose up -d Navigate to the IP address of your host in the browser. You should see the below screen. If not, please see the Quick Start section of the troubleshooting docs.
11 Netmaker, Release 0.3.5
3.1.4 Setup
1. Create your admin user, with a username and password. 2. Login with your new user 3. Examine the default network. Click on DEFAULT under NETWORK DETAILS
This displays information about the default network, which is created on server startup. You can delete this network if you do not need it, but for standard use cases this network should be enough to get started. Nodes will get an address from the network address range (ADDRESSRANGE). If the range conflicts with a pre-existing private network on your devices, you may want to change this, or make a new network instead. Nodes will also get default settings from here for unset configurations. For instance, the DEFAULTKEEPALIVE field will set the PersistenKeepAlive for nodes. To get started quickly, we can just use the existing default network.
12 Chapter 3. Quick Start Netmaker, Release 0.3.5
Create Key
1. Click on the ACCESS KEYS tab and select the DEFAULT network. 2. Click ADD NEW ACCESS KEY 3. Give it a name (ex: “mykey”) and a number of uses (ex: 25) 4. Click CREATE KEY (Important: Do not click out of the following screen until you have saved your key details. It will appear only once.) 5. Copy the bottom command under “Your agent install command with access token” and save it somewhere locally. E.x: curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/v0.3/scripts/ netclient-install.sh | KEY=vm3ow4thatogiwnsla3thsl3894ths sh -
You will use this command to install the netclient on your nodes. There are three different values for three different scenarios: • The Access 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 -c install -k
3.1. Quick Start 13 Netmaker, Release 0.3.5
3.1.5 Deploy Nodes
1. SSH to each machine 2. sudo su - 3. Prerequisite Check: Every Linux machine on which you run the netclient must have WireGuard and systemd installed • which wg (should show wg binary present) • pidof systemd && echo "systemd found" || echo "systemd not found" 4. Run the install command, Ex: curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/ v0.5/scripts/netclient-install.sh | KEY=vm3ow4thatogiwnsla3thsl3894ths sh - You should get output similar to the below. The netclient retrieves local settings, submits them to the server for pro- cessing, and retrieves updated settings. Then it sets the local network configuration. For more information about this process, see the client installation documentation. If this process failed and you do not see your node in the console (see below), then reference the troubleshooting documentation.
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.
14 Chapter 3. Quick Start Netmaker, Release 0.3.5
3.1.6 Manage Nodes
Your machines should now be visible in the control pane.
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 docs.
3.1. Quick Start 15 Netmaker, Release 0.3.5
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 aboue ~30 seconds to take effect.
3.1.7 Uninstalling the netclient
1. To remove your nodes from the default network, run the following on each node: sudo netclient leave -n default 2. To remove the netclient entirely from each node, run sudo rm -rf /etc/netclient (after running the first step)
3.1.8 Uninstralling Netmaker
To uninstall Netmaker from the server, simply run docker-compose down or docker-compose down --volumes to remove the docker volumes for a future installation.
16 Chapter 3. Quick Start CHAPTER FOUR
SERVER INSTALLATION
A detailed guide to installing the Netmaker server (API, DB, UI, DNS), and configuration options.
4.1 Server Installation
This section outlines installing the Netmaker server, including Netmaker, Netmaker UI, MongoDB, and CoreDNS
4.1.1 Notes on Optional Features
There are a few key options to keep in mind when deploying Netmaker. All of the following options are enabled by default but can be disabled with a single flag at runtime (see Customization). In addition to these options, thereare many more Customizable components which will be discussed later on and help to solve for special challenges and use cases. Client Mode: Client Mode enables Netmaker to control the underlying host server’s Network. This can make manage- ment a bit easier, because Netmaker can be added into networks via a button click in the UI. This is especially useful for things like Gateways, and will open up additional options in future versions, for instance, allowing Netmaker to easily become a relay server. Client Mode requires many additional privileges on the host machine, since Netmaker needs to control kernel Wire- Guard. Because of this, if running in Client Mode, you must run with root privileges and mount many system directories to the Netmaker container. Running without Client Mode allows you to install without privilege escalation and increases the number of compatible systems substantially. DNS Mode: DNS Mode enables Netmaker to write configuration files for CoreDNS, which can be set as a DNS Server for nodes. DNS Mode, paired with a CoreDNS deployment, requires use of port 53. On many linux systems (such as Ubuntu), port 53 is already in use to support local DNS, via systemd-resolved. Running in DNS Mode may require making modifications on the host machine. Secure GRPC: Secure GRPC ensures all communications between nodes and the server are encrypted. Netmaker sets up a default “comms” network that exists only for nodes to connect to the server. It acts as a hub-and-spoke WireGuard network. In the below installation instructions, when port 50555 needs to be open, this is referring to the WireGuard port for Netmaker’s GRPC comms. When it is port 50051, secure comms is not enabled. When Secure GRPC is enabled, before any nodes can join a Netmaker network, they request to join the comms network, and are given the appropriate WireGuard configs to connect to the server. Then they are able to make requests againstthe private netmaker endpoint specified for the comms network (10.101.0.1 by default). If switched off, communications are not secure between the hub and nodes over GRPC (it is like http vs https), and likewise, certificates must be added to gain secure communications. Agent Backend: The Agent Backend is the GRPC server (by default running on port 50051). This port is not needed for the admin server. If your use case requires special access configuration, you can run two Netmaker instances, one for the admin server, and one for node access.
17 Netmaker, Release 0.3.5
REST Backend: Similar to the above, the REST backend runs by default on port 8081, and is used for admin API and UI access. By enabling the REST backend while disabling the Agent backend, you can separate the two functions for more restricted environments.
4.1.2 System Compatibility
Both Client Mode and Secure GRPC require WireGuard to be installed on the host system, and will require elevated privileges to perform network operations.. When both of these features are disabled, Netmaker can be run on any system that supports Docker, including Windows, Mac, and Linux, and other systems. With these features disabled, no special privileges are required. Netmaker will only need ports for GRPC (50051 by default), the API (8081 by default), and CoreDNS (53, if enabled). With Client Mode and/or Secure GRPC enabled (the default), Netmaker has the same limitations as the netclient (client networking agent), because client mode just means that the Netmaker server is also running a netclient. These modes require privileged (root) access to the host machine. In addition, Client Mode requires multiple host directory mounts. WireGuard must be installed, the system must be systemd Linux (see compatible systems for more details). To run a non-docker installation, you must run the Netmaker binary, CoreDNS binary, MongoDB, and a web server directly on the host. This requires all the requirements for those individual components. Our guided install assumes systemd-based linux, but there are many other ways to install Netmaker’s individual components onto machines that do not support Docker.
4.1.3 DNS Mode Prereqisite Setup
If you plan on running the server in DNS Mode, know that a CoreDNS Server will be installed. CoreDNS is a light- weight, fast, and easy-to-configure DNS server. It is recommended to bind CoreDNS to port 53 of the host system, and it will do so by default. The clients will expect the nameserver to be on port 53, and many systems have issues resolving a different port. However, on your host system (for Netmaker), this may conflict with an existing process. On linux systems running systemd-resolved, there is likely a service consuming port 53. The below steps will disable systemd-resolved, and replace it with a generic (e.g. Google) nameserver. Be warned that this may have consequences for any existing private DNS configuration. The following was tested on Ubuntu 20.04 and should be run prior to deploying thedocker containers. 1. systemctl stop systemd-resolved 2. systemctl disable systemd-resolved 3. vim /etc/systemd/resolved.conf • uncomment DNS and add 8.8.8.8 or whatever reachable nameserver is your preference • uncomment DNSStubListener and set to “no” 4. ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf Port 53 should now be available for CoreDNS to use.
18 Chapter 4. Server Installation Netmaker, Release 0.3.5
4.1.4 Docker Compose Install
The most simple (and recommended) way of installing Netmaker is to use one of the provided Docker Compose files. Below are instructions for several different options to install Netmaker via Docker Compose, followed by an annotated reference Docker Compose in case your use case requires additional customization.
Slim Install - No DNS, No Client Mode, No Secure GRPC
This is the same docker compose covered in the quick start. It requires no special privileges and can run on any system with Docker and Docker Compose. However, it also does not have the full feature set, and lacks Client Mode and DNS Mode. Prerequisites: • ports 80, 8081, and 50051 are not blocked by firewall • ports 80, 8081, 50051, and 27017 are not in use Notes: • You can still run the netclient on the host system even if Client Mode is not enabled. It will just be managed like the netclient on any other nodes, and will not be automatically managed by thhe server/UI. • You can change the port mappings in the Docker Compose if the listed ports are already in use. Assuming you have Docker and Docker Compose installed, you can just run the following, replacing < Insert your-host IP Address Here > with your host IP (or domain): 1. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/ master/scripts/docker-compose.slim.yml 2. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml 3. docker-compose up -d
Full Install - DNS, Client Mode, and Secure GRPC Enabled
This installation gives you the fully-featured product with Client Mode and DNS Mode. Prerequisites: • systemd linux (Debian or Ubuntu reccommended) • sudo privileges • DNS Mode Prerequisite Setup (see above) • WireGuard installed • ports 80, 8081, 53, and 50555 are not blocked by firewall • ports 80, 8081, 53, 50555, and 27017 are not in use Notes: • You can change the port mappings in the Docker Compose if the listed ports are already in use. • You can run CoreDNS on a non-53 port, but this likely will cause issues on the client side (DNS on non- standard port). We do not recommend this and do not cover how to manage running CoreDNS on a different port for clients, which will likely have problems resolving a nameserver on a non-53 port. Assuming you have Docker and Docker Compose installed, you can just run the following, replacing < Insert your-host IP Address Here > with your host IP (or domain):
4.1. Server Installation 19 Netmaker, Release 0.3.5
1. sudo su - 2. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/ master/scripts/docker-compose.yml 3. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml 4. docker-compose up -d
Server Only Install - UI, DNS, Client Disabled
A “Server Only” install can be helpful for scenarios in which you do not want to run the UI. the UI is not mandatory for running a Netmaker network, but it makes the process easier. This mode also diables DNS and Client Modes, though you can add those back in if needed. There is no UI dependency on Client Mode or DNS Mode. Prerequisites: • ports 8081 and 50051 are not blocked by firewall • ports 8081, 50051, and 27017 are not in use Notes: • You can still run the netclient on the host system even if Client Mode is not enabled. It will just be managed like the netclient on any other nodes, and will not be automatically managed by thhe server/UI. • You can change the port mappings in the Docker Compose if the listed ports are already in use. Assuming you have Docker and Docker Compose installed, you can just run the following, replacing < Insert your-host IP Address Here > with your host IP (or domain): 1. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/ master/scripts/docker-compose.server-only.yml 2. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml
No DNS - CoreDNS Disabled, Client Enabled
DNS Mode is currently limited to clients that can run resolvectl (systemd-resolved, see Architecture docs for more info). You may wish to disable DNS mode for various reasons. This installation option gives you the full feature set minus CoreDNS. Prerequisites: • systemd linux (Debian or Ubuntu reccommended) • sudo privileges • WireGuard installed • ports 80, 8081, and 50555 are not blocked by firewall • ports 80, 8081, 50555, and 27017 are not in use Notes: • You can change the port mappings in the Docker Compose if the listed ports are already in use. • If you would like to run DNS Mode, but disable it on some clients, this is also an option. See the client installation documentation for more details. Assuming you have Docker and Docker Compose installed, you can just run the following, replacing < Insert your-host IP Address Here > with your host IP (or domain):
20 Chapter 4. Server Installation Netmaker, Release 0.3.5
1. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/ master/scripts/docker-compose.nodns.yml 2. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml No DNS - CoreDNS Disabled, Client Enabled
No Client - DNS Enabled, Client Disabled
You may want to provide DNS, but do not want to run the server with special privileges, in which case you can run with just Client Mode disabled. It requires no special privileges and can run on any system with Docker and Docker Compose. Prerequisites: • ports 80, 8081, 53, and 50051 are not blocked by firewall • ports 80, 8081, 53, 50051, and 27017 are not in use • DNS Mode Prerequisite Setup (see above) Notes: • You can still run the netclient on the host system even if Client Mode is not enabled. It will just be managed like the netclient on any other nodes, and will not be automatically managed by thhe server/UI. • You can change the port mappings in the Docker Compose if the listed ports are already in use. Assuming you have Docker and Docker Compose installed, you can just run the following, replacing < Insert your-host IP Address Here > with your host IP (or domain): 1. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/ master/scripts/docker-compose.noclient.yml 2. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml 3. docker-compose up -d
Reference Compose File - Annotated
All environment variables and options are enabled in this file. It is the equivalent to running the “full install” fromthe 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. version:"3.4" services: mongodb: # The MongoDB Instance that backs up Netmaker image: mongo:4.2 ports: -"27017:27017" # Port Mapping for MongoDB. Can be modified, but be sure to change␣
˓→the MONGO_PORT env var in netmaker container_name: mongodb volumes: - mongovol:/data/db restart: always environment: (continues on next page)
4.1. Server Installation 21 Netmaker, Release 0.3.5
(continued from previous page) MONGO_INITDB_ROOT_USERNAME: mongoadmin # Default username. Recommend changing for␣
˓→production installs. You will need to set MONGO_ADMIN netmaker env var. MONGO_INITDB_ROOT_PASSWORD: mongopass # Default password. Recommend changing for␣
˓→production installs. You will need to set MONGO_PASS netmaker env var. netmaker: # The Primary Server for running Netmaker privileged: true # Necessary to run sudo/root level commands on host system. Take␣
˓→out if not running with CLIENT_MODE=on container_name: netmaker depends_on: - mongodb image: gravitl/netmaker:v0.3 volumes: # Volume mounts necessary for CLIENT_MODE to control netclient, wireguard,␣
˓→and networking on host (except dnsconfig, which is where dns config files are stored␣
˓→for use by CoreDNS) - ./:/local - /etc/netclient:/etc/netclient - dnsconfig:/root/config/dnsconfig # Netmaker writes Corefile to this location,␣
˓→which gets mounted by CoreDNS for DNS configuration. - /usr/bin/wg:/usr/bin/wg - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket - /run/systemd/system:/run/systemd/system - /etc/systemd/system:/etc/systemd/system - /sys/fs/cgroup:/sys/fs/cgroup cap_add: # Necessary for CLIENT_MODE. Should be removed if turned off. - NET_ADMIN - SYS_MODULE restart: always network_mode: host # Necessary for CLIENT_MODE. Should be removed if turned off, but␣
˓→then need to add port mappings environment: SERVER_HOST:"" # All the Docker Compose files pre-populate this with HOST_IP,␣
˓→which you replace as part of the install instructions. This will set both HTTP and␣
˓→GRPC host. SERVER_HTTP_HOST:"127.0.0.1" # Overrides SERVER_HOST if set. Useful for making␣
˓→HTTP and GRPC available via different interfaces/networks. SERVER_GRPC_HOST:"127.0.0.1" # Overrides SERVER_HOST if set. Useful for making␣
˓→HTTP and GRPC available via different interfaces/networks. API_PORT: 8081 # 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. GRPC_PORT: 50051 # The GRPC port for Netmaker. Used for communications from nodes. MASTER_KEY:"secretkey" # The admin master key for accessing the API. Change this␣
˓→in any production installation. CORS_ALLOWED_ORIGIN:"*" # The "allowed origin" for API requests. Change to␣
˓→restrict where API requests can come from. REST_BACKEND:"on" # Enables the REST backend (API running on API_PORT at SERVER_
˓→HTTP_HOST). Change to "off" to turn off. AGENT_BACKEND:"on" # Enables the AGENT backend (GRPC running on GRPC_PORT at␣
˓→SERVER_GRPC_HOST). Change to "off" to turn off. CLIENT_MODE:"on" # Enables Client Mode, meaning netclient will be deployed on␣
˓→server and will be manageable from UI. Change to "off" to turn off. DNS_MODE:"on" # Enables DNS Mode, meaning config files will be generated for␣ ˓→CoreDNS. Note, turning "off" does not remove CoreDNS. You still need to remove(continues CoreDNS on next page)␣ ˓→from compose file.
22 Chapter 4. Server Installation Netmaker, Release 0.3.5
(continued from previous page) DISABLE_REMOTE_IP_CHECK:"off" # 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. MONGO_ADMIN:"mongoadmin" # Admin user for MongoDB. Change to match above MongoDB␣
˓→instance MONGO_PASS:"mongopass" # Admin password for MongoDB. Change to match above␣
˓→MongoDB instance MONGO_HOST:"127.0.0.1" # Address of MongoDB. Change if necessary. MONGO_PORT:"27017" # Port of MongoDB. Change if necessary. MONGO_OPTS:"/?authSource=admin" # Opts to enable admin login for Mongo. SERVER_GRPC_WIREGUARD:"on" # Whether to run GRPC over a WireGuard network. On by␣
˓→default. Secures server comms. Switch to "off" to turn off. SERVER_GRPC_WG_INTERFACE:"nm-grpc-wg" # Interface to use for GRPC WireGuard␣
˓→network if enabled SERVER_GRPC_WG_ADDRESS:"10.101.0.1" # Private Address to use for GRPC WireGuard␣
˓→network if enabled SERVER_GRPC_WG_ADDRESS_RANGE:"10.101.0.0/16" # Private Address range to use for␣
˓→GRPC WireGard clients if enabled SERVER_GRPC_WG_PORT:"50555" # Port to use for GRPC WireGuard if enabled SERVER_GRPC_WG_PUBKEY:"SERVER_GRPC_WG_PUBKEY" # PublicKey for GRPC WireGuard␣
˓→interface. Generated if blank. SERVER_GRPC_WG_PRIVKEY:"SERVER_GRPC_WG_PRIVKEY" # PrivateKey for GRPC WireGuard␣
˓→interface. Generated if blank. netmaker-ui: # The Netmaker UI Component container_name: netmaker-ui depends_on: - netmaker image: gravitl/netmaker-ui:v0.3 links: -"netmaker:api" ports: -"80:80" environment: BACKEND_URL:"http://HOST_IP:8081" # URL where UI will send API requests. Change␣
˓→based on SERVER_HOST, SERVER_HTTP_HOST, and API_PORT MASTER_KEY:"secretkey" # Master Key for API calls. Will be removed in v0.3.5 coredns: # The DNS Server. Remove this section if DNS_MODE="off" depends_on: - netmaker image: coredns/coredns command: -conf /root/dnsconfig/Corefile # Config location for Corefile. This is the␣
˓→path of file which is also mounted to Netmaker for modification. container_name: coredns restart: always ports: -"53:53/udp" # Likely needs to run at port 53 for adequate nameserver usage. volumes: - dnsconfig:/root/dnsconfig volumes: mongovol: {} dnsconfig: {}
4.1. Server Installation 23 Netmaker, Release 0.3.5
4.1.5 Linux Install without Docker
Most systems support Docker, but some, such as LXC, do not. In such environments, there are many options for installing Netmaker. Netmaker is available as a binary file, and there is a zip file of the Netmaker UI static HTMLon GitHub. Beyond the UI and Server, you need to install MongoDB and CoreDNS (optional). Below is a guided set of instructions for installing without Docker on Ubuntu 20.04. Depending on your system, the steps may vary.
MongoDB Setup
1. Install MongoDB on your server: • For Ubuntu: sudo apt install -y mongodb • For more advanced installation or other operating systems, see the MongoDB documentation. 2. Create a user: • mongo admin • > db.createUser({ user: “mongoadmin” , pwd: “mongopass”, roles: [“userAdminAnyDatabase”, “dbAdminAnyDatabase”, “readWriteAnyDatabase”]})
Server Setup
1. Run the install script: sudo curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/ v0.3.5/scripts/netmaker-server.sh | sh - 2. Check status: sudo journalctl -u netmaker 3. If any settings are incorrect such as host or mongo credentials, change them under /etc/netmaker/config/environments/< your env >.yaml and then run sudo systemctl restart netmaker
UI Setup
The following uses NGinx as an http server. You may alternatively use Apache or any other web server that serves static web files. 1. Download UI asset files: sudo wget -O /usr/share/nginx/html/netmaker-ui.zip https:// github.com/gravitl/netmaker-ui/releases/download/latest/netmaker-ui.zip 2. Unzip: sudo unzip /usr/share/nginx/html/netmaker-ui.zip -d /usr/share/nginx/html 3. Copy Config to Nginx: sudo cp /usr/share/nginx/html/nginx.conf /etc/nginx/conf.d/ default.conf 4. Modify Default Config Path: sudo sed -i 's/root \/var\/www\/html/root \/usr\/share\/ nginx\/html/g' /etc/nginx/sites-available/default 5. Change Backend URL: sudo sh -c 'BACKEND_URL=http://
24 Chapter 4. Server Installation Netmaker, Release 0.3.5
CoreDNS Setup
4.1.6 Kubernetes Install
This configuration is coming soon. It will allow you to deploy Netmaker on a Kubernetes cluster.
4.1.7 Configuration Reference
The “Reference Compose File” (above) explains many of these options. However, it is important to understand funda- mentally how Netmaker sets its configuration: 1. Defaults 2. Config File 3. Environment Variables
Variable Description
SERVER_HOST: Default: Server will perform an IP check and set automatically unless explicitly set, or DIS- ABLE_REMOTE_IP_CHECK is set to true, in which case it defaults to 127.0.0.1 Description: Sets the SERVER_HTTP_HOST and SERVER_GRPC_HOST variables if they are unset. The address where traffic comes in. SERVER_HTTP_HOST: Default: Equals SERVER_HOST if set, “127.0.0.1” if SERVER_HOST is unset. Description: Set to make the HTTP and GRPC functions available via different interfaces/networks. SERVER_GRPC_HOST: Default: Equals SERVER_HOST if set, “127.0.0.1” if SERVER_HOST is unset. Description: Set to make the HTTP and GRPC functions available via different interfaces/networks. API_PORT: Default: 8081 Description: The HTTP API port for Netmaker. Used for API calls / communication from front end. GRPC_PORT: Default: 50051 Description: The GRPC port for Netmaker. Used for communications from nodes. MASTER_KEY: Default: “secretkey” Description: The admin master key for accessing the API. Change this in any production installation. CORS_ALLOWED_ORIGIN: Default: “*” Description: The “allowed origin” for API requests. Change to restrict where API requests can come from. REST_BACKEND: Default: “on” Description: Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST). Change to “off” to turn off. AGENT_BACKEND: Default: “on” Description: Enables the AGENT backend (GRPC running on GRPC_PORT at SERVER_GRPC_HOST). Change to “off” to turn off. CLIENT_MODE: Default: “on” Description: Enables Client Mode, meaning netclient will be deployed on server and will be manageable from UI. Change to “off” to turn off.
4.1. Server Installation 25 Netmaker, Release 0.3.5
DNS_MODE: Default: “on” Description: Enables DNS Mode, meaning config files will be generated for CoreDNS. 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. Turned “off” by default. MONGO_ADMIN: Default: “mongoadmin” Description: Admin user for MongoDB. MONGO_PASS: Default: “mongopass” Description: Admin password for MongoDB. MONGO_HOST: Default: “127.0.0.1” Description: Address of MongoDB. MONGO_PORT: Default: “27017” Description: Port of MongoDB. MONGO_OPTS: Default: “/?authSource=admin” Description: Opts to enable admin login for Mongo. SERVER_GRPC_WIREGUARD: Default: “on” Description: Whether to run GRPC over a WireGuard network. On by default. Secures the server comms. Switch to “off” to turn off. If off and running in production, make sure to have certificates installed tosecure GRPC communications. SERVER_GRPC_WG_INTERFACE: Default: “nm-grpc-wg” Description: Interface to use for GRPC WireGuard network if enabled SERVER_GRPC_WG_ADDRESS: Default: “10.101.0.1” Description: Private Address to use for GRPC WireGuard network if enabled SERVER_GRPC_WG_ADDRESS_RANGE: Default: “10.101.0.0/16” Description: Private Address range to use for GRPC WireGard clients if enabled. Gives 65,534 total addresses for all of netmaker. If running a larger network, will need to configure addresses differently, for instance using ipv6, or use certificates instead. SERVER_GRPC_WG_PORT: Default: 50555 Description: Port to use for GRPC WireGuard if enabled SERVER_GRPC_WG_PUBKEY: Default: < generated at startup > Description: PublicKey for GRPC WireGuard interface. Generated if left blank. SERVER_GRPC_WG_PRIVKEY: Default: < generated at startup > Description: PrivateKey for GRPC WireGuard interface. Generated if left blank. SERVER_GRPC_WG_KEYREQUIRED Default: “” Description: Determines if an Access Key is required to join the Comms network. Blank (meaning ‘no’) by default. Set to “yes” to turn on.
26 Chapter 4. Server Installation Netmaker, Release 0.3.5
Config File Reference
A config file may be placed under config/environments/
˓→is not set to true. SERVER_API_HOST if set apiport:"" # defaults to 8081 or HTTP_PORT (if set) grpchost:"" # defaults to 127.0.0.1 or remote ip (SERVER_HOST) if␣
˓→DisableRemoteIPCheck is not set to true. SERVER_GRPC_HOST if set. grpcport:"" # defaults to 50051 or GRPC_PORT (if set) masterkey:"" # defaults to 'secretkey' or MASTER_KEY (if set) allowedorigin:"" # defaults to '*' or CORS_ALLOWED_ORIGIN (if set) restbackend:"" # defaults to "on" or REST_BACKEND (if set) agentbackend:"" # defaults to "on" or AGENT_BACKEND (if set) clientmode:"" # defaults to "on" or CLIENT_MODE (if set) dnsmode:"" # defaults to "on" or DNS_MODE (if set) disableremoteipcheck:"" # defaults to "false" or DISABLE_REMOTE_IP_CHECK (if set) mongoconn: user:"" # defaults to "mongoadmin" or MONGO_ADMIN (if set) pass:"" # defaults to "mongopass" or MONGO_PASS (if set) host:"" # defaults to 127.0.0.1 or MONGO_HOST (if set) port:"" # defaults to 27017 or MONGO_PORT (if set) opts: '' # defaults to '/?authSource=admin' or MONGO_OPTS (if set) wg: keyrequired:"" # defaults to "". If set to "yes", a key is required for signing up␣
˓→for the comms network grpcwg:"" # defaults to "on" or SERVER_GRPC_WIREGUARD if set grpciface:"" # defaults to nm-grpc-wg or SERVER_GRPC_WG_INTERFACE if set grpcaddr:"" # defaults to 10.101.0.1 or SERVER_GRPC_WG_ADDRESS if set grpcaddrrange:"" # defaults to 10.101.0.0/16 or SERVER_GRPC_WG_ADDRESS_RANGE if set grpcendpoint:"" # defaults to SERVER_HOST if unset grpcport:"" # defaults to 50555 or SERVER_GRPC_WG_PORT if set pubkey:"" # defaults to generated value or SERVER_GRPC_WG_PUBKEY if set privkey:"" # defaults to generated value or SERVER_GRPC_WG_PRIVKEY if set
4.1. Server Installation 27 Netmaker, Release 0.3.5
28 Chapter 4. Server Installation CHAPTER FIVE
CLIENT INSTALLATION
A detailed guide to installing the Netmaker agent (netclient) on devices and configuration options.
5.1 Client 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 Net- maker.
5.1.1 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 machine. Any changes to the settings of any one of these machines can break those connections. Any machine that is added, removed, or modified on the network requires reconfiguring every peer in the network. This can be very time consuming. 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.
5.1.2 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 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.”
29 Netmaker, Release 0.3.5
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 devices. 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. This requires a systemd-based linux operating system. If running the netclient on a non-systemd system, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.
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
5.1.3 Prerequisites
For netclient cli: Linux/Unix with WireGuard installed (wg command available) For netclient daemon: Systemd Linux + WireGuard For Private DNS management: Resolvectl (systemd-resolved)
5.1.4 Configuration
Variable Reference
Config File Reference
CLI Reference
5.1.5 Installation
Token
Access Key
Manual
30 Chapter 5. Client Installation Netmaker, Release 0.3.5
Config File
5.1.6 Managing Netclient
Viewing Logs
Making Updates
Adding/Removing Networks
Uninstalling
Troubleshooting
5.1. Client Installation 31 Netmaker, Release 0.3.5
32 Chapter 5. Client Installation CHAPTER SIX
EXTERNAL CLIENTS
A detailed guide to give clients outside of the Netmaker network access to network resources.
6.1 External Clients
6.1.1 Introduction
Netmaker allows for “external clients” to reach into a network and access services via an Ingress Gateway. So what is an “external client”? An external client is any machine which cannot or should not be meshed. This can include:
• Phones • Laptops • Desktops An external client is not “managed,” meaning it does not automatically pull the latest network configuration, or push changes to its configuration. Instead, it uses a generated WireGuard config file to access the designated Ingress Gate- way, which is a managed server (running netclient). This server then forwards traffic to the appropriate endpoint, acting as a middle-man/relay. By using this method, you can hook any machine into a netmaker network that can run WireGuard. It is recommended to run the netclient where compatible, but for all other cases, a machine can be configured as an external client. Important to note, an external client is not reachable by the network, meaning the client can establish connections to other machines, but those machines cannot independently establish a connection back. The External Client method should only be used in use cases where one wishes to access resource runnin on the virtual network, and not for use cases where one wishes to make a resource accessible on the network. For that, use netclient.
33 Netmaker, Release 0.3.5
34 Chapter 6. External Clients CHAPTER SEVEN
GUIDES
A handful of guides for use cases including site-to-site, Kubernetes, private DNS, and more.
7.1 Using Netmaker
Netmaker has many different 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 Netmakerisa good fit, let us know!
7.1.1 External Tutorials
Members of the community have created helpful tutorials for getting started with Netmaker. Below are some selected tutorials on different topics.
Video Tutorials
• Intro/Overview: Tutorial on first-time usage, setting up a mesh network. • Site-to-Site Gateway: Tutorial on setting up site-to-site connections, allowing peers to access external networks via gateways. • IPv6 and Private DNS: Tutorial on dual-stack IPv6 in Netmaker and Private DNS management (separate topics). • Kubernetes Networking: Tutorial on setting up cross-cloud Kubernetes clusters using Netmaker.
Written Tutorials
• Kubernetes Cross-cloud cluster: Tutorial on setting up cross-cloud Kubernetes clusters using Netmaker.
7.1.2 Basic
7.1.3 Local Network
7.1.4 Site-to-Site
7.1.5 Dual Stack with IPv6
7.1.6 Kubernetes Node Network
35 Netmaker, Release 0.3.5
36 Chapter 7. Guides CHAPTER EIGHT
API REFERENCE
A reference document for the Netmaker Server API, and example API calls for various use cases. Coming Soon: Swagger Documentation
8.1 API Reference
8.1.1 API Usage
Most actions that can be performed via API can be performed via UI. We recommend managing your networks using the official netmaker-ui project. However, Netmaker can also be run without the UI, and all functions can beachievedvia API calls. If your use case requires using Netmaker without the UI or you need to do some troubleshooting/advanced configuration, using the API directly may help.
8.1.2 Authentication
API calls must be authenticated via a header of the format -H “Authorization: Bearer
8.1.3 Format of Calls for Curl
Requests take the format of curl -H “Authorization: Bearer
8.1.4 API Documentation
Networks API
Get All Networks: /api/networks, GET Create Network: /api/network, POST Get Network: /api/networks/{network id}, GET Update Network: /api/networks/{network id}, PUT
37 Netmaker, Release 0.3.5
Delete Network: /api/networks/{network id}, DELETE Cycle PublicKeys on all Nodes: /api/networks/{network id}/keyupdate, POST
Networks API Call Examples
Get All Networks: curl -H “Authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/networks | jq Create Network: curl -d ‘{“addressrange”:”10.70.0.0/16”,”netid”:”skynet”}’ -H “Authorization: Bearer YOUR_SECRET_KEY” -H ‘Content-Type: application/json’ localhost:8081/api/networks Get Network: curl -H “Authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/networks/skynet | jq Update Network: curl -X PUT -d ‘{“displayname”:”my-house”}’ -H “Authorization: Bearer YOUR_SECRET_KEY” -H ‘Content-Type: application/json’ localhost:8081/api/networks/skynet Delete Network: curl -X DELETE -H “Authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/networks/skynet Cycle PublicKeys on all Nodes: curl -X POST -H “Authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/networks/skynet/keyupdate
Access Keys API
Get All Keys: /api/networks/{network id}/keys, GET Create Key: /api/networks/{network id}/keys, GET Delete Key: /api/networks/{network id}/keys/{keyname}, DELETE
Access Keys API Call Examples
Get All Keys: curl -H “Authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/networks/skynet/keys | jq Create Key: curl -d ‘{“uses”:10,”name”:”mykey”}’ -H “Authorization: Bearer YOUR_SECRET_KEY” -H ‘Content- Type: application/json’ localhost:8081/api/networks/skynet/keys Delete Key: curl -X DELETE -H “Authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/networks/skynet/keys/mykey
Nodes API
Get All Nodes: /api/nodes, GET Get Network Nodes: /api/nodes/{network id}, GET Create Node: /api/nodes/{network id}, POST Get Node: /api/nodes/{network id}/{macaddress}, GET Update Node: /api/nodes/{network id}/{macaddress}, PUT Delete Node: /api/nodes/{network id}/{macaddress}, DELETE Check In Node: /api/nodes/{network id}/{macaddress}/checkin, POST Create a Gateway: /api/nodes/{network id}/{macaddress}/creategateway, POST Delete a Gateway: /api/nodes/{network id}/{macaddress}/deletegateway, DELETE Uncordon (Approve) a Pending Node: /api/nodes/{network id}/{macaddress}/uncordon, POST
38 Chapter 8. API Reference Netmaker, Release 0.3.5
Get Last Modified Date (Last Modified Node in Network): /api/nodes/adm/{network id}/lastmodified, GET Authenticate: /api/nodes/adm/{network id}/authenticate, POST
Nodes API Call Examples
Get All Nodes: curl -H “Authorization: Bearer YOUR_SECRET_KEY” http://localhost:8081/api/nodes | jq Get Network Nodes: curl -H “Authorization: Bearer YOUR_SECRET_KEY” http://localhost:8081/api/nodes/skynet | jq Create Node: curl -d ‘{ “endpoint”: 100.200.100.200, “publickey”: aorijqalrik3ajflaqrdajhkr,”macaddress”: “8c:90:b5:06:f1:d9”,”password”: “reallysecret”,”localaddress”: “172.16.16.1”,”accesskey”: “aA3bVG0rnItIRXDx”,”listenport”: 6400}’ -H ‘Content-Type: application/json’ -H “authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/nodes/skynet Get Node: curl -H “Authorization: Bearer YOUR_SECRET_KEY” http://localhost:8081/api/nodes/skynet/{macaddress} | jq Update Node: curl -X PUT -d ‘{“name”:”laptop1”}’ -H ‘Content-Type: application/json’ -H “authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/nodes/skynet/8c:90:b5:06:f1:d9 Delete Node: curl -X DELETE -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/skynet/nodes/8c:90:b5:06:f1:d9 Create a Gateway: curl -d ‘{ “rangestring”: “172.31.0.0/16”, “interface”: “eth0”}’ - H ‘Content-Type: application/json’ -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/nodes/skynet/8c:90:b5:06:f1:d9/creategateway Delete a Gateway: curl -X DELETE -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/nodes/skynet/8c:90:b5:06:f1:d9/deletegateway Approve a Pending Node: curl -X POST -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/nodes/skynet/8c:90:b5:06:f1:d9/approve Get Last Modified Date (Last Modified Node in Network): curl -H “authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/nodes/adm/skynet/lastmodified Authenticate: curl -d ‘{“macaddress”: “8c:90:b5:06:f1:d9”, “password”: “YOUR_PASSWORD”}’ -H ‘Content- Type: application/json’ localhost:8081/api/nodes/adm/skynet/authenticate
Users API
Note: Only able to create Admin user at this time. The “user” is only used by the user interface to authenticate the single admin user. Get User: /api/users/{username}, GET Update User: /api/users/{username}, PUT Delete User: /api/users/{username}, DELETE Check for Admin User: /api/users/adm/hasadmin, GET Create Admin User: /api/users/adm/createadmin, POST Authenticate: /api/users/adm/authenticate, POST
8.1. API Reference 39 Netmaker, Release 0.3.5
Users API Calls Examples
Get User: curl -H “Authorization: Bearer YOUR_SECRET_KEY” http://localhost:8081/api/users/{username} | jq Update User: curl -X PUT -d ‘{“password”:”noonewillguessthis”}’ -H ‘Content-Type: application/json’ -H “autho- rization: Bearer YOUR_SECRET_KEY” localhost:8081/api/users/{username} Delete User: curl -X DELETE -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/users/{username} Check for Admin User: curl -H “Authorization: Bearer YOUR_SECRET_KEY” http://localhost:8081/api/users/adm/hasadmin Create Admin User: curl -d ‘{ “username”: “smartguy”, “password”: “YOUR_PASS”}’ -H ‘Content-Type: appli- cation/json’ -H “authorization: Bearer YOUR_SECRET_KEY” localhost:8081/api/users/adm/createadmin Authenticate: curl -d ‘{“username”: “smartguy”, “password”: “YOUR_PASS”}’ -H ‘Content-Type: applica- tion/json’ localhost:8081/api/nodes/adm/skynet/authenticate
Server Management API
The Server Mgmt. API allows you to add and remove the server from networks. Add to Network: /api/server/addnetwork/{network id}, POST Remove from Network: /api/server/removenetwork/{network id}, DELETE Add to Network: curl -X POST -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/server/addnetwork/{network id} Remove from Network: curl -X DELETE -H “authorization: Bearer YOUR_SECRET_KEY” local- host:8081/api/server/removenetwork/{network id}
File Server API
Get File: /meshclient/files/{filename}, GET Example: curl localhost:8081/meshclient/files/meshclient
40 Chapter 8. API Reference CHAPTER NINE
TROUBLESHOOTING
Help with common Netmaker/netclient issues.
9.1 Troubleshooting
9.1.1 Common Issues
9.1.2 Server
9.1.3UI
9.1.4 Agent
9.1.5 CoreDNS
41 Netmaker, Release 0.3.5
42 Chapter 9. Troubleshooting CHAPTER TEN
SUPPORT
Where to go for help, and a FAQ.
10.1 Support
10.1.1 FAQ
Does/Will Netmaker Support X Operating System?
Netmaker is initially available on a limited number of operating systems for good reason: Every operating system is designed differently. With a small team, we can either focus on making Netmaker do a lot on a few number ofoperating systems, or a little on a bunch of operating systems. We chose the first option. You can view the System Compatibility docs for more info, but in general, you should only be using Netmaker on systemd linux right now. However, as of v0.4, we will technically be able to bring any operating system into the network. This is a bit of a hack. v0.4 introduces Ingress Gateways. Think of it this way. You set up a private network. You want devices to access it. You set up a single node as an “Ingress Gateway” and generate config files for “external clients.” These clients are unmanaged and unmeshed, meaning they can access the network but only via the gateway. It also means they will not automatically account for changes to the network, and the user will have to update the configs manually. This lets us immediately “support” any device which can run WireGuard, which includes most operating systems at this point including phones and Windows. As we stabilize the design and feature set of Netmaker, we will expand the operating system support for Netclient which configures dynamic, fully-meshed devices. Expect to see updates about new OS support every few weeks, until eventually the Ingress Gateway becomes unnecessary (though you will still want it for certain use cases).
How do I install the Netclient on X?
As per the above, there are many unsupported operating systems. You are still welcome to try, it is just an executable binary file after all. If the system is unix-based and has kernel WireGuard installed, netclient may very wellmeshthe device into the network. However, the service likely will encounter problems retrieving updates.
43 Netmaker, Release 0.3.5
Why MongoDB? SQL is better and smaller.
We are in a phase of rapid iteration. Every week the database schema changes. MongoDB makes our development process much more flexible. That said, we agree! SQL will be better for production, and indeed, we plan toswitchover to SQL before v1.0, so please be patient with the resource consumption of MongoDB for the time being; it is helping to support a rapid pace of development.
Is Netmaker a VPN like NordNPN?
No. Netmaker makes Virtual Networks, which are technically VPNs, but different. It’s more like a corporate VPN, or a VPC (if you’re familiar with AWS). If you’re looking to achieve self-hosted web browsing, with functionality similar to NordVPN, ExpressVPN, Surfshark, Tunnelbear, or Private Internet Access, this is probably not the project for you. Technically, you can accomplish this with Netmaker, but it would be a little like using a all-terrain vehicle for stock car racing. There are many good projects out there that support general internet privacy using WireGuard. Here are just a few of them: https://github.com/trailofbits/algo https://github.com/pivpn/pivpn https://github.com/subspacecloud/subspace https:// github.com/mullvad/mullvadvpn-app
Do you offer any paid support?
Not at this time, but eventually we will. If you are interested, or if you are interested in sponsoring the project generally, please contact Alex Feiszli ([email protected]).
Why the SSPL License?
We thought long and hard about the license. Ultimately, we think this is the best way to support and ensure the health of the project long term. The community deserves something that is well-maintained, and in order to do that, eventually we need some financial support. We won’t do that by limiting the project, but we will offer some additional support, and hosted options for things people would end up paying for anyway (relay servers, load balancing support, backups). While SSPL is not an OSI-approved open source license, it let’s people generally run the project however they want, both for private use and business use, without running into the issue of someone else monetizing the project and making it financially untenable. We are working on making the guidelines clear, and will make sure that the licensedoesnot impact the communities ability to use and modify the project. If you have concerns about the license leading to project restrictions down the road, just know that there are other paid, closed-source/closed-core options out there, so beyond not wanting to follow that path, we also don’t think it’s a good idea economically either. We firmly believe that having the project open is not only right, but the best option. All that said, we will re-evaluate the license on a regular basis and determine if an OSI-approved license makes more sense. It’s just easier to move from SSPL to another license than vice-versa.
44 Chapter 10. Support Netmaker, Release 0.3.5
10.1.2 Issues, Bugs, and Feature Requests
Issues / Bugs
Feature Requests
10.1.3 Contact
If you need help, try the discord or open a GitHub ticket. Email: [email protected] Discord: https://discord.gg/zRb9Vfhk8A
10.1. Support 45 Netmaker, Release 0.3.5
46 Chapter 10. Support CHAPTER ELEVEN
CONTRIBUTING
A guide on how to contribute to the Netmaker project.
11.1 Contribute
11.1.1 Submitting an Issue
11.1.2 Submitting an Enhancement
11.1.3 Contributing Code
Forking
Building
Testing
Submitting a PR
47 Netmaker, Release 0.3.5
48 Chapter 11. Contributing CHAPTER TWELVE
CODE OF CONDUCT
A statement on our expectations and pledge to the community.
12.1 Code of Conduct
12.1.1 Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
12.1.2 Our Standards
Examples of behavior that contributes to creating a positive environment include: • Using welcoming and inclusive language • Being respectful of differing viewpoints and experiences • Gracefully accepting constructive criticism • Focusing on what is best for the community • Showing empathy towards other community members Examples of unacceptable behavior by participants include: • The use of sexualized language or imagery and unwelcome sexual attention or advances • Trolling, insulting/derogatory comments, and personal or political attacks • Public or private harassment • Publishing others’ private information, such as a physical or electronic address, without explicit permission • Other conduct which could reasonably be considered inappropriate in a professional setting
49 Netmaker, Release 0.3.5
12.1.3 Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appro- priate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
12.1.4 Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online oroffline event. Representation of a project may be further defined and clarified by project maintainers.
12.1.5 Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.
12.1.6 Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available here.
50 Chapter 12. Code of Conduct CHAPTER THIRTEEN
LICENSING
A link to the Netmaker license.
13.1 License
Netmaker’s source code and all artifacts in this repository are freely available. All versions are published under the Server Side Public License (SSPL), version 1, which can be found here.
51