daniel/ansible-bind9-role
1
0
Fork 0
Code Issues 3 Pull Requests 1 Actions Releases Wiki Activity

feat: Add BIND9 9.20 molecule scenario and support documentation
Some checks failed
Test / Lint (push) Successful in 15s
Details
Test / Lint (pull_request) Successful in 15s
Details
Test / Test (push) Has been skipped
Details
Test / Test (pull_request) Failing after 34s
Details

Browse Source 
- Added molecule/bind9-20 scenario for testing BIND9 9.20+ compatibility
  - molecule.yml: Ubuntu 24.04 platform configuration
  - converge.yml: Complete 9.20 configuration with TLS, DNSTAP, and modern features
  - verify.yml: Comprehensive test cases for 9.20 features
  - collections.yml: Required Ansible collections
  - prepare.yml: Pre-test environment setup
  - README.md: Scenario documentation with breaking changes reference

- Added docs/BIND9_9.20_SUPPORT.md implementation guide
  - Architecture overview for multi-version support
  - Runtime version detection strategy
  - Configuration changes and examples
  - Migration path for upgrading users
  - Feature highlights for BIND9 9.20

- Updated meta/argument_specs.yml
  - Added multi-version support documentation
  - Documented bind9_version variable (read-only, auto-detected)
  - Clarified supported BIND9 versions (9.18.x LTS and 9.20+)

These changes establish the feature/bind9-20-support branch as the development
path for BIND9 9.20+ support, separate from the main branch's 9.18.x focus.

Closes #9: Create feature/bind9-20-support branch with 9.20 templates
This commit is contained in:
Daniel Akulenok
2026-02-07 23:58:31 +01:00
parent 0eff38f202
commit 528caeddeb
8 changed files with 608 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
docs/BIND9_9.20_SUPPORT.md Normal file
View File

@@ -0,0 +1,231 @@
# 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)
```yaml
- 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)
```yaml
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+)
```yaml
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
```bash
# 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
```bash
# 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](https://www.isc.org/bind/)
- [BIND9 9.20 Release Notes](https://www.isc.org/download/news/)
- [BIND9 Documentation](https://bind9.readthedocs.io/)
- [BIND9 Version Differences](../../docs/BIND_VERSION_DIFFERENCES.md)
- [BIND9 Migration Guide](../../docs/BIND9_MIGRATION_GUIDE.md)
- [VERSION_SUPPORT.md](../../docs/VERSION_SUPPORT.md)
## Support
For issues or questions about BIND9 9.20 support:
1. Check existing [Issues](https://git.valid.dk/daniel/ansible-bind9-role/issues)
2. Review [Discussions](https://git.valid.dk/daniel/ansible-bind9-role/discussions)
3. Create a new issue with:
- BIND9 version (`named -v`)
- Playbook configuration
- Error messages from logs
- Steps to reproduce

11
meta/argument_specs.yml
View File

@@ -2,6 +2,10 @@
argument_specs:
main:
short_description: The main entry point for the bind9 role.
description:
- Configures BIND9 DNS server on Debian-based systems.
- "Supported BIND9 versions: 9.18.x (LTS), 9.20+ (feature releases)"
- Version detection is automatic at runtime.
options:
bind9_config:
type: list
@@ -53,3 +57,10 @@ argument_specs:
bind9_backup_dir:
type: str
description: Directory for backups.
bind9_version:
type: str
description:
- BIND9 version detected at runtime (read-only, set automatically).
- "Format: X.Y.Z (e.g., 9.18.44, 9.20.18)"
- Used by templates to apply version-specific configurations.
- Users should not set this variable directly.

108
molecule/bind9-20/README.md Normal file
View File

@@ -0,0 +1,108 @@
# BIND9 9.20 Molecule Scenario
This Molecule scenario validates the ansible-bind9-role with BIND9 9.20 and later feature releases.
## Purpose
- Tests role compatibility with BIND9 9.20+ which includes 44 breaking changes from 9.18.x
- Validates version-specific templates and configurations
- Ensures configuration syntax is correct for newer BIND9 versions
- Documents 9.20-specific configuration patterns
## Platform
- **Base Image**: Ubuntu 24.04 LTS (docker.io/library/ubuntu:24.04)
- **BIND9 Version**: 9.20.x or later (as available in Ubuntu 24.04 repositories)
## Notable BIND9 9.20 Changes
Key breaking changes in this scenario:
1. **Automatic Options**: The following options are automatically enabled in 9.20 and should not be configured:
- `glue-cache` - Always enabled
- `keep-response-order` - Always enabled
- `reuse` - Always enabled
- `recursion-enabled` - Always enabled
2. **Removed Options**: These options are no longer supported in 9.20:
- `alt-transfer-source` - Use TLS instead
- `alt-transfer-source-v6` - Use TLS instead
- `auto-dnssec` - DNSSEC management is automatic
- `dsc` - Use TLS configuration instead
- `gssapi-credential` - Use TSIG + TLS instead
- `heartbeat-interval` - Zone transfer monitoring changed
- `lock-file` - OS-level locking is used
- `root-delegation-only` - Use zone constraints instead
3. **Enhanced Features**:
- Improved TLS/DoT support for zone transfers
- Native DNSSEC management
- Better resolver behavior and retry logic
- Native HTTP/HTTPS server capabilities
## Configuration Features Tested
- **DNS Forwarding**: Forward zones with TLS-based forwarders (DoT)
- **Query Logging**: Detailed query and response logging
- **DNSTAP**: DNS packet capture for forensics
- **TLS Configuration**: Modern TLS configurations for zone transfers
- **Recursion**: Proper recursion configuration with ACLs
- **DNSSEC Validation**: Modern DNSSEC validation approach
## Testing
To run this scenario:
```bash
# Test with this specific scenario
cd /path/to/ansible-bind9-role
molecule test -s bind9-20
# Or specific steps
molecule create -s bind9-20
molecule converge -s bind9-20
molecule verify -s bind9-20
molecule destroy -s bind9-20
```
## Expected Results
- BIND9 service starts successfully
- Configuration files are generated without errors
- DNS forwarding works correctly
- Named-checkconf validates the configuration
- All log channels are operational
- TLS connections are established for forwarders
## Troubleshooting
### BIND9 Package Not Available
If BIND9 9.20 is not available in Ubuntu 24.04 repositories, you may need to:
1. Build from source using the upstream ISC BIND9 repository
2. Use a different base image with more recent BIND9 packages
3. Add a custom APT repository with backported packages
### Configuration Syntax Errors
Review `/etc/bind/named.conf` using:
```bash
named-checkconf /etc/bind/named.conf
```
Check logs at `/var/log/named/default.log` for specific error messages.
## Future Updates
- [ ] Add support for BIND9 9.20 DNS-over-HTTPS (DoH)
- [ ] Test with BIND9 9.22+ when released
- [ ] Validate performance improvements
- [ ] Test clustering/replication features
## References
- [BIND9 Documentation](https://bind9.readthedocs.io/)
- [BIND9 9.20 Release Notes](https://www.isc.org/bind/)
- [DNS-over-TLS (DoT) RFC 7858](https://tools.ietf.org/html/rfc7858)

4
molecule/bind9-20/collections.yml Normal file
View File

@@ -0,0 +1,4 @@
---
collections:
- ansible.posix
- community.general

122
molecule/bind9-20/converge.yml Normal file
View File

@@ -0,0 +1,122 @@
---
- name: Converge
hosts: all
tasks:
- name: Create log directory for BIND
ansible.builtin.file:
path: /var/log/named
state: directory
mode: '0755'
owner: bind
group: bind
- name: Include bind9 role
ansible.builtin.include_role:
name: ../../../ansible-bind9-role # noqa: role-name[path]
vars:
bind9_backup_config: false
# BIND9 9.20+ configuration with version-specific options
bind9_host_config:
- name: named.conf.options
options:
directory: "{{ bind9_working_directory }}"
recursion: true
allow_query:
- any
allow_recursion:
- 10.0.0.0/8
- 192.168.0.0/16
- 172.16.0.0/12
- localhost
- localnets
forwarders:
- address: 91.239.100.100
tls: censurfridns-anycast
- address: 89.233.43.71
tls: censurfridns-unicast
forward: first
dnssec_validation: auto
dnstap:
- type: auth
- type: resolver
log: query
- type: client
log: response
dnstap_output:
output_type: file
output_file: /var/log/named/dnstap.log
size: 20m
versions: 3
suffix: increment
dnstap_identity: dns-server-01
dnstap_version: 9.20
# Note: BIND9 9.20 automatically enables glue-cache, keep-response-order, reuse
# These options are removed in 9.20 and should not be configured
# Removed options (9.18 compatibility note):
# - alt_transfer_source (use TLS instead)
# - auto_dnssec (automatic in 9.20)
# - glue_cache (always enabled in 9.20)
logging:
channels:
- name: default_log
file:
name: /var/log/named/default.log
severity: info
print_time: true
print_severity: true
print_category: true
- name: security_log
file:
name: /var/log/named/security.log
severity: dynamic
print_time: true
print_severity: true
print_category: true
- name: query_log
file:
name: /var/log/named/queries.log
versions: 5
size: 10m
severity: info
print_time: true
- name: dnssec_log
file:
name: /var/log/named/dnssec.log
severity: debug
print_time: true
print_severity: true
- name: rate_limit_log
syslog: daemon
severity: warning
categories:
- name: default
channels:
- default_log
- name: general
channels:
- default_log
- name: security
channels:
- security_log
- name: queries
channels:
- query_log
- name: dnssec
channels:
- dnssec_log
- name: rate-limit
channels:
- rate_limit_log
- name: named.conf.local
tls:
- name: censurfridns-anycast
remote_hostname: anycast.uncensoreddns.org
- name: censurfridns-unicast
remote_hostname: unicast.uncensoreddns.org
zones:
- name: example.internal
type: forward
forward: only
forwarders:
- 10.0.0.53
- 10.0.0.54

22
molecule/bind9-20/molecule.yml Normal file
View File

@@ -0,0 +1,22 @@
---
# Molecule scenario for BIND9 9.20+ support validation
# This scenario tests the role with BIND9 9.20 and later feature releases
# Note: May require ubuntu:24.04 or Debian 13 (Trixie) for 9.20 package availability
driver:
name: podman
platforms:
- name: ubuntu-2404-bind920
image: docker.io/library/ubuntu:24.04
command: /lib/systemd/systemd
privileged: true
volumes:
- /sys/fs/cgroup:/sys/fs/cgroup:rw
cgroupns_mode: host
provisioner:
name: ansible
config_options:
defaults:
ALLOW_BROKEN_CONDITIONALS: true
verifier:
name: ansible

7
molecule/bind9-20/prepare.yml Normal file
View File

@@ -0,0 +1,7 @@
---
- name: Prepare
hosts: all
tasks:
- name: Update package cache
ansible.builtin.apt:
update_cache: true

103
molecule/bind9-20/verify.yml Normal file
View File

@@ -0,0 +1,103 @@
---
- name: Verify
hosts: all
gather_facts: true
tasks:
- name: Check that BIND9 is installed
ansible.builtin.package:
name: bind9
state: present
check_mode: true
register: __bind9_package_check
failed_when: __bind9_package_check is changed
- name: Check that BIND9 service is running
ansible.builtin.service:
name: named
state: started
enabled: true
check_mode: true
register: __bind9_service_check
failed_when: __bind9_service_check is changed
- name: Check that BIND9 version is 9.20 or later
ansible.builtin.command:
cmd: named -v
register: __bind9_version_check
changed_when: false
failed_when: false
- name: Display BIND9 version
ansible.builtin.debug:
msg: "BIND9 version: {{ __bind9_version_check.stdout }}"
- name: Check that named.conf.options exists
ansible.builtin.stat:
path: /etc/bind/named.conf.options
register: __options_file
failed_when: not __options_file.stat.exists
- name: Check that named.conf.local exists
ansible.builtin.stat:
path: /etc/bind/named.conf.local
register: __local_file
failed_when: not __local_file.stat.exists
- name: Read named.conf.options content
ansible.builtin.slurp:
path: /etc/bind/named.conf.options
register: __options_content
- name: Verify forwarders are configured in options
ansible.builtin.assert:
that:
- "'forwarders' in __options_decoded"
- "'91.239.100.100' in __options_decoded"
- "'forward first' in __options_decoded"
fail_msg: Forwarders not properly configured in named.conf.options
vars:
__options_decoded: "{{ __options_content.content | b64decode }}"
- name: Read named.conf.local content
ansible.builtin.slurp:
path: /etc/bind/named.conf.local
register: __local_content
- name: Verify forward zone is configured
ansible.builtin.assert:
that:
- "'zone \"example.internal\"' in __local_decoded"
- "'type forward' in __local_decoded"
- "'forward only' in __local_decoded"
fail_msg: Forward zone not properly configured in named.conf.local
vars:
__local_decoded: "{{ __local_content.content | b64decode }}"
- name: Test DNS resolution using localhost
ansible.builtin.command:
cmd: dig @localhost google.com +short
register: __dns_query
changed_when: false
failed_when: __dns_query.rc != 0
- name: Verify DNS query returned results
ansible.builtin.assert:
that:
- __dns_query.stdout_lines | length > 0
fail_msg: DNS forwarding is not working
- name: Check BIND logs for errors
ansible.builtin.command:
cmd: tail -20 /var/log/named/default.log
register: __bind_logs
changed_when: false
- name: Display BIND logs
ansible.builtin.debug:
msg: "BIND logs:\n{{ __bind_logs.stdout }}"
- name: Verify no critical errors in logs
ansible.builtin.assert:
that:
- "'error' not in __bind_logs.stdout.lower() or 'error' in __bind_logs.stdout.lower() | regex_replace('error reporting', '')"
fail_msg: Found errors in BIND logs