Add DNSMasq integration rule for NextDNS coexistence - #14
Conversation
Co-authored-by: tuanductran <69758022+tuanductran@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR adds a new integration rule to guide users on running dnsmasq alongside NextDNS while preserving client reporting and conditional configuration features. The integration addresses a common scenario where routers come with dnsmasq pre-installed and need to coexist with NextDNS.
Changes:
- New integration rule documenting dnsmasq and NextDNS coexistence setup
- Updated skill manifest to register the new rule with appropriate keywords
- Configuration guidance for port settings, client identification parameters, and automatic router setup
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.
| File | Description |
|---|---|
| skills/integrations/rules/dnsmasq-integration.md | Comprehensive guide for configuring dnsmasq to forward DNS queries to NextDNS on an alternative port while preserving client information via MAC addresses and subnet data |
| skills/integrations/SKILL.md | Registered new dnsmasq integration rule in the capability rules table with appropriate keywords and description |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - DNSMasq is running on port 53 | ||
| - NextDNS is configured to use an alternative port (e.g., 5555) | ||
| - No other services are using the chosen alternative port | ||
|
|
||
| ```bash | ||
| # Check which service is using port 53 | ||
| netstat -tulpn | grep :53 | ||
|
|
||
| # Verify NextDNS is listening on the configured port | ||
| netstat -tulpn | grep :5555 | ||
| ``` | ||
|
|
||
| ### Client Reporting Not Working | ||
|
|
||
| If client devices are not appearing correctly in NextDNS analytics: | ||
|
|
||
| - Verify `--add-mac` parameter is enabled in DNSMasq configuration | ||
| - Check that `--add-subnet` parameter is properly configured | ||
| - Ensure DNS queries are being forwarded to NextDNS (check DNSMasq logs) | ||
|
|
||
| ### Router Firmware Issues | ||
|
|
||
| If `-setup-router` fails or doesn't configure properly: | ||
|
|
||
| - Fall back to manual configuration using Steps 1 and 2 | ||
| - Check router firmware documentation for DNSMasq configuration location | ||
| - Ensure you have appropriate permissions to modify DNSMasq configuration |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase, not "DNSMasq".
| ## Reference | ||
|
|
||
| - [NextDNS CLI Wiki](https://github.com/nextdns/nextdns/wiki) | ||
| - [DNSMasq Documentation](https://thekelleys.org.uk/dnsmasq/doc.html) |
There was a problem hiding this comment.
The link text should use "dnsmasq" in lowercase, not "DNSMasq", to match the official project name.
| - [DNSMasq Documentation](https://thekelleys.org.uk/dnsmasq/doc.html) | |
| - [dnsmasq documentation](https://thekelleys.org.uk/dnsmasq/doc.html) |
|
|
||
| | Rule | Keywords | Description | | ||
| |------|----------|-------------| | ||
| | [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 | |
There was a problem hiding this comment.
The table entry uses "DNSMasq" in mixed case, but based on codebase conventions and the official project name, it should be "dnsmasq" in lowercase. This applies to both the link text and the description.
| | [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 | | |
| | [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 | |
|
|
||
| # DNSMasq Integration | ||
|
|
||
| **Impact: MEDIUM** - Enables DNSMasq and NextDNS to run together while preserving client reporting and conditional configuration capabilities |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase, not "DNSMasq".
| 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. | ||
|
|
||
| This integration allows DNSMasq to continue handling local DNS resolution and DHCP services while forwarding external DNS queries to NextDNS for filtering and protection. |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase, not "DNSMasq".
| NextDNS must be configured to listen on a different port to avoid conflicts with DNSMasq, which typically uses port 53. | ||
|
|
||
| ```bash | ||
| # Configure NextDNS to listen on port 5555 on localhost | ||
| nextdns install -listen 127.0.0.1:5555 | ||
| ``` | ||
|
|
||
| This configuration ensures NextDNS binds to port 5555 instead of the default port 53, allowing DNSMasq to continue operating on port 53. | ||
|
|
||
| ### Step 2: Configure DNSMasq to Forward to NextDNS | ||
|
|
||
| Add the following parameters to your DNSMasq configuration to forward DNS queries to NextDNS while preserving client information: |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase, not "DNSMasq".
| @@ -0,0 +1,112 @@ | |||
| --- | |||
| title: DNSMasq Integration | |||
There was a problem hiding this comment.
The project name "dnsmasq" should be in lowercase, not "DNSMasq". Throughout the codebase (e.g., skills/integrations/rules/openwrt.md:68, skills/nextdns-cli/rules/installation.md:49, skills/nextdns-cli/rules/platform-specific.md:13, skills/nextdns-cli/rules/troubleshooting.md:54), "dnsmasq" is consistently written in lowercase. The official project also uses lowercase as evidenced by the documentation URL (thekelleys.org.uk/dnsmasq/doc.html). This violates the case-police rules specified in CLAUDE.md.
| --- | ||
| title: DNSMasq Integration | ||
| impact: MEDIUM | ||
| 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. |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase throughout the file, not "DNSMasq". This is inconsistent with the rest of the codebase and the official project naming. All occurrences in this file should use lowercase "dnsmasq".
| tags: dnsmasq, dns, router, client reporting, conditional configuration, port configuration, setup-router | ||
| --- | ||
|
|
||
| # DNSMasq Integration |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase, not "DNSMasq".
| On router firmwares that ship with DNSMasq pre-installed, the above configuration can often be handled automatically. | ||
|
|
||
| When running NextDNS installation on such routers, use the `-setup-router` parameter: | ||
|
|
||
| ```bash | ||
| # Automatic router setup (handles DNSMasq configuration) | ||
| nextdns install -setup-router | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
||
| ## Best Practices | ||
|
|
||
| - **Use alternative port**: Always configure NextDNS to use a non-standard port (e.g., 5555) when running alongside DNSMasq | ||
| - **Preserve client information**: Ensure `--add-mac` and `--add-subnet` parameters are set to maintain client reporting features | ||
| - **Prefer automatic setup**: On router firmwares, use `-setup-router` parameter for automatic configuration | ||
| - **Verify forwarding**: Test DNS resolution after configuration to ensure queries are properly forwarded to NextDNS | ||
| - **Check logs**: Monitor both DNSMasq and NextDNS logs to verify proper operation and client identification |
There was a problem hiding this comment.
The project name should be "dnsmasq" in lowercase, not "DNSMasq".
Adds integration guidance for running DNSMasq alongside NextDNS while preserving client reporting and conditional configuration capabilities.
Changes
New rule:
skills/integrations/rules/dnsmasq-integration.md--add-mac,--add-subnet=32,128)-setup-routerflag for router firmwaresSkill manifest: Updated
skills/integrations/SKILL.mddnsmasq, dns, router, client reporting, conditional configuration, port configuration, setup-routerConfiguration Pattern
Router firmwares with pre-installed DNSMasq can use
nextdns install -setup-routerfor automatic configuration.Original prompt
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.