Advanced Server Installation

This section outlines installing the Netmaker server, including Netmaker, Netmaker UI, rqlite, and CoreDNS

System Compatibility

Netmaker will require elevated privileges to perform network operations. Netmaker has similar limitations to netclient (client networking agent).

Typically, Netmaker is run inside of containers (Docker). To run a non-docker installation, you must run the Netmaker binary, CoreDNS binary, rqlite, and a web server directly on the host. Each of these components have their own individual requirements.

The quick install guide is recommended for first-time installs.

The following documents are meant for special cases like Kubernetes and LXC, or for more advanced setups.

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 the docker 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.

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.

Test Install - No DNS, No Secure GRPC

This install will run Netmaker on a server without HTTPS using an IP address. This is not secure and not recommended, but can be helpful for testing.

It also does not run the CoreDNS server, to simplify the deployment

Prerequisites:

  • server ports 80, 8081, and 50051 are not blocked by firewall

Notes:

  • 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.test.yml

  2. sed -i ‘s/HOST_IP/< Insert your-host IP Address Here >/g’ docker-compose.yml

  3. docker-compose up -d

No DNS - CoreDNS Disabled

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.

To run without DNS, follow the Quick Install guide, omitting the steps for DNS setup. In addition, when the guide has you pull (wget) the Netmaker docker-compose template, use the following link instead:

  1. wget -O docker-compose.yml https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/docker-compose.nodns.yml

This template is equivalent but omits CoreDNS.

Reference 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.

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:
      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.5
    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 CoreDNS from compose file.
      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.
      GRPC_SSL: "off" # Tells clients to use SSL to connect to GRPC. Switch to on to turn on.
      SERVER_API_CONN_STRING: "" # Changes the api connection string. IP:PORT format. By default is empty and uses SERVER_HOST:API_PORT
      SERVER_GRPC_CONN_STRING: "" # Changes the grpc connection string. IP:PORT format. By default is empty and uses SERVER_HOST:GRPC_PORT
  netmaker-ui: # The Netmaker UI Component
    container_name: netmaker-ui
    depends_on:
      - netmaker
    image: gravitl/netmaker-ui:v0.5
    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: {}

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 HTML on 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.

rqlite Setup

  1. Install rqlite on your server: https://github.com/rqlite/rqlite

  2. Run rqlite: rqlited -node-id 1 ~/node.1

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://<YOUR BACKEND API URL>:PORT /usr/share/nginx/html/generate_config_js.sh >/usr/share/nginx/html/config.js'

  6. Start Nginx: sudo systemctl start nginx

CoreDNS Setup

Kubernetes Install

This configuration is coming soon. It will allow you to deploy Netmaker on a Kubernetes cluster.

Configuration Reference

The “Reference Compose File” (above) explains many of these options. However, it is important to understand fundamentally 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 DISABLE_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.

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 to secure 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.

GRPC_SSL

Default: “”

Description: Specifies if GRPC is going over secure GRPC or SSL. This is a setting for the clients and is passed through the access token. Can be set to “on” and “off”. Set to on if SSL is configured for GRPC.

SERVER_API_CONN_STRING

Default: “”

Description: Allows specification of the string used to connect to the server api. Format: IP:PORT or DOMAIN:PORT. Defaults to SERVER_HOST if not specified.

SERVER_GRPC_CONN_STRING

Default: “”

Description: Allows specification of the string used to connect to grpc. Format: IP:PORT or DOMAIN:PORT. Defaults to SERVER_HOST if not specified.

Config File Reference

A config file may be placed under config/environments/<env-name>.yml. To read this file at runtime, provide the environment variable ENV at runtime. For instance, dev.yml paired with ENV=dev. Netmaker will load the specified Config file. This allows you to store and manage configurations for different environments. Below is a reference Config File you may use.

server:
  apihost: "" # defaults to 127.0.0.1 or remote ip (SERVER_HOST) if DisableRemoteIPCheck 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)

Nginx Reverse Proxy Setup with https

The Swag Proxy makes it easy to generate a valid ssl certificate for the config bellow. Here is the documentation for the installation.

The following file configures Netmaker as a subdomain. This config is an adaption from the swag proxy project.

./netmaker.subdomain.conf:

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name netmaker.*; # The external URL
    client_max_body_size 0;

    # A valid https certificate is needed.
    include /config/nginx/ssl.conf;

    location / {
        # This config file can be found at:
        # https://github.com/linuxserver/docker-swag/blob/master/root/defaults/proxy.conf
        include /config/nginx/proxy.conf;

        # if you use a custom resolver to find your app, needed with swag proxy
        # resolver 127.0.0.11 valid=30s;
        set $upstream_app netmaker-ui;                             # The internal URL
        set $upstream_port 80;                                     # The internal Port
        set $upstream_proto http;                                  # the protocol that is being used
        proxy_pass $upstream_proto://$upstream_app:$upstream_port; # combine the set variables from above
        }
    }

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name backend-netmaker.*; # The external URL
    client_max_body_size 0;
    underscores_in_headers on;

    # A valid https certificate is needed.
    include /config/nginx/ssl.conf;

    location / {
        # if you use a custom resolver to find your app, needed with swag proxy
        # resolver 127.0.0.11 valid=30s;

        set $upstream_app netmaker;                                # The internal URL
        set $upstream_port 8081;                                   # The internal Port
        set $upstream_proto http;                                  # the protocol that is being used
        proxy_pass $upstream_proto://$upstream_app:$upstream_port; # combine the set variables from above

        # Forces the header to be the one that is visible from the outside
        proxy_set_header                Host backend.netmaker.example.org; # Please cange to your URL

        # Pass all headers through to the backend
        proxy_pass_request_headers      on;
        }
    }