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

BIND9 9.20 Support Implementation Guide

Overview

This document describes the ansible-bind9-role strategy for BIND9 9.20+ support through a dedicated version branch.

The current implementation uses branch-level compatibility boundaries instead of runtime version detection. The main branch targets BIND9 9.18.x LTS, while the 9.20 branch targets BIND9 9.20+ feature releases.

Architecture

Branch-Based Support Strategy

The role uses branch-only support boundaries:

1. main branch: BIND9 9.18.x LTS support for production-stable deployments.
2. 9.20 branch: BIND9 9.20+ feature-release support with version-specific templates, grammar data, tests, and documentation.

The role does not currently detect BIND9 versions at runtime and does not use runtime version conditionals in templates. Each branch is expected to be tested against the BIND9 series it supports.

This approach is preferred because:

• compatibility boundaries are clear for users and maintainers;
• templates avoid cross-version conditional complexity;
• each branch can evolve with the grammar and package behavior of its target BIND9 series;
• generated configuration does not silently change based on the installed package version.

Branch Structure

main                    # BIND9 9.18.x LTS support
│
└─ 9.20                 # BIND9 9.20+ feature-release support
   └─ feature/*          # Short-lived feature branches targeting 9.20

Implementation Details

1. Task Flow

1. Install the configured BIND9 packages from bind9_packages.
2. Ensure backup and logging directories exist when enabled or configured.
3. Render configured BIND9 files through named.conf.generator.j2.
4. Validate the generated configuration with named-checkconf -z.
5. Restore backed-up configuration files if validation fails.
6. Start and enable the named service.

There is no runtime bind9_version fact in this flow.

2. Meta/Argument Specs Updates

The meta/argument_specs.yml file documents the public role inputs for the current branch. It must not document runtime-only variables that the role does not set or consume.

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 in each version branch should be audited for the BIND9 series targeted by that branch. 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 9.20 branch should handle this through:

1. Documentation: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md
2. Branch-specific templates: Templates on the 9.20 branch omit 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
• Runtime version detection if branch-per-version maintenance becomes insufficient
• Template conditionals only if a future design intentionally supports multiple BIND9 series from one branch
• 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