Hands-On Guide to Netmaker v0.13.1

Yoshiaki Senda
6 min readMay 7, 2022


This hands-on guide shows you how to set-up Office-Home Wireguard mesh network using Netmaker v0.13.1.

<Hands-on guide to Netmaker v0.14.2 is out! Please see here.>


Office network has dynamic global IP that binds to office router and office workstation is behind a NAT. Home network has dynamic global IP that binds to home router and home PC is behind a NAT. Netmaker (server) will place on cloud and static global IP is attached.

Installation of Netmaker

Before install Netmaker, let’s create a VM on your preferred cloud. This guide will use Lightsail on AWS.

VM preparation

  • Create a VM with 4GB of memory and 2 vCPU running Ubuntu 22.04
  • Attach static global IP to your VM
  • Add wildcard A record to your DNS that points to the public IP of your VM
  • Allow 80/tcp, 443/tcp, 8883/tcp, 51821–51830/udp from
  • Install dependencies to your VM ( sudo apt update && sudo apt install -y docker.io docker-compose wireguard)

Once you booted up Ubuntu box, download docker-compose.yml file from Netmaker repository.

$ sudo su -
$ wget -O docker-compose.yml \

Set your base domain, this domain should be matched to wildcard A record that you added to your DNS. Here is the example command that assumes your wildcard A record looks like *.netmaker.example.jp A 54.XXX.YYY.ZZZ

$ sed -i 's/NETMAKER_BASE_DOMAIN/netmaker.example.jp/g' docker-compose.yml

Set your server IP (global IP).

$ curl ifconfig.me
$ sed -i 's/SERVER_PUBLIC_IP/54.XXX.YYY.ZZZ/g' docker-compose.yml

Set your CoreDNS IP. If you run VM on AWS, global IP is not directly bind to network interface of VM. In such a case, we need to set the IP of the default interface.

$ (ip route get 1 | sed -n 's/^.*src \([0-9.]*\) .*$/\1/p')
$ sed -i 's/COREDNS_IP/172.XXX.YYY.ZZZ/g' docker-compose.yml

Generate a master key and populate it.

$ tr -dc A-Za-z0-9 </dev/urandom | head -c 30 ; echo ''
sed -i 's/REPLACE_MASTER_KEY/8I9Ifom5xfiEVrcatsfsXXXXXXXXXX/g' docker-compose.yml

Prepare Caddy. Set your base domain and E-mail address for acquiring wildcard SSL certificate from Let’s encrypt.

wget -O /root/Caddyfile \
sed -i 's/NETMAKER_BASE_DOMAIN/netmaker.example.jp/g' /root/Caddyfile
sed -i 's/YOUR_EMAIL/netmaker@example.jp/g' /root/Caddyfile

Prepare MQ

wget -O /root/mosquitto.conf \

Let’s spin up Netmaker

docker-compose up -d

Web UI

Open https://dashboard.netmaker.example.jp on your browser and create an admin user to get started.

Log-in to web UI

Create Network

Create network called awesome

Click network name to configure this network

Create Access Key

Set number to Usesthat satisfies expected user volume

Copy Client Install Commands . Use this command later to add client to this network.

Installation of Netclient (Office Workstation & Home PC)

Install dependencies

sudo apt update && sudo apt install -y wireguard

Install Netclient and Join to Netmaker network

Paste Client Install Commands to your client terminal

sudo su -
curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/netclient-install.sh | VERSION=v0.13.1 KEY=XXXXXXXX sh -

You can check your netclient status with:

systemctl status netclient

On v0.13.1, I got following error (error message below has been partially omitted to simplify message). This is just a status check error and if your client can ping through Netmaker network, you can ignore it. This will fix in v0.14 according to Netmaker team.

could not ping server for awesome broker.netmaker.example.jp
ping error 100.000000

Let’s check IP of nm-awesome device on Office workstation.

$ ip a
nm-awesome: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1280 qdisc noqueue state UNKNOWN group default qlen 1000
inet scope global nm-awesome
valid_lft forever preferred_lft forever
bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
link/ether de:AA:BB:CC:DD:EE brd ff:ff:ff:ff:ff:ff
inet brd scope global bond0
valid_lft forever preferred_lft forever

Check IP of nm-awesome device on Home PC

$ ip a
nm-awesome: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1280 qdisc noqueue state UNKNOWN group default qlen 1000
inet scope global nm-awesome
valid_lft forever preferred_lft forever
Wireguard Mesh Networking using Netmaker

Ping office workstation from home PC.

$ ping

If ping doesn’t reach, check wireguard connection with wg show on home PC.

$ wg show
interface: nm-awesome
public key: i3c2HJr+LpXBKv9d166OwPE7ZkMHOwsG/XXXXXXX=
private key: (hidden)
listening port: 43449
peer: pvQRAMxKGh8Lzj4Mt3lHqYJesJZ2uXXXXXXX=
endpoint: 54.XXX.YYY.ZZZ:51821
allowed ips:,
latest handshake: 50 seconds ago
transfer: 0 B received, 48.56 KiB sent
persistent keepalive: every 20 seconds

If you see 0B received that means wireguard connection is not established. Sometimes MTU is a cause, but since Netmaker’s default MTU is low enough, I’ll explain another possibility such as ”UDP hole punching doesn’t work” case.

UDP hole punching

When we create awesome network, we enabled UDP hole punching . This is convenient if your consumer grade router is UPnP enabled that automatically open UDP port to the public for you and map that port to your netclient installed PC.

If your router does not support or disabled UPnP, you need to configure your router manually. You need to open udp port to the public, for example 51821/udp, for wireguard connection and map that port to your PC that is netclient installed. If there is a firewall you also need to change that settings to allow wireguard connections.

But not always you can administer a router/firewall on both end. If you can’t change settings of office router/firewall, it’s time to make use of Relay functionality of Netmaker.


You can setup Netmaker server as a Relay. Open Nodes tab of Netmaker web UI. Click “Make Relay” of netmaker-1.

Select office workstation , and click CREATE button.

Now your graph looks like below. If you connect to office workstation from home PC, all the traffic go through Netmaker server. If you place your Netmaker server on cloud, you need to watch transfer costs in some use cases.

Ping may work now.

$ ping

Egress Gateway

To access office network (ex. from home PC. Configure office PC as Egress Gateway. Before hands, check route of office PC.

$ route U 0 0 0 bond0 U 0 0 0 nm-awesome
home-pc.aweso UH 0 0 0 nm-awesome
netmaker-1.awes UH 0 0 0 nm-awesome

Click Nodes > Create Egress Gateway

Set Egress Gateway Range, , this could be a subnet in your office.

Access Office Network from Home PC

Check route of home PC.

$ route U 0 0 0 nm-awesome U 0 0 0 nm-awesome

If route doesn’t appear, manually pull configuration from Netmaker. Then check route again.

sudo netclient pull

SSHing to PC ( in office network from home PC through office workstation.

$ ssh -l user -i .ssh/id_rsaWelcome to Ubuntu 20.04.2 LTS