mirror of
https://github.com/Control-D-Inc/ctrld.git
synced 2026-03-13 10:26:06 +00:00
7006e967e4
- 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
136 lines
4.0 KiB
Markdown
136 lines
4.0 KiB
Markdown
# 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.
|