Skip to content

Commit 3b0f380

Browse files
tuanductrantuanductran
authored
Merge branch 'main' into copilot/add-ddwrt-installation-rule
Signed-off-by: Tuan Duc Tran <tuanductran.dev@gmail.com>
2 parents c48208c + cc86c9f commit 3b0f380

5 files changed

Lines changed: 396 additions & 0 deletions

File tree

‎skills/integrations/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ metadata:
1313

1414
| Rule | Keywords | Description |
1515
|------|----------|-------------|
16+
| [DNSMasq Integration](rules/dnsmasq-integration.md) | dnsmasq, dns, router, client reporting, conditional configuration, port configuration, setup-router | Configure DNSMasq and NextDNS to run together while maintaining client reporting and conditional configuration features |
1617
| [Public DNS and AdGuard Home Integration](rules/public-dns-and-adguard.md) | public dns, adguard, anycast, doh, dot, browser setup, windows, android, ios, upstream dns, bootstrap dns | Configure NextDNS public DNS servers on browsers and operating systems, and integrate with AdGuard Home as upstream DNS provider |
1718
| [OpenWrt Integration](rules/openwrt.md) | openwrt, router, installation, upgrade, troubleshooting, ssh, luci | Installation, upgrade, and troubleshooting guidance for NextDNS on OpenWrt routers |
1819

‎skills/integrations/rules/dnsmasq-integration.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: DNSMasq Integration
3+
impact: MEDIUM
4+
impactDescription: Running DNSMasq alongside NextDNS without proper configuration can result in loss of client reporting and conditional configuration features. This guidance ensures both services work together seamlessly while maintaining full NextDNS functionality.
5+
type: capability
6+
tags: dnsmasq, dns, router, client reporting, conditional configuration, port configuration, setup-router
7+
---
8+
9+
# DNSMasq Integration
10+
11+
**Impact: MEDIUM** - Enables DNSMasq and NextDNS to run together while preserving client reporting and conditional configuration capabilities
12+
13+
## Overview
14+
15+
DNSMasq is a lightweight DNS forwarder commonly bundled with router firmwares. It is possible to run DNSMasq and NextDNS together on the same system while maintaining full NextDNS functionality, including client reporting and conditional configuration features.
16+
17+
This integration allows DNSMasq to continue handling local DNS resolution and DHCP services while forwarding external DNS queries to NextDNS for filtering and protection.
18+
19+
## Configuration Steps
20+
21+
### Step 1: Configure NextDNS to Listen on Alternative Port
22+
23+
NextDNS must be configured to listen on a different port to avoid conflicts with DNSMasq, which typically uses port 53.
24+
25+
```bash
26+
# Configure NextDNS to listen on port 5555 on localhost
27+
nextdns install -listen 127.0.0.1:5555
28+
```
29+
30+
This configuration ensures NextDNS binds to port 5555 instead of the default port 53, allowing DNSMasq to continue operating on port 53.
31+
32+
### Step 2: Configure DNSMasq to Forward to NextDNS
33+
34+
Add the following parameters to your DNSMasq configuration to forward DNS queries to NextDNS while preserving client information:
35+
36+
```conf
37+
# Forward DNS queries to NextDNS on port 5555
38+
--server=127.0.0.1#5555
39+
40+
# Include client MAC address in DNS queries
41+
--add-mac
42+
43+
# Include client subnet information (IPv4: /32, IPv6: /128)
44+
--add-subnet=32,128
45+
```
46+
47+
These parameters ensure that:
48+
49+
- `--server=127.0.0.1#5555`: All DNS queries are forwarded to NextDNS running on port 5555
50+
- `--add-mac`: Client MAC addresses are included in DNS queries, enabling device identification
51+
- `--add-subnet=32,128`: Client subnet information is added for IPv4 (/32) and IPv6 (/128), supporting conditional configuration
52+
53+
## Automatic Configuration for Router Firmwares
54+
55+
On router firmwares that ship with DNSMasq pre-installed, the above configuration can often be handled automatically.
56+
57+
When running NextDNS installation on such routers, use the `-setup-router` parameter:
58+
59+
```bash
60+
# Automatic router setup (handles DNSMasq configuration)
61+
nextdns install -setup-router
62+
```
63+
64+
The `-setup-router` flag automatically detects DNSMasq and configures both services to work together without manual intervention. This is the recommended approach for router environments.
65+
66+
## Best Practices
67+
68+
- **Use alternative port**: Always configure NextDNS to use a non-standard port (e.g., 5555) when running alongside DNSMasq
69+
- **Preserve client information**: Ensure `--add-mac` and `--add-subnet` parameters are set to maintain client reporting features
70+
- **Prefer automatic setup**: On router firmwares, use `-setup-router` parameter for automatic configuration
71+
- **Verify forwarding**: Test DNS resolution after configuration to ensure queries are properly forwarded to NextDNS
72+
- **Check logs**: Monitor both DNSMasq and NextDNS logs to verify proper operation and client identification
73+
74+
## Troubleshooting
75+
76+
### Port Conflicts
77+
78+
If you encounter port binding errors, verify that:
79+
80+
- DNSMasq is running on port 53
81+
- NextDNS is configured to use an alternative port (e.g., 5555)
82+
- No other services are using the chosen alternative port
83+
84+
```bash
85+
# Check which service is using port 53
86+
netstat -tulpn | grep :53
87+
88+
# Verify NextDNS is listening on the configured port
89+
netstat -tulpn | grep :5555
90+
```
91+
92+
### Client Reporting Not Working
93+
94+
If client devices are not appearing correctly in NextDNS analytics:
95+
96+
- Verify `--add-mac` parameter is enabled in DNSMasq configuration
97+
- Check that `--add-subnet` parameter is properly configured
98+
- Ensure DNS queries are being forwarded to NextDNS (check DNSMasq logs)
99+
100+
### Router Firmware Issues
101+
102+
If `-setup-router` fails or doesn't configure properly:
103+
104+
- Fall back to manual configuration using Steps 1 and 2
105+
- Check router firmware documentation for DNSMasq configuration location
106+
- Ensure you have appropriate permissions to modify DNSMasq configuration
107+
108+
## Reference
109+
110+
- [NextDNS CLI Wiki](https://github.com/nextdns/nextdns/wiki)
111+
- [DNSMasq Documentation](https://thekelleys.org.uk/dnsmasq/doc.html)
112+
- [NextDNS Setup Guide](https://help.nextdns.io)

‎skills/nextdns-cli/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,15 @@ metadata:
1414
| Rule | Keywords | Description |
1515
|------|----------|-------------|
1616
| [installation](rules/installation.md) | install, setup, curl, nextdns install | Install NextDNS CLI on various platforms |
17+
| [macos-installation](rules/macos-installation.md) | macOS, Homebrew, App Store, installer | Install and configure NextDNS CLI on macOS |
1718
| [daemon-control](rules/daemon-control.md) | start, stop, restart, status, daemon | Control NextDNS daemon service |
1819
| [system-configuration](rules/system-configuration.md) | activate, deactivate, DNS resolver | Configure system DNS settings |
1920
| [profile-configuration](rules/profile-configuration.md) | config, profile ID, settings | Configure NextDNS profile and settings |
2021
| [advanced-features](rules/advanced-features.md) | conditional forwarder, MAC address, subnet | Advanced routing and filtering |
2122
| [monitoring](rules/monitoring.md) | log, cache-stats, discovered clients | Monitor and debug DNS queries |
2223
| [platform-specific](rules/platform-specific.md) | router, OpenWrt, pfSense, Synology | Platform-specific configurations |
2324
| [ddwrt-installation](rules/ddwrt-installation.md) | DD-WRT, JFFS, NTP, router, time sync, dnsmasq | DD-WRT router installation and setup |
25+
| [docker-deployment](rules/docker-deployment.md) | docker, container, DockerHub, host network, port mapping | Deploy NextDNS CLI via Docker containers |
2426
| [troubleshooting](rules/troubleshooting.md) | diagnostic, connection test, DNS leak | Troubleshoot DNS issues |
2527

2628
## Efficiency Rules

‎skills/nextdns-cli/rules/docker-deployment.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
title: Docker Deployment
3+
impact: HIGH
4+
impactDescription: Proper Docker deployment ensures NextDNS CLI runs efficiently with correct network configuration for host detection and client IP visibility
5+
type: capability
6+
tags: docker, container, DockerHub, host network, port mapping, deployment
7+
---
8+
9+
# Docker Deployment
10+
11+
**Impact: HIGH** - Essential container deployment patterns for optimal DNS resolution and client tracking
12+
13+
NextDNS CLI is available as pre-built Docker images on DockerHub (`nextdns/nextdns`), enabling containerized deployments across various platforms. The networking mode significantly affects functionality, particularly for host detection and client IP visibility.
14+
15+
## Host Network Mode (Recommended)
16+
17+
Using host network mode allows the NextDNS CLI container to see actual LAN IP addresses and enables host detection features:
18+
19+
```bash
20+
docker run -d --network host --restart unless-stopped nextdns/nextdns run -listen=:53 -profile=abc123
21+
```
22+
23+
### Why Host Network Mode?
24+
25+
- **Real IP Visibility**: The CLI sees actual client IP addresses from your LAN instead of Docker's internal NAT IPs.
26+
- **Host Detection**: Automatic device identification works properly since the CLI can observe network traffic patterns.
27+
- **Performance**: Eliminates NAT overhead for DNS queries.
28+
- **Simplicity**: No port mapping required, direct access to port 53.
29+
30+
### Important Considerations
31+
32+
- Host network mode only works on Linux hosts.
33+
- The container shares the host's network stack directly.
34+
- Ensure no other service is listening on port 53 on the host.
35+
36+
## Port Translation Mode
37+
38+
When host network mode is not available or desired, use port mapping:
39+
40+
```bash
41+
docker run -d -p 53:53/tcp -p 53:53/udp --restart unless-stopped nextdns/nextdns run -listen=:53 -profile=abc123
42+
```
43+
44+
### Limitations
45+
46+
- **NAT IP Addresses**: All clients appear as internal Docker NATed IP addresses (typically from the Docker bridge network).
47+
- **No Host Detection**: Device identification features will not work properly.
48+
- **Query Attribution**: All queries appear to come from the Docker container's IP rather than individual clients.
49+
50+
### When to Use
51+
52+
- On macOS or Windows Docker Desktop where host networking is not supported.
53+
- In environments where network isolation is required.
54+
- For testing or development purposes.
55+
56+
## Persistence Configuration
57+
58+
The `--restart unless-stopped` flag ensures the container automatically restarts on system boot and after Docker daemon restarts:
59+
60+
```bash
61+
docker run -d \
62+
--name nextdns \
63+
--network host \
64+
--restart unless-stopped \
65+
nextdns/nextdns run -listen=:53 -profile=abc123
66+
```
67+
68+
### Restart Policy Options
69+
70+
- `unless-stopped`: Container restarts automatically unless explicitly stopped (recommended for production).
71+
- `always`: Container always restarts, even after manual stops (not recommended).
72+
- `on-failure`: Only restarts on non-zero exit codes.
73+
- `no`: No automatic restart (default, not recommended for DNS services).
74+
75+
## Configuration File Persistence
76+
77+
To persist configuration across container restarts, mount the configuration directory:
78+
79+
```bash
80+
docker run -d \
81+
--name nextdns \
82+
--network host \
83+
--restart unless-stopped \
84+
-v /etc/nextdns:/etc/nextdns \
85+
nextdns/nextdns run -listen=:53 -profile=abc123
86+
```
87+
88+
This allows the CLI to store and read configuration from `/etc/nextdns` on the host system.
89+
90+
## Best Practices
91+
92+
- **Always Use Restart Policy**: DNS services must be highly available. Use `--restart unless-stopped` for production deployments.
93+
- **Prefer Host Network Mode**: On Linux systems, host network mode provides the best functionality and performance.
94+
- **Profile ID Management**: Store profile IDs securely, consider using Docker secrets or environment variables for sensitive configurations.
95+
- **Resource Limits**: In production, consider setting memory and CPU limits to prevent resource exhaustion.
96+
- **Logging**: Use Docker logging drivers to capture and rotate NextDNS CLI logs appropriately.
97+
98+
## Container Management
99+
100+
```bash
101+
# View container status
102+
docker ps -f name=nextdns
103+
104+
# View logs
105+
docker logs nextdns
106+
107+
# Stop container
108+
docker stop nextdns
109+
110+
# Remove container
111+
docker rm nextdns
112+
113+
# Pull latest image
114+
docker pull nextdns/nextdns:latest
115+
```
116+
117+
## Troubleshooting
118+
119+
### Port Already in Use
120+
121+
If port 53 is already in use:
122+
123+
```bash
124+
# Check what's using port 53
125+
sudo lsof -i :53
126+
# or
127+
sudo netstat -tulpn | grep :53
128+
129+
# Common conflicts: systemd-resolved, dnsmasq
130+
# Disable systemd-resolved if needed
131+
sudo systemctl disable systemd-resolved
132+
sudo systemctl stop systemd-resolved
133+
```
134+
135+
### Container Not Starting
136+
137+
Check logs for errors:
138+
139+
```bash
140+
docker logs nextdns
141+
```
142+
143+
Common issues:
144+
- Invalid profile ID
145+
- Port conflicts
146+
- Network configuration errors
147+
- Insufficient permissions
148+
149+
## Reference
150+
151+
- [NextDNS CLI GitHub](https://github.com/nextdns/nextdns)
152+
- [NextDNS Docker Hub](https://hub.docker.com/r/nextdns/nextdns)
153+
- [Docker Networking Documentation](https://docs.docker.com/engine/network/)
154+
- [Docker Restart Policies](https://docs.docker.com/config/containers/start-containers-automatically/)

0 commit comments

Comments
 (0)