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

docs: add v2.0.0 breaking changes documentation

Browse Source 
- Add comprehensive documentation for ctrld v2.0.0 breaking changes
- Document removal of automatic configuration for router/server platforms
- Provide step-by-step migration guide for affected users
- Include detailed dnsmasq and Windows Server configuration examples
- Update README.md to reflect v2.0.0 installer URLs and Go version requirements
- Remove references to automatic dnsmasq upstream configuration in README
This commit is contained in:
Cuong Manh Le
2025-10-02 20:52:10 +07:00
committed by Cuong Manh Le
parent f9d026334a
commit 7006e967e4
2 changed files with 141 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@@ -44,12 +44,12 @@ There are several ways to download and install `ctrld`.
The simplest way to download and install `ctrld` is to use the following installer command on any UNIX-like platform:
```shell
sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"'
sh -c 'sh -c "$(curl -sL https://api.controld.com/dl?version=2)"'
```
Windows user and prefer Powershell (who doesn't)? No problem, execute this command instead in administrative PowerShell:
```shell
(Invoke-WebRequest -Uri 'https://api.controld.com/dl/ps1' -UseBasicParsing).Content | Set-Content "$env:TEMPctrld_install.ps1"; Invoke-Expression "& '$env:TEMPctrld_install.ps1'"
(Invoke-WebRequest -Uri 'https://api.controld.com/dl/ps1?version=2' -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)
@@ -61,7 +61,7 @@ docker run -d --name=ctrld -p 127.0.0.1:53:53/tcp -p 127.0.0.1:53:53/udp control
Alternatively, if you know what you're doing you can download pre-compiled binaries from the [Releases](https://github.com/Control-D-Inc/ctrld/releases) section for the appropriate platform.
## Build
Lastly, you can build `ctrld` from source which requires `go1.21+`:
Lastly, you can build `ctrld` from source which requires `go1.23+`:
```shell
go build ./cmd/ctrld
@@ -111,7 +111,7 @@ Available Commands:
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
-v, --verbose count verbose log output, "-v" basic logging, "-vv" debug logging
--version version for ctrld
Use "ctrld [command] --help" for more information about a command.
@@ -179,7 +179,7 @@ Linux or Macos
`ctrld` can be configured in variety of different ways, which include: API, local config file or via cli launch args.
## API Based Auto Configuration
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.
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. This mode is used when the 1 liner installer command from the Control D onboarding guide is executed.
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.
@@ -196,7 +196,7 @@ 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 physical network interface will be updated to use the listener started by the service
- All DNS queries will be sent to the listener
## Manual Configuration

135
docs/v2.0.0-breaking-changes.md Normal file
View File

@@ -0,0 +1,135 @@
# ctrld v2.0.0 Breaking Changes
This document outlines the breaking changes introduced in ctrld v2.0.0 and provides migration guidance for affected users.
## Overview
ctrld v2.0.0 removes automatic configuration support for router and server platforms. This means ctrld will no longer perform "magic" configuration to automatically set itself up as an upstream for existing DNS software on these platforms.
## What's Changing
### Removed Platform Support
**Router Platforms:**
- ctrld will no longer automatically configure itself as an upstream for dnsmasq or other DNS software
- No automatic detection and configuration of router-specific DNS settings
**Server Platforms:**
- ctrld will no longer automatically configure Windows Server DNS forwarder settings
- No automatic integration with server DNS services
### What Remains Supported
**Desktop Platforms:**
- Windows Desktop
- macOS Desktop
- Linux Desktop
These platforms continue to receive full automatic configuration support.
## Stay on v1.x.x
ctrld v1.x.x will continue to be supported for router and server platforms:
- Important bug fixes (regression or security) will be cherry-picked to v1.x.x branch
- New features may still be added (but may take longer to implement)
- Long-term support for these platforms
## Migration Path for Router and Server Users
If you're currently using ctrld v1.x.x on router or server platforms, you need to follow these steps to migrate to v2.0.0:
### Step 1: Downloading ctrld v2 binary
To download ctrld v2.0.0, follow these steps:
Stop the current ctrld service:
```sh
ctrld stop
```
Or uninstall the current version:
```sh
ctrld uninstall
```
Download the appropriate binary for your platform: https://dl.controld.com/v2/linux-amd64/ctrld
> **Note**: Replace `amd64` with your platform architecture as needed.
Verify that the binary was updated correctly:
```sh
ctrld --version
```
Expected output:
```
ctrld version v2.0.0
```
### Step 2: Start ctrld without self-checking
You have two ways to start ctrld:
**Option A: Use Remote Configuration (Recommended)**
1. **Export your current configuration:**
- Copy the contents of your current `ctrld.toml` file
2. **Import to Control D Dashboard:**
- Log into your Control D dashboard
- Use the remote configuration feature to upload your configuration
3. **Start ctrld with remote config:**
```bash
sudo ctrld service start --cd=<your_uid> --skip_self_checks
```
> **Note**: You must use `ctrld service start` to prevent DNS being set automatically by ctrld.
**Option B: Use Local Configuration**
```bash
sudo ctrld service start --skip_self_checks
```
### Step 3: Configure DNS Software to Use ctrld as Upstream
**For dnsmasq users:**
1. Configure dnsmasq to use ctrld as upstream:
```bash
# Add to dnsmasq.conf
no-resolv
server=127.0.0.1#5354
add-mac
add-subnet=32,128
# Disable cache or set max-cache-ttl=0
# to prevent queries from caching
cache-size=0
# max-cache-ttl=0
```
2. Restart dnsmasq:
```bash
sudo service dnsmasq restart
```
**For Windows Server users:**
1. Configure DNS forwarder in Windows Server:
- Open DNS Manager
- Right-click on your server name
- Select "Properties" → "Forwarders" tab
- Add `<ctrld listener IP>` as a forwarder
## Getting Help
If you encounter any issues during migration or have questions about the v2.0.0 changes:
1. **File an issue:** [GitHub Issues](https://github.com/Control-D-Inc/ctrld/issues)
2. **Contact support:** Email help@controld.com.
3. **Check documentation:** Review the [configuration documentation](config.md) for detailed setup instructions
## Summary
While ctrld v2.0.0 removes automatic configuration for router and server platforms, it provides a more focused experience for desktop users while still allowing router/server users to continue using ctrld with manual configuration or by staying on the v1.x.x branch.
The migration path is designed to be straightforward, with multiple options to suit different use cases and technical comfort levels.