CalvinBackup/ctrld
1
0
Fork 0
mirror of https://github.com/Control-D-Inc/ctrld.git synced 2026-02-16 10:22:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Created NextDNS Mode (markdown)

Yegor S
2023-11-20 18:03:25 -05:00
parent 2b2dfe6b43
commit 7fe4c7dbf2
1 changed files with 174 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
NextDNS-Mode.md Normal file

@@ -0,0 +1,174 @@
# Requirements
v1.3.2 must be installed in order to use this guide.
# Overview
`ctrld` is a customizable DNS forwarding proxy server that runs on any operating system, most routers, and can be used to send DNS queries to any upstream, using any DNS protocol. NextDNS mode allows for a 1 liner command setup of `ctrld` with NextDNS service, while relaying client specific metadata (MAC address, IP address, Hostname) to a NextDNS upstream, similar to the [native app](https://github.com/nextdns/nextdns).
As far as I can tell, `ctrld` is feature complete with the NextDNS analog (all functionality of the NextDNS app is supported as of v1.3.2), but also includes other functionality such as support for all DNS protocols, multiple listeners, richer configuration syntax, support for more routers, and highly advanced modes of operation.
## Supported Platforms
* Asus Merlin
* DD-WRT
* Firewalla
* FreshTomato
* GL.iNet
* OpenWRT
* pfSense / OPNsense
* Synology
* Ubiquiti (UniFi, EdgeOS)
* Windows
* MacOS
* Linux (any)
# Why this exists
We want you to try our app with NextDNS, love all the things you can do with it, and then maybe check out this Control D thing.
# How to Use
You can [get the binaries here](https://github.com/Control-D-Inc/ctrld/releases), but the simplest way to get `ctrld` on your device is using the installer command:
## Linux/MacOS/FreeBSD Install
```
sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"'
```
## Windows Install
```
powershell -Command "(Invoke-WebRequest -Uri 'https://api.controld.com/dl' -UseBasicParsing).Content | Set-Content 'ctrld_install.bat'" && ctrld_install.bat
```
## Usage
The above commands will install the binary into the correct directory (installer will show you where), based on your platform. Here is an example from pfSense, but all platforms are the same.
```
[2.7.0-RELEASE][root@pfSense.home.arpa]/root: sh -c 'sh -c "$(curl -sSL https://api.controld.com/dl)"'
__ .__ .___
_____/ |________| | __| _/
_/ ___\ __\_ __ \ | / __ |
\ \___| | | | \/ |__/ /_/ |
\___ >__| |__| |____/\____ |
\/ installer \/
---------------------
| System Info |
---------------------
OS Type : freebsd
OS Vendor : pfSense
Arch : amd64
CPU : 13th Gen Intel(R) Core(TM) i7-13700K
Free RAM : 70 MB / 448 MB
---------------------
| Install Details |
---------------------
Binary URL : https://assets.controld.com/ctrld/freebsd/amd64/ctrld
Install Path : /usr/local/bin
---------------------
Install binary and run it? (y/n): y
- Starting download
- Making binary executable
- Launching /usr/local/bin/ctrld
---------------------
__ .__ .___
_____/ |________| | __| _/
_/ ___\ __\_ __ \ | / __ |
\ \___| | | | \/ |__/ /_/ |
\___ >__| |__| |____/\____ |
\/ dns forwarding proxy \/
Usage:
ctrld [command]
Available Commands:
run Run the DNS proxy server
service Manage ctrld service
start Quick start service and configure DNS on interface
stop Quick stop service and remove DNS from interface
restart Restart the ctrld service
reload Reload the ctrld service
status Show status of the ctrld service
uninstall Stop and uninstall the ctrld service
clients Manage clients
Flags:
-h, --help help for ctrld
-s, --silent do not write any log output
-v, --verbose count verbose log output, "-v" basic logging, "-vv" debug level logging
--version version for ctrld
Use "ctrld [command] --help" for more information about a command.
[2.7.0-RELEASE][root@pfSense.home.arpa]/root:
```
The binary is installed, but currently not doing anything. In order for it to do stuff, use the `start` command with the `--nextdns` flag, while supplying your ID.
```
[2.7.0-RELEASE][root@pfSense.home.arpa]/root: ctrld start --nextdns 8cec72
Nov 20 22:44:21.000 NTC Starting service
Nov 20 22:44:21.000 NTC Generating nextdns config: /etc/controld/ctrld.toml
Nov 20 22:44:26.000 NTC Service started
```
That's it, you're done here. You can check that it works using a dig or nslookup command, or simply view your Logs in NextDNS.
```
[2.7.0-RELEASE][root@pfSense.home.arpa]/root: dig test.com
; <<>> DiG 9.18.14 <<>> test.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 25793
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
;; QUESTION SECTION:
;test.com. IN A
;; ANSWER SECTION:
test.com. 3600 IN A 67.225.146.248
;; Query time: 42 msec
;; SERVER: 127.0.0.1#53(127.0.0.1) (UDP)
;; WHEN: Mon Nov 20 22:44:38 UTC 2023
;; MSG SIZE rcvd: 53
[2.7.0-RELEASE][root@pfSense.home.arpa]/root:
```
![image](https://github.com/Control-D-Inc/ctrld/assets/817935/94d9245a-5b21-4e93-8f9c-405342bad8e2)
By default, `ctrld` will send all traffic from your device or router to the chosen NextDNS profile, using DOH3 protocol, while appending LAN metadata just like the native app. If you wish to get fancy, read on.
# Advanced Usages
Everything is config driven, and the `start` command will tell you where the config was written to, usually it's `/etc/controld/` but the path can differ based on your router platform. You can edit this config to get `ctrld` to route your DNS queries in highly advanced ways. Here is some relevant material to get you started:
- [Overview Blog Post](https://blog.controld.com/how-to-use-control-d-on-your-router/)
- [Example Configurations](https://github.com/Control-D-Inc/ctrld/wiki/Example-Configurations)
- [Full Documentation ](https://github.com/Control-D-Inc/ctrld/blob/main/docs/config.md)
- [Troubleshooting Guide](https://github.com/Control-D-Inc/ctrld/wiki/Troubleshooting-Guide)
Once you crafted your perfect config, simply run: `ctrld restart` in order for changes to kick in. To see what LAN clients `ctrld` discovered using DHCP leases file, arp, mDNS, PTR probes or hosts file, you can run the `ctrld clients list` command. This client data will be appended to DNS queries. Be mindful, that this only works when DNS-over-HTTPS (any version) is used. DOT and DOQ don't support this.
```
[2.7.0-RELEASE][root@pfSense.home.arpa]/root: ctrld clients list
+-----------------------------------------+------------+-------------------+------------+
| IP | Hostname | Mac | Discovered |
+-----------------------------------------+------------+-------------------+------------+
| 10.0.10.1 | | 00:50:56:9f:0e:84 | arp |
| 10.0.10.209 | pfSense | 00:0c:29:f5:a3:55 | arp,dhcp |
| 10.0.10.238 | Office-Box | 74:56:3c:44:eb:5e | arp,mdns |
| 10.0.10.245 | Test-W11 | | mdns |
| 127.0.0.1 | pfSense | 00:0c:29:f5:a3:55 | dhcp |
| ::1 | pfSense | 00:0c:29:f5:a3:55 | dhcp |
| 2607:f0c8:8000:8210:10a:e664:e855:1f61 | Office-Box | | mdns |
| 2607:f0c8:8000:8210:20c:29ff:fef5:a355 | pfSense | 00:0c:29:f5:a3:55 | dhcp |
| 2607:f0c8:8000:8210:2d11:e044:9e90:a14c | Test-W11 | | mdns |
| 2607:f0c8:8000:8210:4d66:459f:6b76:1c16 | Test-W11 | | mdns |
| 2607:f0c8:8000:8210:dcf4:5b74:4f7e:bd7f | Office-Box | | mdns |
| fe80::20c:29ff:fef5:a355 | pfSense | 00:0c:29:f5:a3:55 | dhcp |
| fe80::1554:c4ab:cfba:189 | Office-Box | | mdns |
| fe80::ab3f:8a1c:df6b:91b9 | Test-W11 | | mdns |
+-----------------------------------------+------------+-------------------+------------+
[2.7.0-RELEASE][root@pfSense.home.arpa]/root:
```
That's all there is to it. If you spot any issues with this guide, let us know.