ctrld/docs/v2.0.0-breaking-changes.md

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:

ctrld stop

Or uninstall the current version:

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:

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:

   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

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:

   # 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:

   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
2. Contact support: Email help@controld.com.
3. Check documentation: Review the configuration documentation 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.