# BIND9 9.18 to 9.20 Migration Guide

## Overview

This guide provides step-by-step instructions for migrating BIND9 configurations from version 9.18.x (LTS) to version 9.20.x. 

**Important:** BIND9 9.20 introduces 44 breaking changes. Before upgrading, carefully review this guide and test in a development environment.

For detailed technical differences between versions, see [BIND9 Version Differences](BIND_VERSION_DIFFERENCES.md).

## Table of Contents

1. [Pre-Migration Planning](#pre-migration-planning)
2. [Breaking Changes Summary](#breaking-changes-summary)
3. [Migration Steps](#migration-steps)
4. [Configuration Examples](#configuration-examples)
5. [Role-Specific Changes](#role-specific-changes)
6. [Testing Recommendations](#testing-recommendations)
7. [Rollback Procedure](#rollback-procedure)

## Pre-Migration Planning

### Check Your Configuration

Before upgrading, identify which BIND9 options your configuration uses:

```bash
# Check for options that will be removed
named-checkconf -p /etc/bind/named.conf | \
  grep -E "alt-transfer-source|auto-dnssec|coresize|datasize|glue-cache"
```

### Create Backups

```bash
# Backup all BIND configuration
cp -r /etc/bind /data/backup/bind.9.18.backup

# Backup BIND data
cp -r /var/lib/bind /data/backup/bind.9.18.data
cp -r /var/cache/bind /data/backup/bind.9.18.cache
```

### Review Version Support

This Ansible role is designed for BIND9 9.18.x. When upgrading to 9.20:

- The main branch will continue supporting 9.18.x
- A separate `9.20` branch will provide 9.20-specific templates and configurations
- Use the appropriate branch for your target BIND9 version

## Breaking Changes Summary

The following options are **removed** in BIND9 9.20 and will cause `named` to fail if present:

### Global Options (9.20 Breaking Changes)

- `alt-transfer-source` - Use TLS-based transfers instead
- `alt-transfer-source-v6` - Use TLS-based transfers instead
- `auto-dnssec` - DNSSEC management is automatic in 9.20
- `coresize` - System resource limits; use OS-level controls
- `datasize` - System resource limits; use OS-level controls
- `dscp` - Use TLS configuration instead
- `files` - System resource limits; use OS-level controls
- `glue-cache` - Always enabled in 9.20
- `heartbeat-interval` - Zone transfer changes
- `keep-response-order` - Always enabled in 9.20
- `lock-file` - Use system lock controls
- `maxz-zone-ttl` - Use `max-zone-ttl` instead (per-zone option)
- `parent-registration-delay` - Zone-delegation monitoring removed
- `parental-agents` - Use `primaries` statement with DNSSEC
- `primaries` - Replaced with enhanced syntax (see below)
- `random-device` - System entropy handling improved
- `recurse-ing-file` - Renamed to `recursing-file`
- `reserved-sockets` - Automatic in 9.20
- `resolver-nonbackoff-tries` - Resolver behavior changed
- `resolver-retry-interval` - Resolver behavior changed
- `reuse` - Always enabled in 9.20
- `root-delegation-only` - Removed; not needed in 9.20
- `stacksize` - System resource limits; use OS-level controls
- `suppress-initial-notify` - NOTIFY behavior changed
- `tkey-dhkey` - Use modern TLS/DNSSEC instead
- `tkey-gssapi-credential` - Use TSIG + TLS instead

### Zone-Type Specific Breaking Changes

#### All Zone Types
- `delegation-only` - Removed; use zone type constraints instead
- `alt-transfer-source[v6]` - Use TLS configuration
- `auto-dnssec` - DNSSEC management changes
- `use-alt-transfer-source` - Use TLS configuration

## Migration Steps

### Step 1: Identify Configuration Changes

Review your current `bind9_*_config` variables for any deprecated options:

```yaml
# Search your inventory and host_vars for these patterns
bind9_default_config:
  - name: named.conf.options
    options:
      # These options must be removed or replaced:
      # - alt_transfer_source
      # - auto_dnssec  
      # - glue_cache
      # ... etc
```

### Step 2: Update Ansible Variables

Replace deprecated options in your Ansible configuration:

```yaml
# BEFORE (BIND9 9.18)
bind9_default_config:
  - name: named.conf.options
    options:
      alt_transfer_source: 10.0.1.1
      glue_cache: yes
      keep_response_order: yes

# AFTER (BIND9 9.20)
bind9_default_config:
  - name: named.conf.options
    options:
      # alt_transfer_source removed - use TLS
      # glue_cache removed - always enabled
      # keep_response_order removed - always enabled
      # Instead configure TLS for transfers
      http:
        preference: https
```

### Step 3: Update Primaries Configuration

The `primaries` statement syntax has changed:

```yaml
# BEFORE (BIND9 9.18)
bind9_host_config:
  - name: named.conf.view
    view:
      - name: internal
        zone:
          - name: example.com
            type: secondary
            primaries:
              - 192.0.2.1
              - 192.0.2.2

# AFTER (BIND9 9.20)
bind9_host_config:
  - name: named.conf.view
    view:
      - name: internal
        zone:
          - name: example.com
            type: secondary
            primaries:
              - address: 192.0.2.1
              - address: 192.0.2.2
              # Optional: TLS configuration
              # tls: cert-name
              # source: 10.0.1.1
              # source_v6: "2001:db8::1"
```

### Step 4: Validate Configuration

Before deploying to production:

```bash
# Validate syntax
named-checkconf /etc/bind/named.conf

# Check for deprecated options
grep -r "alt-transfer-source\|auto-dnssec\|glue-cache" /etc/bind/
```

### Step 5: Test Zone Operations

```bash
# Test zone transfers
dig @ns1.example.com example.com AXFR

# Test DNSSEC validation
dig @ns1.example.com example.com +dnssec

# Check BIND logs
journalctl -u bind9 -f
```

## Configuration Examples

### Example 1: Simple Secondary Zone Migration

**BIND9 9.18 Configuration:**

```yaml
bind9_default_config:
  - name: named.conf.view
    view:
      - name: "default"
        recursion: yes
        zone:
          - name: "example.com"
            type: "secondary"
            file: "/var/lib/bind/example.com.zone"
            primaries:
              - 192.0.2.1
              - 192.0.2.2
            alt_transfer_source: 10.0.1.1
            alt_transfer_source_v6: "2001:db8::1"
            allow_transfer:
              - 10.0.2.0/24
```

**BIND9 9.20 Configuration:**

```yaml
bind9_default_config:
  - name: named.conf.view
    view:
      - name: "default"
        recursion: yes
        zone:
          - name: "example.com"
            type: "secondary"
            file: "/var/lib/bind/example.com.zone"
            primaries:
              - address: 192.0.2.1
              - address: 192.0.2.2
            # alt_transfer_source removed - use TLS
            # Configuration now uses single source per address:
            allow_transfer:
              - 10.0.2.0/24
```

### Example 2: DNSSEC Configuration Migration

**BIND9 9.18 Configuration:**

```yaml
bind9_default_config:
  - name: named.conf.options
    options:
      dnssec_policy: default
  - name: named.conf.zone
    zone:
      - name: "example.com"
        type: "primary"
        file: "/var/lib/bind/example.com.zone"
        auto_dnssec: maintain
        inline_signing: yes
```

**BIND9 9.20 Configuration:**

```yaml
bind9_default_config:
  - name: named.conf.options
    options:
      dnssec_policy: default
  - name: named.conf.zone
    zone:
      - name: "example.com"
        type: "primary"
        file: "/var/lib/bind/example.com.zone"
        # auto_dnssec removed - DNSSEC management is automatic
        dnssec_policy: default  # Explicitly set policy
        inline_signing: yes     # Still supported
```

## Role-Specific Changes

### Branch Selection

When using this Ansible role with BIND9 9.20, you have two options:

#### Option 1: Use Main Branch (Recommended for 9.18)

```bash
# Use main branch for BIND9 9.18
ansible-galaxy install daniel.ansible-bind9-role
```

#### Option 2: Use 9.20 Branch (When Available)

```bash
# Clone the 9.20 branch for BIND9 9.20 support
git clone --branch 9.20 https://git.valid.dk/daniel/ansible-bind9-role.git
```

### Template Variables

No Ansible variable names change between versions. However, the **values** for some variables may need adjustment:

```yaml
# Variable names stay the same (kebab-case → snake_case)
# Example: "alt-transfer-source" → "alt_transfer_source"
# Simply remove deprecated variables - they will be ignored

bind9_default_config:
  - name: named.conf.options
    options:
      # Remove these:
      # alt_transfer_source: ...
      # auto_dnssec: ...
      # glue_cache: ...
      
      # These still work:
      dnssec_validation: yes
      recursion: yes
      allow_query:
        - any
```

### DNSSEC Policy Changes

BIND9 9.20 improves DNSSEC handling:

```yaml
# Both versions support dnssec_policy
bind9_default_config:
  - name: named.conf.dnssec-policy
    dnssec_policy:
      - name: default
        keys:
          - lifetime: 3600
            algorithm: ecdsap256sha256
            role:
              - ksk
              - zsk
        nsec3param:
          iterations: 0
          optout: no
          salt_length: 32
```

## Testing Recommendations

### Test Environment Setup

Create a test playbook to validate migration:

```yaml
---
- hosts: test_servers
  vars:
    bind9_version: "9.20"  # Document version being tested
  
  tasks:
    - name: Apply BIND9 9.20 configuration
      include_role:
        name: ansible-bind9-role
      
    - name: Validate configuration
      command: named-checkconf /etc/bind/named.conf
      register: config_check
      failed_when: config_check.rc != 0
    
    - name: Test zone transfers
      command: >
        dig @localhost example.com AXFR
      register: zone_transfer
      
    - name: Test DNSSEC validation
      command: >
        dig @localhost example.com +dnssec
      register: dnssec_test
      
    - name: Check BIND status
      systemd:
        name: bind9
        state: started
      register: bind_status
```

### Validation Checklist

- [ ] Configuration syntax valid (`named-checkconf`)
- [ ] BIND9 service starts without errors
- [ ] All zones load successfully
- [ ] Zone transfers complete successfully
- [ ] Queries resolve correctly
- [ ] DNSSEC validation works
- [ ] Secondary zones receive updates
- [ ] No errors in BIND logs
- [ ] Performance is acceptable

## Rollback Procedure

If issues occur after migration:

### Immediate Rollback

```bash
# Stop BIND9
systemctl stop bind9

# Restore configuration backup
rm -rf /etc/bind
cp -r /data/backup/bind.9.18.backup /etc/bind

# Restore zone files
rm -rf /var/lib/bind
cp -r /data/backup/bind.9.18.data /var/lib/bind
cp -r /data/backup/bind.9.18.cache /var/cache/bind

# Restore BIND9 package
apt-get install --reinstall bind9=1:9.18.44-1+0~20240101.3+debian~bullseye+1+sury+1

# Start BIND9
systemctl start bind9

# Verify
systemctl status bind9
dig @localhost example.com
```

### Using Ansible Rollback

```yaml
---
- hosts: bind_servers
  tasks:
    - name: Restore BIND9 9.18 package
      apt:
        name: bind9=1:9.18.44-1+0~20240101.3+debian~bullseye+1+sury+1
        state: present
    
    - name: Restore configuration from backup
      synchronize:
        src: /data/backup/bind.9.18.backup/
        dest: /etc/bind/
        delete: yes
        mode: push
    
    - name: Restart BIND9
      systemd:
        name: bind9
        state: restarted
        daemon_reload: yes
```

## Additional Resources

- [BIND9 Version Differences](BIND_VERSION_DIFFERENCES.md) - Technical comparison
- [ISC BIND9 Release Notes](https://www.isc.org/bind/) - Official documentation
- [BIND9 9.20 Features](https://bind.readthedocs.io/en/latest/) - Feature details
- [Role Configuration Reference](CONFIGURATION_GRAMMAR.md) - Ansible role documentation

## Getting Help

For issues during migration:

1. Check [BIND9 Version Differences](BIND_VERSION_DIFFERENCES.md) for specific option changes
2. Review BIND9 logs: `journalctl -u bind9 -n 100`
3. Validate configuration: `named-checkconf /etc/bind/named.conf`
4. Test in development environment first
5. Document any custom options that need special handling

## Version Support Timeline

- **BIND9 9.18.x (LTS)**: Supported until September 2026
  - This Ansible role's current focus
  - Main branch targets 9.18.x configurations
  
- **BIND9 9.20.x**: Available now
  - Future branch (`9.20`) being prepared
  - Plan migration during non-critical periods

- **BIND9 9.22.x**: Coming in 2026
  - Further breaking changes expected
  - Will require additional migration steps

Plan upgrades within your maintenance windows and test thoroughly before production deployment.