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

# Passwall Integration Guide

> Complete guide for integrating DNS-MNS with Passwall/Passwall2 on OpenWrt

# DNS-MNS Passwall Integration Guide

This guide covers the seamless integration between DNS-MNS and Passwall/Passwall2 proxy on OpenWrt routers, available in DNS-MNS v6.5.0.

## Overview

Passwall is a popular OpenWrt package that provides transparent proxy/VPN functionality with support for Shadowsocks, V2Ray, XRay, Trojan, and other protocols. DNS-MNS integrates with Passwall to provide optimized DNS resolution while Passwall handles proxy traffic.

### Key Features

* **Auto-Detection** - Automatically detects Passwall/Passwall2 installation
* **Three Integration Modes** - Cooperative, Integrated, and Override
* **Smart DNS Sync** - Synchronizes DNS-MNS optimized servers with Passwall
* **Gaming Optimization** - DNS recommendations based on Passwall's proxy mode
* **Backup & Restore** - Safely backup and restore configurations
* **UCI Integration** - Native OpenWrt UCI configuration management

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    OpenWrt Router                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐         ┌─────────────┐                   │
│  │   DNS-MNS   │◄───────►│  Passwall   │                   │
│  │             │  Sync   │  (Proxy)    │                   │
│  └──────┬──────┘         └──────┬──────┘                   │
│         │                        │                          │
│         │    ┌─────────────┐     │                          │
│         └───►│   dnsmasq   │◄────┘                          │
│              │   (DNS)     │                                │
│              └──────┬──────┘                                │
│                     │                                       │
│              ┌──────┴──────┐                                │
│              │   Clients   │                                │
│              └─────────────┘                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Integration Modes

### Cooperative Mode (Recommended)

In cooperative mode, DNS-MNS and Passwall work independently:

* **DNS-MNS** handles DNS resolution with optimized servers
* **Passwall** handles proxy/VPN traffic routing
* **Best for** most users who want optimal performance

```bash theme={null}
# Configure cooperative mode
dns-mns passwall configure --mode cooperative
```

**How it works:**

1. DNS-MNS runs on port 5353 (or custom port)
2. dnsmasq uses DNS-MNS as upstream DNS
3. Passwall routes proxy traffic through its configured servers
4. DNS queries and proxy traffic are handled separately

### Integrated Mode

In integrated mode, DNS-MNS routes upstream queries through Passwall's proxy:

* **Use case** when DNS is blocked and needs to go through proxy tunnel
* **Benefit** bypasses DNS blocking in heavily restricted networks
* **Trade-off** may add slight latency

```bash theme={null}
# Configure integrated mode
dns-mns passwall configure --mode integrated
```

**How it works:**

1. DNS-MNS routes DNS queries through Passwall's SOCKS proxy
2. DNS queries go through the proxy tunnel
3. Helps bypass DNS blocking and poisoning

### Override Mode

In override mode, DNS-MNS takes over Passwall's DNS configuration:

* **Use case** when you want complete DNS control
* **Benefit** unified DNS management
* **Trade-off** Passwall's built-in DNS is disabled

```bash theme={null}
# Configure override mode
dns-mns passwall configure --mode override
```

**How it works:**

1. Passwall's DNS configuration is disabled
2. DNS-MNS becomes the primary DNS handler
3. All DNS queries go through DNS-MNS

## Prerequisites

* OpenWrt 19.07+ with Passwall or Passwall2 installed
* DNS-MNS v6.5.0+ installed on router
* Passwall configured with at least one working proxy node

## Installation

### Step 1: Install DNS-MNS

Follow the [OpenWrt Installation Guide](/openwrt-integration) to install DNS-MNS on your router.

### Step 2: Verify Passwall Installation

```bash theme={null}
# Check if Passwall is installed
dns-mns passwall status
```

If Passwall is not installed:

```bash theme={null}
# Install Passwall (using opkg)
opkg update
opkg install luci-app-passwall

# Or install Passwall2
opkg install luci-app-passwall2
```

### Step 3: Configure Integration

```bash theme={null}
# Recommended: Configure cooperative mode
dns-mns passwall configure --mode cooperative

# Verify configuration
dns-mns passwall status
```

## CLI Commands

### Check Status

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

Shows:

* Passwall variant (Passwall/Passwall2)
* Installation and running status
* DNS mode and filter mode
* Integration mode
* Recommendations

### Configure Integration

```bash theme={null}
# Configure with specific mode
dns-mns passwall configure --mode <cooperative|integrated|override>

# Configure with custom port
dns-mns passwall configure --mode cooperative --port 5353
```

### Sync DNS Settings

```bash theme={null}
# Sync DNS-MNS optimized servers with Passwall
dns-mns passwall sync
```

This updates Passwall's remote DNS with DNS-MNS's best performing servers.

### Gaming Optimization

```bash theme={null}
# Optimize DNS for gaming with Passwall
dns-mns passwall gaming
```

Provides gaming-optimized DNS configuration based on:

* Passwall's current proxy mode
* Network conditions
* Gaming requirements

### Restore Configuration

```bash theme={null}
# Restore original Passwall configuration
dns-mns passwall restore
```

Restores the original configuration from backup.

## Interactive Menu

Access Passwall integration through the interactive menu:

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

Select **Option 11: Passwall Integration**

Menu options:

1. Check Status - Show detailed Passwall integration status
2. Configure Integration - Set up integration mode
3. Gaming Optimization - Optimize DNS for gaming
4. Sync DNS Settings - Sync with Passwall
5. Restore Configuration - Restore original settings

## Gaming with Passwall

### Optimal Setup for Gaming

1. **Configure Passwall in Game Mode** (if available)
   ```bash theme={null}
   # In Passwall web UI, set DNS mode to "Game Mode"
   ```

2. **Use DNS-MNS Cooperative Mode**
   ```bash theme={null}
   dns-mns passwall configure --mode cooperative
   ```

3. **Apply Gaming DNS**
   ```bash theme={null}
   dns-mns passwall gaming
   ```

### Recommended DNS for Gaming

| Passwall Mode | Primary DNS    | Secondary DNS  | Notes                           |
| ------------- | -------------- | -------------- | ------------------------------- |
| Game Mode     | 10.202.10.10   | 178.22.122.100 | Direct DNS for low latency      |
| Global Proxy  | 1.1.1.1        | 8.8.8.8        | International DNS through proxy |
| GFW List      | 178.22.122.100 | 1.1.1.1        | Mixed approach                  |

## Troubleshooting

### Passwall Not Detected

```bash theme={null}
# Check if Passwall UCI config exists
ls -la /etc/config/passwall*

# Check if init script exists
ls -la /etc/init.d/passwall*
```

### DNS Not Working After Configuration

```bash theme={null}
# Restart dnsmasq
/etc/init.d/dnsmasq restart

# Check dnsmasq configuration
uci show dhcp.@dnsmasq[0]

# Check if DNS-MNS is running
dns-mns openwrt status
```

### Restore Original Configuration

```bash theme={null}
# Restore from backup
dns-mns passwall restore

# Restart services
/etc/init.d/dnsmasq restart
/etc/init.d/passwall restart
```

### Check Logs

```bash theme={null}
# DNS-MNS logs
tail -f /var/log/dns-mns.log

# dnsmasq logs
logread | grep dnsmasq

# Passwall logs
logread | grep passwall
```

## Advanced Configuration

### Custom DNS Servers

```bash theme={null}
# Set custom DNS for Passwall sync
dns-mns passwall sync --dns 1.1.1.1,8.8.8.8
```

### JSON Output

All commands support JSON output for scripting:

```bash theme={null}
dns-mns passwall status --json
dns-mns passwall configure --mode cooperative --json
dns-mns passwall gaming --json
```

### Integration with Auto-Benchmarking

Enable auto-benchmarking to automatically update Passwall DNS:

```bash theme={null}
# Enable scheduler
uci set dns-mns.@main[0].scheduler_enabled='1'
uci set dns-mns.@main[0].benchmark_interval='6h'
uci commit dns-mns

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

## FAQ

### Q: Which integration mode should I use?

**A:** For most users, **Cooperative Mode** is recommended:

* Best performance
* DNS and proxy handled separately
* Lowest latency for gaming

Use **Integrated Mode** only if:

* DNS is being blocked/poisoned
* You're in a heavily restricted network
* You need DNS through proxy tunnel

### Q: Will this affect my existing Passwall configuration?

**A:** DNS-MNS creates a backup before making changes. You can restore the original configuration with:

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

### Q: Can I use Passwall without DNS-MNS?

**A:** Yes, Passwall works independently. DNS-MNS integration is optional but provides optimized DNS performance.

### Q: Does this work with Passwall2?

**A:** Yes, DNS-MNS supports both Passwall (legacy) and Passwall2 (modern).

### Q: What happens if I uninstall DNS-MNS?

**A:** Before uninstalling, run:

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

This restores the original Passwall configuration.

## See Also

* [OpenWrt Integration Guide](/openwrt-integration)
* [OpenWrt Features](/openwrt-features)
* [CLI Reference](/reference/cli)