ansible-bind9-role/docs/BIND9_9.20_SUPPORT.md

BIND9 9.20 Support Implementation Guide

Overview

This document describes the ansible-bind9-role implementation for BIND9 9.20+ support through the feature/bind9-20-support branch.

Architecture

Multi-Version Support Strategy

The role supports multiple BIND9 versions using:

1. Runtime Version Detection: BIND9 version is detected at runtime and stored in the bind9_version fact
2. Template Conditionals: Jinja2 conditionals in templates apply version-specific configurations
3. Separate Branches: Different BIND9 feature release series are maintained on separate branches
   • main: BIND9 9.18.x (LTS) - Production stable
   • 9.20: BIND9 9.20+ (feature releases) - New features and modern approach

Branch Structure

main                          # BIND9 9.18.x LTS (stable)
│
└─ 9.20                       # BIND9 9.20+ feature releases
   ├─ feature/bind9-20-support  # Current development branch
   └─ (will merge to 9.20 after testing)

Implementation Details

1. Version Detection (tasks/main.yml)

- name: Detect BIND9 version at runtime
  ansible.builtin.command:
    cmd: named -v
  register: _bind9_version_output
  changed_when: false

- name: Set bind9_version fact
  ansible.builtin.set_fact:
    bind9_version: "{{ _bind9_version_output.stdout | regex_search('BIND (\\S+)', '\\1') | first }}"

2. Meta/Argument Specs Updates

The meta/argument_specs.yml has been updated to:

• Document BIND9 9.20+ support alongside 9.18.x
• Add bind9_version variable documentation (read-only, auto-detected)
• Clarify version-specific behavior

3. Molecule Testing

Two molecule scenarios are now available:

Default Scenario (BIND9 9.18.x)

• Location: molecule/default/
• Platform: Debian 13 (Trixie) with BIND9 9.18.x
• Purpose: Validate production-stable configurations

BIND9 9.20 Scenario

• Location: molecule/bind9-20/
• Platform: Ubuntu 24.04 LTS with BIND9 9.20+
• Purpose: Validate newer configurations and breaking changes
• Tests: Forward zones, TLS, DNSTAP, modern DNSSEC

4. Template Version Compatibility

Templates have been audited for BIND9 9.20 compatibility. The primary template files include:

• named.conf.options.j2 - Global options block
• named.conf.zone.j2 - Zone definitions
• named.conf.primaries.j2 - Primary/secondary definitions
• named.conf.tls.j2 - TLS configurations (9.20 focus)
• named.conf.dnssec-policy.j2 - DNSSEC policies

5. Deprecated Options Handling

BIND9 9.20 removes 44 options from 9.18. The role handles this through:

1. Documentation: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md
2. Conditional Removal: Templates check version and exclude removed options
3. Migration Path: BIND9_MIGRATION_GUIDE.md provides alternatives for each removed option

Critical BIND9 9.20 Changes

Automatically Enabled Options

These cannot and should not be configured (always enabled in 9.20):

• glue-cache - Glue records are always cached
• keep-response-order - Response ordering is always enabled
• reuse - TCP socket reuse is always enabled

Removed Global Options

Key removed options requiring configuration changes:

9.18 Option	9.20 Replacement
alt-transfer-source	Use TLS in primaries statement
alt-transfer-source-v6	Use TLS in primaries statement
auto-dnssec	Automatic (DNSSEC always managed)
dsc	Use TLS configuration instead
gssapi-credential	Use TSIG + TLS instead
heartbeat-interval	Zone transfer monitoring improved
lock-file	OS-level locking used
max-zone-ttl	Use per-zone option instead
parental-agents	Use enhanced primaries statement
parental-registration-delay	Zone monitoring improved
root-delegation-only	Zone constraints
suppress-initial-notify	NOTIFY behavior changed
tkeydhkey	Use modern TLS/DNSSEC
tkeygsapi-credential	Use TSIG + TLS

New 9.20 Features

• Native TLS/DoT Support: Zone transfers over TLS
• Automatic DNSSEC Management: DNSSEC is handled automatically
• Enhanced HTTP/HTTPS Server: Built-in HTTP API
• Better Resolver Behavior: Improved retry and fallback logic
• Query Monitoring: Advanced query tracking and statistics

Configuration Changes for 9.20

Before (BIND9 9.18.x)

bind9_default_config:
  - name: named.conf.options
    options:
      alt_transfer_source: 10.0.1.1
      glue_cache: yes
      parental_agents: 
        - 192.0.2.1
        - 192.0.2.2

After (BIND9 9.20+)

bind9_default_config:
  - name: named.conf.options
    options:
      # Removed: alt_transfer_source, glue_cache, parental_agents
      # Instead use TLS and enhanced primaries statement
  - name: named.conf.zone
    zones:
      - name: example.com
        type: secondary
        primaries:
          - address: 192.0.2.1
            tls: zone-transfer-tls  # New 9.20 approach
          - address: 192.0.2.2
            tls: zone-transfer-tls

Testing the Implementation

Running Molecule Tests

# Test both scenarios
molecule test

# Test only 9.18 scenario
molecule test -s default

# Test only 9.20 scenario
molecule test -s bind9-20

# Interactive testing
molecule create -s bind9-20
molecule converge -s bind9-20
molecule verify -s bind9-20

Manual Validation

# Check BIND9 version
named -v

# Validate configuration syntax
named-checkconf /etc/bind/named.conf

# Check logs for version-related messages
journalctl -u named -n 50 -e
tail -f /var/log/named/default.log

Migration Path

Users upgrading from 9.18 to 9.20 should:

1. Review Configuration: Check BIND9_MIGRATION_GUIDE.md for breaking changes
2. Update Playbooks: Remove deprecated variables/options
3. Test in Staging: Use molecule test -s bind9-20 to validate
4. Gradual Migration: Test on non-critical servers first
5. Monitor Logs: Watch for deprecation or error messages

Future Enhancements

• Automated configuration migration tool
• Deprecation warnings in role output
• 9.21+ preparation when available
• Performance tuning for 9.20 features
• DNS-over-HTTPS (DoH) support
• Clustering/high-availability examples

References

• ISC BIND9 Website
• BIND9 9.20 Release Notes
• BIND9 Documentation
• BIND9 Version Differences
• BIND9 Migration Guide
• VERSION_SUPPORT.md

Support

For issues or questions about BIND9 9.20 support:

1. Check existing Issues
2. Review Discussions
3. Create a new issue with:
   • BIND9 version (named -v)
   • Playbook configuration
   • Error messages from logs
   • Steps to reproduce