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