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

Update file README.md

Browse Source
This commit is contained in:
Yegor Sak
2025-04-04 19:40:27 +00:00
committed by Cuong Manh Le
parent 3937e885f0
commit 433a61d2ee
1 changed files with 113 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
README.md
View File

@@ -4,12 +4,12 @@
[![Go Reference](https://pkg.go.dev/badge/github.com/Control-D-Inc/ctrld.svg)](https://pkg.go.dev/github.com/Control-D-Inc/ctrld) [![Go Reference](https://pkg.go.dev/badge/github.com/Control-D-Inc/ctrld.svg)](https://pkg.go.dev/github.com/Control-D-Inc/ctrld)
[![Go Report Card](https://goreportcard.com/badge/github.com/Control-D-Inc/ctrld)](https://goreportcard.com/report/github.com/Control-D-Inc/ctrld) [![Go Report Card](https://goreportcard.com/badge/github.com/Control-D-Inc/ctrld)](https://goreportcard.com/report/github.com/Control-D-Inc/ctrld)
![ctrld spash image](/docs/ctrldsplash.png) ![ctrld splash image](/docs/ctrldsplash.png)
A highly configurable DNS forwarding proxy with support for: A highly configurable DNS forwarding proxy with support for:
- Multiple listeners for incoming queries - Multiple listeners for incoming queries
- Multiple upstreams with fallbacks - Multiple upstreams with fallbacks
- Multiple network policy driven DNS query steering - Multiple network policy driven DNS query steering (via network cidr, MAC address or FQDN)
- Policy driven domain based "split horizon" DNS with wildcard support - Policy driven domain based "split horizon" DNS with wildcard support
- Integrations with common router vendors and firmware - Integrations with common router vendors and firmware
- LAN client discovery via DHCP, mDNS, ARP, NDP, hosts file parsing - LAN client discovery via DHCP, mDNS, ARP, NDP, hosts file parsing
@@ -35,13 +35,29 @@ All DNS protocols are supported, including:
## OS Support ## OS Support
- Windows (386, amd64, arm) - Windows (386, amd64, arm)
- Mac (amd64, arm64) - Windows Server (386, amd64)
- MacOS (amd64, arm64)
- Linux (386, amd64, arm, mips) - Linux (386, amd64, arm, mips)
- FreeBSD - FreeBSD (386, amd64, arm)
- Common routers (See Router Mode below) - Common routers (See below)
### Supported Routers
You can run `ctrld` on any supported router. The list of supported routers and firmware includes:
- Asus Merlin
- DD-WRT
- Firewalla
- FreshTomato
- GL.iNet
- OpenWRT
- pfSense / OPNsense
- Synology
- Ubiquiti (UniFi, EdgeOS)
`ctrld` will attempt to interface with dnsmasq (or Windows Server) whenever possible and set itself as the upstream, while running on port 5354. On FreeBSD based OSes, `ctrld` will terminate dnsmasq and unbound in order to be able to listen on port 53 directly.
# Install # Install
There are several ways to download and install `ctrld. There are several ways to download and install `ctrld`.
## Quick Install ## Quick Install
The simplest way to download and install `ctrld` is to use the following installer command on any UNIX-like platform: The simplest way to download and install `ctrld` is to use the following installer command on any UNIX-like platform:
@@ -50,14 +66,14 @@ The simplest way to download and install `ctrld` is to use the following install
sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"' sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"'
``` ```
Windows user and prefer Powershell (who doesn't)? No problem, execute this command instead in administrative cmd: Windows user and prefer Powershell (who doesn't)? No problem, execute this command instead in administrative PowerShell:
```shell ```shell
powershell -Command "(Invoke-WebRequest -Uri 'https://api.controld.com/dl' -UseBasicParsing).Content | Set-Content 'ctrld_install.bat'" && ctrld_install.bat (Invoke-WebRequest -Uri 'https://api.controld.com/dl/ps1' -UseBasicParsing).Content | Set-Content "$env:TEMPctrld_install.ps1"; Invoke-Expression "& '$env:TEMPctrld_install.ps1'"
``` ```
Or you can pull and run a Docker container from [Docker Hub](https://hub.docker.com/r/controldns/ctrld) Or you can pull and run a Docker container from [Docker Hub](https://hub.docker.com/r/controldns/ctrld)
``` ```shell
$ docker pull controldns/ctrld docker run -d --name=ctrld -p 127.0.0.1:53:53/tcp -p 127.0.0.1:53:53/udp controldns/ctrld:latest
``` ```
## Download Manually ## Download Manually
@@ -67,20 +83,19 @@ Alternatively, if you know what you're doing you can download pre-compiled binar
Lastly, you can build `ctrld` from source which requires `go1.21+`: Lastly, you can build `ctrld` from source which requires `go1.21+`:
```shell ```shell
$ go build ./cmd/ctrld go build ./cmd/ctrld
``` ```
or or
```shell ```shell
$ go install github.com/Control-D-Inc/ctrld/cmd/ctrld@latest go install github.com/Control-D-Inc/ctrld/cmd/ctrld@latest
``` ```
or or
``` ```shell
$ docker build -t controldns/ctrld . -f docker/Dockerfile docker build -t controldns/ctrld . -f docker/Dockerfile
$ docker run -d --name=ctrld -p 53:53/tcp -p 53:53/udp controldns/ctrld --cd=RESOLVER_ID_GOES_HERE -vv
``` ```
@@ -101,15 +116,16 @@ Usage:
Available Commands: Available Commands:
run Run the DNS proxy server run Run the DNS proxy server
service Manage ctrld service
start Quick start service and configure DNS on interface start Quick start service and configure DNS on interface
stop Quick stop service and remove DNS from interface stop Quick stop service and remove DNS from interface
restart Restart the ctrld service restart Restart the ctrld service
reload Reload the ctrld service reload Reload the ctrld service
status Show status of the ctrld service status Show status of the ctrld service
uninstall Stop and uninstall the ctrld service uninstall Stop and uninstall the ctrld service
service Manage ctrld service
clients Manage clients clients Manage clients
upgrade Upgrading ctrld to latest version upgrade Upgrading ctrld to latest version
log Manage runtime debug logs
Flags: Flags:
-h, --help help for ctrld -h, --help help for ctrld
@@ -121,81 +137,99 @@ Use "ctrld [command] --help" for more information about a command.
``` ```
## Basic Run Mode ## Basic Run Mode
To start the server with default configuration, simply run: `./ctrld run`. This will create a generic `ctrld.toml` file in the **working directory** and start the application in foreground. This is the most basic way to run `ctrld`, in foreground mode. Unless you already have a config file, a default one will be generated.
1. Start the server
``` ### Command
$ sudo ./ctrld run
Windows (Admin Shell)
```shell
ctrld.exe run
``` ```
2. Run a test query using a DNS client, for example, `dig`: Linux or Macos
```shell
sudo ctrld run
```
You can then run a test query using a DNS client, for example, `dig`:
``` ```
$ dig verify.controld.com @127.0.0.1 +short $ dig verify.controld.com @127.0.0.1 +short
api.controld.com. api.controld.com.
147.185.34.1 147.185.34.1
``` ```
If `verify.controld.com` resolves, you're successfully using the default Control D upstream. From here, you can start editing the config file and go nuts with it. To enforce a new config, restart the server. If `verify.controld.com` resolves, you're successfully using the default Control D upstream. From here, you can start editing the config file that was generated. To enforce a new config, restart the server.
## Service Mode ## Service Mode
To run the application in service mode on any Windows, MacOS, Linux distibution or supported router, simply run: `./ctrld start` as system/root user. This will create a generic `ctrld.toml` file in the **user home** directory (on Windows) or `/etc/controld/` (almost everywhere else), start the system service, and configure the listener on the default network interface. Service will start on OS boot. This mode will run the application as a background system service on any Windows, MacOS, Linux, FreeBSD distribution or supported router. This will create a generic `ctrld.toml` file in the **C:\ControlD** directory (on Windows) or `/etc/controld/` (almost everywhere else), start the system service, and **configure the listener on all physical network interface**. Service will start on OS boot.
When Control D upstreams are used, `ctrld` willl [relay your network topology](https://docs.controld.com/docs/device-clients) to Control D (LAN IPs, MAC addresses, and hostnames), and you will be able to see your LAN devices in the web panel, view analytics and apply unique profiles to them. When Control D upstreams are used on a router type device, `ctrld` will [relay your network topology](https://docs.controld.com/docs/device-clients) to Control D (LAN IPs, MAC addresses, and hostnames), and you will be able to see your LAN devices in the web panel, view analytics and apply unique profiles to them.
In order to stop the service, and restore your DNS to original state, simply run `./ctrld stop`. If you wish to stop and uninstall the service permanently, run `./ctrld uninstall`. ### Command
Windows (Admin Shell)
```shell
ctrld.exe start
```
### Supported Routers Linux or Macos
You can run `ctrld` on any supported router, which will function similarly to the Service Mode mentioned above. The list of supported routers and firmware includes: ```
- Asus Merlin sudo ctrld start
- DD-WRT ```
- Firewalla
- FreshTomato
- GL.iNet
- OpenWRT
- pfSense / OPNsense
- Synology
- Ubiquiti (UniFi, EdgeOS)
`ctrld` will attempt to interface with dnsmasq whenever possible and set itself as the upstream, while running on port 5354. On FreeBSD based OSes, `ctrld` will terminate dnsmasq and unbound in order to be able to listen on port 53 directly. If `ctrld` is not in your system path (you installed it manually), you will need to run the above commands from the directory where you installed `ctrld`.
In order to stop the service, and restore your DNS to original state, simply run `ctrld stop`. If you wish to stop and uninstall the service permanently, run `ctrld uninstall`.
### Control D Auto Configuration ## Unmanaged Service Mode
Application can be started with a specific resolver config, instead of the default one. Simply supply your Resolver ID with a `--cd` flag, when using the `run` (foreground) or `start` (service) modes. This mode functions similarly to the "Service Mode" above except it will simply start a system service and the config defined listeners, but **will not make any changes to any network interfaces**. You can then set the `ctrld` listener(s) IP on the desired network interfaces manually.
The following command will start the application in foreground mode, using the free "p2" resolver, which blocks Ads & Trackers. ### Command
```shell Windows (Admin Shell)
./ctrld run --cd p2 ```shell
``` ctrld.exe service start
```
Alternatively, you can use your own personal Control D Device resolver, and start the application in service mode. Your resolver ID is displayed on the "Show Resolvers" screen for the relevant Control D Device. Linux or Macos
```shell
```shell sudo ctrld service start
./ctrld start --cd abcd1234 ```
```
Once you run the above commands (in service mode only), the following things will happen:
- You resolver configuration will be fetched from the API, and config file templated with the resolver data
- Application will start as a service, and keep running (even after reboot) until you run the `stop` or `uninstall` sub-commands
- Your default network interface will be updated to use the listener started by the service
- All OS DNS queries will be sent to the listener
# Configuration # Configuration
See [Configuration Docs](docs/config.md). `ctrld` can be configured in variety of different ways, which include: API, local config file or via cli launch args.
## Example ## API Based Auto Configuration
- Start `listener.0` on 127.0.0.1:53 Application can be started with a specific Control D resolver config, instead of the default one. Simply supply your Resolver ID with a `--cd` flag, when using the `start` (service) mode. In this mode, the application will automatically choose a non-conflicting IP and/or port and configure itself as the upstream to whatever process is running on port 53 (like dnsmasq or Windows DNS Server). This mode is used when the 1 liner installer command from the Control D onboarding guide is executed.
- Accept queries from any source address
- Send all queries to `upstream.0` via DoH protocol
### Default Config The following command will use your own personal Control D Device resolver, and start the application in service mode. Your resolver ID is displayed on the "Show Resolvers" screen for the relevant Control D Endpoint.
Windows (Admin Shell)
```shell
ctrld.exe start --cd abcd1234
```
Linux or Macos
```shell
sudo ctrld start --cd abcd1234
```
Once you run the above command, the following things will happen:
- You resolver configuration will be fetched from the API, and config file templated with the resolver data
- Application will start as a service, and keep running (even after reboot) until you run the `stop` or `uninstall` sub-commands
- All physical network interface will be updated to use the listener started by the service or dnsmasq upstream will be switched to `ctrld`
- All DNS queries will be sent to the listener
## Manual Configuration
`ctrld` is entirely config driven and can be configured in many different ways, please see [Configuration Docs](docs/config.md).
### Example
```toml ```toml
[listener] [listener]
[listener.0] [listener.0]
ip = "" ip = '0.0.0.0'
port = 0 port = 53
restricted = false
[network] [network]
@@ -203,10 +237,6 @@ See [Configuration Docs](docs/config.md).
cidrs = ["0.0.0.0/0"] cidrs = ["0.0.0.0/0"]
name = "Network 0" name = "Network 0"
[service]
log_level = "info"
log_path = ""
[upstream] [upstream]
[upstream.0] [upstream.0]
@@ -215,28 +245,26 @@ See [Configuration Docs](docs/config.md).
name = "Control D - Anti-Malware" name = "Control D - Anti-Malware"
timeout = 5000 timeout = 5000
type = "doh" type = "doh"
[upstream.1]
bootstrap_ip = "76.76.2.11"
endpoint = "p2.freedns.controld.com"
name = "Control D - No Ads"
timeout = 3000
type = "doq"
``` ```
`ctrld` will pick a working config for `listener.0` then writing the default config to disk for the first run. The above basic config will:
- Start listener on 0.0.0.0:53
- Accept queries from any source address
- Send all queries to `https://freedns.controld.com/p1` using DoH protocol
## Advanced Configuration ## CLI Args
The above is the most basic example, which will work out of the box. If you're looking to do advanced configurations using policies, see [Configuration Docs](docs/config.md) for complete documentation of the config file. If you're unable to use a config file, `ctrld` can be be supplied with basic configuration via launch arguments, in [Ephemeral Mode](docs/ephemeral_mode.md).
You can also supply configuration via launch argeuments, in [Ephemeral Mode](docs/ephemeral_mode.md). ### Example
```
ctrld run --listen=127.0.0.1:53 --primary_upstream=https://freedns.controld.com/p2 --secondary_upstream=10.0.10.1:53 --domains=*.company.int,very-secure.local --log /path/to/log.log
```
The above will start a foreground process and:
- Listen on `127.0.0.1:53` for DNS queries
- Forward all queries to `https://freedns.controld.com/p2` using DoH protocol, while...
- Excluding `*.company.int` and `very-secure.local` matching queries, that are forwarded to `10.0.10.1:53`
- Write a debug log to `/path/to/log.log`
## Contributing ## Contributing
See [Contribution Guideline](./docs/contributing.md) See [Contribution Guideline](./docs/contributing.md)
## Roadmap
The following functionality is on the roadmap and will be available in future releases.
- DNS intercept mode
- Direct listener mode
- Support for more routers (let us know which ones)