# How To Run Netclient On OpenWRT

{% stepper %}
{% step %}

### 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>
{% endstep %}

{% step %}

### 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
  {% endstep %}

{% step %}

### 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).*

![](/files/Q0sskXw5uNDocGrHERXI)

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:

```plaintext
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.

![](/files/HkzAEBUdzAJd8ov6sVjt)

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.
  {% endstep %}

{% step %}

### 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

![](/files/16b8d2e5982c06bb5dd6f9583ad7d2a7ca499a28)

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.

![](/files/6d75f1d8716e8480850f81eaa3d3f2b9a255090e)

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

![](/files/8898ac44cce079dc81c83055e6ef37ee3503e2d0)
{% endstep %}

{% step %}

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

![](/files/041c7ad2905c56f6c704e56ec760ab6eeec59893)

After saving, the firewall zone table should include the new entry.
{% endstep %}

{% step %}

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

![](/files/8e60139c85db9940bba83f881a7848d5ea692d15)

It is crucial to review routes and firewall rules configured by Netclient on your OpenWRT device.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
If you choose to run Netclient in Docker, you may need to create users and groups and set appropriate folder permissions. For simplicity in demos, containers are sometimes run as root, but consider security implications for production.
{% endhint %}

{% hint style="warning" %}
Disclaimer

The information in this guide is for general informational purposes only. No warranty is made regarding the accuracy, reliability, or completeness of the information. Use this guide at your own risk. The authors and maintainers are not liable for any loss or damage resulting from the use of this guide.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.netmaker.io/how-to-guides/how-to-run-netclient-on-openwrt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.