DOCSEARCHbyAlgolia
Submit Docs

Netmaker

repository·develop·Indexed 11 days ago

https://github.com/gravitl/netmaker

A WireGuard® automation platform for creating and managing virtual networks, including Mesh VPNs, Site-to-Site connections, and Remote Access Gateways. Supports Linux, Docker, Mac, and Windows, with deployment options for Kubernetes, cloud VMs, and a managed SaaS platform.

Tokens
24.9K
Snippets
151
Records
174
Agent score
95%

What's inside Netmaker

  1. Use the MasterKey for emergency access

    develop

    Netmaker provides a MasterKey which can be used for authentication if standard user authentication fails (e.g., if server access is lost).

    Security Warning: The default MasterKey is secret key. You must change this value in your environment variables or configuration file to a secure string and keep it protected. It should only be used as a backup option.

  2. Self-Hosted Open Source Quick Start

    develop

    To deploy the open source version of Netmaker on a cloud VM as quickly as possible, follow these steps:

    1. Prepare the VM: Use a cloud VM running Ubuntu 24.04 with a static public IP.
    2. Configure Firewall:
      • Allow inbound traffic on port 443 (TCP) and port 51821 (TCP and UDP).
      • For simplicity, allow all outbound TCP and UDP traffic.
    3. Configure DNS (Recommended): Set up a wildcard subdomain in your DNS settings (e.g., *.netmaker.example.com) pointing to your VM's public IP.
    4. Run the Installation Script: Execute the following command to download and run the quick install script.

    Note: For the PRO Version, refer to the official Netmaker Professional Setup documentation.

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

  3. Authenticate API calls using a Bearer token

    develop

    Netmaker API calls are authenticated using a user authentication token. You must include this token in the Authorization header of your HTTP requests using the Bearer scheme.

    To obtain a token, you must first call the api/users/adm/authenticate endpoint.

    -H "Authorization: Bearer <YOUR_AUTH_TOKEN>"

  4. Deploy the Netmaker Server

    develop

    Configure and deploy the Netmaker Server using netmaker-server.yaml.

    1. Subdomain: Set your wildcard subdomain (e.g., nm.mydomain.com).
    2. Ingress: If using Nginx, uncomment the Nginx section at the bottom.
    3. Database: Provide the PostgreSQL deployment name and the password retrieved in the database step.
    4. Master Key: Set a secure password for the Netmaker API.
    5. API Ingress: Ensure an Ingress object is created to route traffic to the netmaker-rest service on port 8081.

    Deployment commands:

    sed -i 's/NETMAKER_SUBDOMAIN/<your subdomain>/g' netmaker-server.yaml
sed -i 's/DB_NAME/<postgres helm name>/g' netmaker-server.yaml
sed -i 's/DB_PASS/<postgres helm password>/g' netmaker-server.yaml
sed -i 's/REPLACE_MASTER_KEY/<super secret password>/g' netmaker-server.yaml

kubectl apply -f netmaker-server.yaml

# Restart MQ to ensure connection
kubectl delete pod mosquitto-<pod name>

    Success is indicated when Netmaker pods log: [netmaker] ... successfully connected to mq broker.

  5. Prerequisites for deploying Netmaker on Kubernetes

    develop

    Before deploying Netmaker using the K8S YAML templates, ensure your cluster meets these requirements:

    • Nodes: At least 3 worker nodes are required. Netmaker uses anti-affinity, so pods will not deploy on the same node.
    • Storage: Both RWX (ReadWriteMany) and RWO (ReadWriteOnce) storage classes must be available.
    • Ingress: Must be configured with certificates. Nginx + LetsEncrypt is the default. The ingress controller must support WebSockets for MQTT (Secure Websockets/WSS).
    • DNS: A wildcard DNS entry is required for Ingress/Netmaker (e.g., *.yourdomain.com).
    • Helm: Required for the PostgreSQL installation.
    • MQ Broker Connectivity: If your Ingress does not support WebSockets, you must use a NodePort or a specialized TCPIngressRoute (for Traefik) to route traffic to the MQ service on port 8883.

  7. Deploy the Netmaker UI

    develop

    Deploy the Netmaker UI using netmaker-ui.yaml.

    1. Set your subdomain using sed.
    2. If using Nginx + LetsEncrypt, uncomment the Ingress section in the YAML; otherwise, configure Ingress manually.
    3. Apply the file.
    sed -i 's/NETMAKER_SUBDOMAIN/<your subdomain>/g' netmaker-ui.yaml
kubectl apply -f netmaker-ui.yaml

  8. Deploy a High-Availability PostgreSQL Database

    develop

    For high availability, use the Bitnami PostgreSQL Helm chart.

    1. Add the Bitnami repository.
    2. Install the PostgreSQL deployment.
    3. Retrieve the generated password to use in the Netmaker Server configuration.
    helm repo add bitnami https://charts.bitnami.com/bitnami
helm install postgres bitnami/postgresql

# Confirm pods are running
kubectl get pods

# Retrieve the postgres password
kubectl get secret --namespace netmaker postgres-postgresql -o jsonpath="{.data.postgres-password}" | base64 -d

  9. Deploy MQTT (Mosquitto) with different Ingress strategies

    develop

    Deploy the MQTT broker using mosquitto.yaml. You must modify the template based on your Ingress provider:

    Scenario A: Nginx

    1. Remove the pod affinity and NodePort sections.
    2. Uncomment the Ingress section at the bottom.
    3. Replace NETMAKER_SUBDOMAIN with your domain.
    4. Replace RWX_STORAGE_CLASS with your storage class.

    Scenario B: External Load Balancer

    1. Remove the pod affinity section.
    2. Configure the LB to load balance TLS traffic to the MQ service on port 8883. Ensure it supports WSS.
    3. If using a non-standard port, update MQ_PORT in netmaker-server.yaml.
    4. Replace RWX_STORAGE_CLASS in mosquitto.yaml.

    Scenario C: Traefik

    1. Remove the pod affinity section.
    2. Create a TCPIngressRoute from port 443 to the mq service on port 8883.
    3. Replace RWX_STORAGE_CLASS in mosquitto.yaml.

    Apply the configuration:

    sed -i 's/NETMAKER_SUBDOMAIN/<your subdomain>/g' mosquitto.yaml
sed -i 's/RWX_STORAGE_CLASS/<your storage class name>/g' mosquitto.yaml
kubectl apply -f mosquitto.yaml

  11. Netmaker Docker Compose Service Overview

    develop

    The Netmaker deployment via Docker Compose consists of the following services:

    • netmaker: The core Netmaker service. Uses volumes dnsconfig and sqldata for persistence.
    • netmaker-ui: The web interface. Depends on the netmaker service.
    • caddy: A reverse proxy/web server. Maps ports 80, 443, and 50051. Uses volumes caddy_data and caddy_conf.
    • mq: The message queue (Mosquitto). Uses volumes mosquitto_logs and mosquitto_data for persistence.

    Required Volumes for Persistence:

    • caddy_data: Runtime data for Caddy.
    • caddy_conf: Configuration files for Caddy.
    • sqldata: Netmaker database storage.
    • dnsconfig: Storage for CoreDNS.
    • mosquitto_logs: MQTT logs.
    • mosquitto_data: MQTT data.

  12. Configure Netmaker server modes (REST and MessageQueue)

    develop

    Netmaker can operate in different backend modes. To serve traffic, you must enable one or both of the following via environment variables:

    • REST_BACKEND: Set to true to enable the REST API server.
    • MESSAGEQUEUE_BACKEND: Set to true to enable the Message Queue (MQTT) backend.

    If neither is set to true, the server will start but will not serve any requests.