How To Run Netclient On OpenWRT

Step 1: Setup Storage

Installing large packages on OpenWRT can be challenging due to limited storage space on many routers. To expand your firmware's space to install more packages, refer to this OpenWRT article:

https://openwrt.org/docs/guide-user/additional-software/extroot_configuration

Step 2: Install WireGuard

Netmaker uses WireGuard for VPN communication. Ensure that your OpenWRT device has WireGuard installed. It’s recommended to install WireGuard via the web UI:

• Go to System → Software

• Click the “Update lists…” button, then search for WireGuard

• Install wireguard-tools and luci-proto-wireguard (for the web GUI)

• Reboot

Step 3: Install and Configure Netclient

Netclient can be run as a Docker container or installed directly on the host machine. Note: Docker Netclients on version 0.24.3 and earlier have a known bug fixed in 0.25.0.

To install the kernel version, copy and paste the install command (remove sudo if running on OpenWRT) and execute it. You can then join a Netmaker network using the enrollment key or by using the netclient join command.

NOTE: Netclient versions 1.2.0 and 1.4.0 cannot be installed directly on OpenWRT. Workaround: install Netclient version 1.0.0 and let it auto-upgrade to v1.4.0 (or whatever version your server uses).

As of Netclient v0.25.0, installation may show this error:

error running command: /etc/init.d/netclient stop

This has no known consequence on OpenWRT and can be ignored.

Alternative: run Netclient as a Docker container on OpenWRT. See the OpenWRT Docker guide:

https://openwrt.org/docs/guide-user/virtualization/docker_host

Install Docker and Docker Client with:

opkg update
opkg install dockerd docker

Once installed, run and join Netclient with the docker run command. Consider adding --restart=always so the container runs after router boot.

Notes:

• After joining, OpenWRT will be able to access resources within the Netmaker network.

• By default, devices on the Netmaker network will not be able to ping the OpenWRT machine, and OpenWRT will not act as a Remote Access Gateway, Relay, Egress Gateway, or Internet Gateway until firewall rules are adjusted. This is expected because OpenWRT’s firewall blocks that traffic by default.

Step 4: Register the Tunnel Interface

The tunnel interface that Netclient creates is recognized as a device named by default "netmaker." Create a new unmanaged interface via LuCI:

Network → Interfaces → Add new interface

• Name: netmakerif (any name)

• Protocol: Unmanaged

• Device: netmaker

Click "Create interface". In the modal form, if you are running CoreDNS on your Netmaker server, go to Advanced Settings and specify the public IP of the server in "Use custom DNS servers". Click Save.

To persist changes, click "Save & Apply" and then reboot the router.

Step 5: Create Firewall Zone

Create a firewall zone for the Netmaker interface via LuCI:

Network → Firewall → Zones → Add

• Name: netmakerzn (or any other name)

• Input: ACCEPT

• Output: ACCEPT

• Forward: ACCEPT

• Masquerading: on

• MSS Clamping: on

• Covered networks: netmakerif (or your custom interface name)

Allow forward to destination zones:

• Select LAN and/or any other internal zones to allow Netmaker resources to reach devices in these zones (useful if OpenWRT is an Egress Gateway).

• Select WAN if you intend to use OpenWRT as an Internet Gateway / exit node.

Allow forward from source zones:

• Select your LAN and/or other internal zones to allow machines there to reach Netmaker resources (required if using this device as a gateway in site-to-site setups). Leave blank otherwise.

Click Save, then Save & Apply.

After saving, the firewall zone table should include the new entry.

Step 6: Add Port Forwarding Rules (for Remote Access Gateway)

Only necessary if OpenWRT should function as a Remote Access Gateway. Create a port forward via LuCI:

Network → Firewall → Port Forwards → Add

Create port forwarding rules from WAN to "netmakerzn".

• Name: netmaker (or any other name)

• Protocol: TCP/UDP

• Source Zone: WAN

• External port: 51821 (or any port; default 51821). To find the port: in NMUI, open the Netmaker network → Remote Access tab → find OpenWRT → view the VPN config. In the [Peer] section, look for the number after the IP address in Endpoint.

• Destination zone: netmakerzn (or the name from Step 5)

• Internal IP address: Netmaker IP address of OpenWRT

• Internal Port: 51821

Click Save, then Save & Apply.

It is crucial to review routes and firewall rules configured by Netclient on your OpenWRT device.