> ## Documentation Index
> Fetch the complete documentation index at: https://e-gurl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenWrt Router Support

> Configure and run DNS-MNS on OpenWrt routers for network-wide smart DNS

# OpenWrt Router Support

DNS-MNS now supports OpenWrt routers, allowing you to provide smart DNS resolution for your entire network. This is especially useful for Iranian users who want to bypass DNS censorship for all devices on their home network.

## Overview

DNS-MNS on OpenWrt operates in two modes:

<CardGroup cols={2}>
  <Card title="Upstream Mode (Recommended)" icon="arrow-up">
    DNS-MNS works alongside dnsmasq. Dnsmasq stays on port 53 and forwards queries to DNS-MNS running on a different port.
  </Card>

  <Card title="Direct Mode" icon="bolt">
    DNS-MNS replaces dnsmasq on port 53. Dnsmasq DNS is disabled, but DHCP continues to work.
  </Card>
</CardGroup>

## Installation

### Download the Correct Binary

OpenWrt runs on various architectures. Download the appropriate binary for your router:

| Architecture | Download File             | Common Routers                       |
| ------------ | ------------------------- | ------------------------------------ |
| x86\_64      | `dns-mns-openwrt-x86_64`  | x86 routers, virtual machines        |
| MIPS         | `dns-mns-openwrt-mips`    | Older routers (TP-Link WR841N, etc.) |
| MIPSel       | `dns-mns-openwrt-mipsel`  | Some TP-Link and D-Link models       |
| ARM v7       | `dns-mns-openwrt-armv7`   | Raspberry Pi 2/3, modern routers     |
| ARM64        | `dns-mns-openwrt-aarch64` | Raspberry Pi 4, high-end routers     |

### Identify Your Router Architecture

SSH into your OpenWrt router and run:

```bash theme={null}
uname -m
```

Common outputs:

* `x86_64` → Use x86\_64 binary
* `mips` → Use MIPS binary
* `mipsel` or `mipsle` → Use MIPSel binary
* `armv7l` → Use ARM v7 binary
* `aarch64` → Use ARM64 binary

### Install on OpenWrt

1. **Download to your computer**, then copy to the router:

```bash theme={null}
# From your computer
scp dns-mns-openwrt-x86_64 root@192.168.1.1:/tmp/
```

2. **SSH to router** and install:

```bash theme={null}
ssh root@192.168.1.1
mv /tmp/dns-mns-openwrt-x86_64 /usr/bin/dns-mns
chmod +x /usr/bin/dns-mns
```

3. **Verify installation**:

```bash theme={null}
dns-mns --version
```

## Configuration

### Step 1: Detect OpenWrt

Verify DNS-MNS detects your OpenWrt system correctly:

```bash theme={null}
dns-mns openwrt detect
```

Example output:

```
[OK] OpenWrt detected!

  Version:  23.05.0
  Board:    x86/64

[OK] dnsmasq is installed
[OK] dnsmasq is running
  Port:     53
```

### Step 2: Choose and Setup Mode

<Tabs>
  <Tab title="Upstream Mode (Recommended)">
    In this mode, dnsmasq remains the primary DNS on port 53, but forwards queries to DNS-MNS.

    ```bash theme={null}
    dns-mns openwrt setup --mode upstream --listen 127.0.0.1 --port 5353
    ```

    This will:

    * Configure dnsmasq to forward DNS queries to 127.0.0.1:5353
    * Backup your original dnsmasq configuration
    * Restart dnsmasq with new settings

    Then start the DNS-MNS proxy:

    ```bash theme={null}
    dns-mns proxy --listen 127.0.0.1:5353 --protocol auto
    ```
  </Tab>

  <Tab title="Direct Mode">
    In this mode, DNS-MNS takes over port 53 directly. Dnsmasq DNS is disabled.

    ```bash theme={null}
    dns-mns openwrt setup --mode direct
    ```

    This will:

    * Set dnsmasq port to 0 (disable DNS)
    * Backup your original dnsmasq configuration
    * Restart dnsmasq (DHCP only)

    Then start DNS-MNS on port 53:

    ```bash theme={null}
    dns-mns proxy --listen :53 --protocol auto
    ```

    <Warning>
      In direct mode, if DNS-MNS stops, DNS resolution will fail. Make sure to set up auto-start.
    </Warning>
  </Tab>
</Tabs>

### Step 3: Check Status

View the current configuration:

```bash theme={null}
dns-mns openwrt status
```

Example output:

```
========================================
OPENWRT STATUS
========================================
  OpenWrt Version:  23.05.0
  Board:            x86/64

  dnsmasq Status:
    Installed: Yes
    Running:   Yes
    Port:      53
    Upstream:  127.0.0.1:5353

  DNS-MNS Status:
    Configured: Yes
    Mode:        upstream
========================================
```

### Step 4: Enable Auto-Start

To start DNS-MNS automatically on boot:

```bash theme={null}
# Install the init script (included in release)
cp /path/to/dns-mns.init /etc/init.d/dns-mns
chmod +x /etc/init.d/dns-mns

# Create UCI config
cat > /etc/config/dns-mns << 'EOF'
config dns-mns 'main'
	option enabled '1'
	option mode 'upstream'
	option listen_addr '127.0.0.1'
	option listen_port '5353'
	option auto_start '1'
EOF

# Enable and start service
/etc/init.d/dns-mns enable
/etc/init.d/dns-mns start
```

## Managing the Service

### Start/Stop/Restart

```bash theme={null}
# Start
/etc/init.d/dns-mns start

# Stop
/etc/init.d/dns-mns stop

# Restart
/etc/init.d/dns-mns restart

# Check status
/etc/init.d/dns-mns status
```

### View Logs

```bash theme={null}
# Real-time logs
logread -f | grep dns-mns

# Recent logs
logread | grep dns-mns
```

## Restoring Original Configuration

If you need to revert to your original dnsmasq configuration:

```bash theme={null}
dns-mns openwrt restore
```

This will:

* Restore dnsmasq configuration from backup
* Restart dnsmasq with original settings
* Remove DNS-MNS configuration

## CLI Commands Reference

| Command                                 | Description                                       |
| --------------------------------------- | ------------------------------------------------- |
| `dns-mns openwrt detect`                | Detect if running on OpenWrt and show system info |
| `dns-mns openwrt setup --mode upstream` | Configure dnsmasq to use DNS-MNS as upstream      |
| `dns-mns openwrt setup --mode direct`   | Configure DNS-MNS to replace dnsmasq on port 53   |
| `dns-mns openwrt status`                | Show current OpenWrt DNS configuration            |
| `dns-mns openwrt restore`               | Restore original dnsmasq configuration            |

### Setup Flags

| Flag           | Description                             | Default     |
| -------------- | --------------------------------------- | ----------- |
| `--mode`       | Operation mode: `upstream` or `direct`  | `upstream`  |
| `--listen`     | Listen address for DNS-MNS              | `127.0.0.1` |
| `--port`       | Listen port for DNS-MNS (upstream mode) | `5353`      |
| `--auto-start` | Enable auto-start on boot               | `true`      |

## Troubleshooting

### DNS-MNS Not Detecting OpenWrt

If `dns-mns openwrt detect` fails, verify:

```bash theme={null}
# Check for OpenWrt files
ls /etc/openwrt_release /etc/openwrt_version 2>/dev/null

# Check for uci
which uci
```

### Dnsmasq Fails to Start

If dnsmasq fails after configuration:

```bash theme={null}
# Check for configuration errors
dnsmasq --test --conf-file=/etc/dnsmasq.conf

# Restore backup manually
cp /etc/config/dhcp.dns-mns-backup /etc/config/dhcp
uci commit dhcp
/etc/init.d/dnsmasq restart
```

### Port Already in Use

If port 5353 is already in use:

```bash theme={null}
# Find what's using the port
netstat -tlnp | grep 5353

# Use a different port
dns-mns openwrt setup --mode upstream --port 5354
```

### Low Memory on Router

For routers with limited RAM (\< 64MB):

```bash theme={null}
# Use direct mode (less memory overhead)
dns-mns openwrt setup --mode direct

# Or limit concurrent connections
dns-mns proxy --listen 127.0.0.1:5353 --protocol auto &
echo $! > /var/run/dns-mns.pid
```

## Building from Source for OpenWrt

To build a custom binary for your router:

```bash theme={null}
# Clone repository
git clone https://gitlab.com/E-Gurl/dns-mns.git
cd dns-mns

# Build for your router architecture
# x86_64
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -extldflags '-static'" -o dns-mns-openwrt-x86_64 ./cmd/dns-mns/

# MIPS
CGO_ENABLED=0 GOOS=linux GOARCH=mips GOMIPS=softfloat go build -ldflags="-s -w -extldflags '-static'" -o dns-mns-openwrt-mips ./cmd/dns-mns/

# ARM v7
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w -extldflags '-static'" -o dns-mns-openwrt-armv7 ./cmd/dns-mns/
```

Or use the Makefile:

```bash theme={null}
make build-openwrt
make verify-static
```

## Comparison with SmartDNS

| Feature                 | DNS-MNS             | SmartDNS   |
| ----------------------- | ------------------- | ---------- |
| DoH/DoT Support         | ✅ Built-in          | ✅ Yes      |
| DNSCrypt Support        | ✅ Built-in          | ❌ No       |
| Auto Protocol Switching | ✅ Yes               | ⚠️ Limited |
| Iran-Optimized          | ✅ Yes               | ⚠️ Generic |
| DPI Evasion             | ✅ TLS Fragmentation | ❌ No       |
| Censorship Detection    | ✅ Yes               | ❌ No       |
| VLESS/REALITY Proxy     | ✅ Built-in          | ❌ No       |
| OpenWrt Integration     | ✅ Native UCI        | ✅ Yes      |

## Best Practices

1. **Start with Upstream Mode**: It's safer and allows easy rollback
2. **Backup Your Config**: Before making changes, backup `/etc/config/dhcp`
3. **Test Before Auto-Start**: Manually test DNS resolution before enabling auto-start
4. **Monitor Memory Usage**: On low-end routers, monitor with `free -h`
5. **Use Dashboard**: Run `dns-mns dashboard` to monitor performance

## Related

* [Setting DNS](/usage/setting-dns) - General DNS configuration
* [Fallback Proxy](/usage/fallback-proxy) - Auto-switching encrypted DNS proxy
* [DPI Evasion](/usage/dpi-evasion) - Bypassing deep packet inspection