DocsAPI

Quick Install

Fast and Easy Setup for Secure Network Management

Welcome to the Netmaker Quick Install Guide!Copied!

This guide will help you set up your Netmaker server quickly, using a virtual machine, physical server, or cloud. We'll cover all the essential steps, including prerequisites, installation, and configuring firewall rules. By the end of this guide, you'll have a fully operational Netmaker server, optimized for secure network management using WireGuard.

PrerequisitesCopied!

Operating System & Server RequirementsCopied!

All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here are setup specifications:

  • Ubuntu 24.04.

  • Public static IP address (required for communication between nodes).

  • Domain name (preferred)  (e.g., netmaker.example.com) with DNS management access.

  • System resources:

    • Minimum: 1 GB RAM, 1 CPU, 2 GB storage.

    • Recommended (production): 2 GB RAM, 2 CPU, 10 GB storage.

  • Recommendation: Use Netmaker in a dedicated network for optimal performance.

Recommended Cloud ProvidersCopied!

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

Netmaker Firewall RulesCopied!

Ensure that the firewall settings for Netmaker are properly configured on both the VM and your cloud security groups (e.g., AWS, GCP) or on your router/firewall appliance:

  • 80, 443 (TCP): For Caddy (serving the UI, REST API, and MQTT broker)

  • 51821 (UDP), 443 (UDP): For WireGuard traffic (default Netclient port)

  • 51821 (TCP): Utilized for endpoint detection, allowing peers in the same VPC to connect via private IPs instead of public ones, improving efficiency and reducing latency.

  • 53 (TCP and UDP): If you set the CoreDNS container, that comes with the Netmaker installation, to ‘host’ your domain name resolution needs.

  • 8085 (Exporter Pro): If you are building a Pro server, you need this port open.

  • 1883, 8883 8083, 18083 (if using EMQX): We use two different types of brokers. There is Mosquitto or EMQX. Mosquitto is our default offering which uses ports 8883 and 1883. If you are setting up EMQX, all four ports mentioned need to be opened for MQTT, SSL MQTT, web sockets, and the EMQX dashboard/REST API.

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

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

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

# Allow TCP on port 51821 for endpoint detection 
sudo ufw allow 51821/tcp

#optional: only when hosting DNS on the Netmaker server
sudo ufw allow 53

# Optional: Necessary for building a Pro server
sudo ufw allow 8085/tcp

# Optional: When setting up EMQX
sudo ufw allow 1883/tcp
sudo ufw allow 8883/tcp
sudo ufw allow 8083/tcp
sudo ufw allow 18083/tcp

# Enable UFW if it is not already enabled
sudo ufw enable

It’s important to make sure that the server isn’t blocking traffic forwarding, as some providers may have this setting enabled by default. To guarantee the forwarding of traffic:

iptables --policy FORWARD ACCEPT

Netclient Firewall RulesCopied!

The server deploys a Netclient

On Linux, these necessary ports are needed to be opened:

  • UDP and TCP ports 51821-51830 for inbound and outbound (based on your client’s listen port running on the machine). As well as UDP port 443

  • TCP port 443 for outbound

  • UDP ports 19302 & 3478 for STUN outbound requests

For advanced use cases, you might need to view your device’s firewall logs, or in the case of Netclients behind a NAT, your Firewall-Appliance/Router’s firewall logs. Look for blocked traffic coming in and out having origin/destination IPs of your devices.

For example, in UFW you may do:

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

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

#reload ufw
ufw reload

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

DomainCopied!

Your server will host several services (netmaker server, UI, etc.) each of which requires a dedicated, public subdomain. Here are some recommendations:

Important Note on Cloudflare: Many users utilize Cloudflare, but its proxying of connections can interfere with MQ functionality. You can disable this feature in the Cloudflare DNS dashboard. If you plan to set up your Netmaker server with Cloudflare DNS, be aware that the Cloudflare proxy configuration may lead to issues with Netmaker. Currently, Netmaker does not offer guidance for resolving these problems.

Quick Install ScriptCopied!

Execute the nm-quick script for a self-hosted or on-premises setup:

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

IMPORTANT: Notes on Installation - Due to the high volume of installations, the auto-generated domain has been rate-limited by the certificate provider. For this reason, we strongly recommend using your domain. Using the auto-generated domain may lead to a failed installation due to rate limiting.

Integrating OAuthCopied!

Users are also allowed to join a Netmaker server via OAuth. They can do this by clicking the “Login with SSO” button on the dashboard’s login page. Check out the integrating oauth docs.

After the trial period endsCopied!

  1. if you wish to continue using PRO:

    1. check these steps to obtain pro license: https://docs.netmaker.io/docs/server-installation/netmaker-professional-setup

    2. Run /root/nm-quick.sh -u

  2. if you wish to downgrade to the community version

    1. Run /root/nm-quick.sh -d

    To get started the easiest way, visit our SaaS platform to set up a netmaker server with just a few clicks https://app.netmaker.io

Post-Installation: Accessing the Dashboard & Creating a Super AdminCopied!

Once you’ve successfully completed the Quick Install, it's time to log into the Netmaker dashboard and create a Super Admin. Follow these steps to get started:

1. Access the Netmaker Dashboard

  • Open a web browser and navigate to the URL of your Netmaker dashboard.

    • If you're using a custom domain, it will look like https://dashboard.example.com.

    • If you opted for the auto-generated domain, the URL will follow the format provided during installation (e.g., https://dashboard.nm.<your-server-ip>.nip.io).

2. Log In

  • On the login screen, use the initial admin credentials created during installation.

3. Create a user

  • Once logged in, navigate to the User Management interface in the left-hand sidebar.

  • Click on Add a User: There are two ways to add users in Netmaker Professional:

    • Basic Auth: Directly create users by specifying their username, password, and any groups or roles.

    • User Invite: Send invitations via email (SMTP setup only required for self-hosted setup). Users receive a link to create their account with pre-assigned roles and groups.

  • Fill in the required fields in case you selected Create a User:

    • Username.

    • Password.

    • Platform Access Level: Select Admin.

  • Click Create User.

  • Fill in the required fields in case you selected Invite a User:

    • Email address(es).

    • Platform Access Level: Select Admin.

  • Click Create User Invite(s).

4. Test the Super Admin Access

  • Log out of the current session.

  • Log back in using the new Super Admin credentials.

  • Verify that you have access to all administrative features in the dashboard.

Next StepsCopied!

Now that you have a basic understanding, here are a few resources to help you continue: