From 1c635e5c553b4f9418702a6b02da8fabd8c9946a Mon Sep 17 00:00:00 2001 From: Daniel Akulenok Date: Sat, 7 Feb 2026 23:46:18 +0100 Subject: [PATCH] docs: Add comprehensive BIND9 9.18 to 9.20 migration guide - Create step-by-step migration guide with pre-planning checklist - Document all 44 breaking changes with explanations - Provide before/after configuration examples - Include Ansible role-specific changes and branch selection - Add DNSSEC policy migration guidance - Include testing recommendations and validation checklist - Provide rollback procedures for safe migration - Link to technical version differences documentation Closes #6 --- docs/BIND9_MIGRATION_GUIDE.md | 479 ++++++++++++++++++++++++++++++++++ 1 file changed, 479 insertions(+) create mode 100644 docs/BIND9_MIGRATION_GUIDE.md diff --git a/docs/BIND9_MIGRATION_GUIDE.md b/docs/BIND9_MIGRATION_GUIDE.md new file mode 100644 index 0000000..8129079 --- /dev/null +++ b/docs/BIND9_MIGRATION_GUIDE.md @@ -0,0 +1,479 @@ +# 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.