ansible-bind9-role/docs/BIND9_MIGRATION_GUIDE.md

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.

Table of Contents

1. Pre-Migration Planning
2. Breaking Changes Summary
3. Migration Steps
4. Configuration Examples
5. Role-Specific Changes
6. Testing Recommendations
7. Rollback Procedure

Pre-Migration Planning

Check Your Configuration

Before upgrading, identify which BIND9 options your configuration uses:

# 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

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

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

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

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

# 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

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

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:

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:

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:

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)

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

Option 2: Use 9.20 Branch (When Available)

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

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

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

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

# 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

---
- 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 - Technical comparison
• ISC BIND9 Release Notes - Official documentation
• BIND9 9.20 Features - Feature details
• Role Configuration Reference - Ansible role documentation

Getting Help

For issues during migration:

1. Check BIND9 Version Differences 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.