daniel/ansible-bind9-role
1
0
Fork 0
Code Issues 3 Pull Requests 1 Actions Releases Wiki Activity
Files
main
ansible-bind9-role/docs/BIND9_MIGRATION_GUIDE.md
Daniel Akulenok 1c635e5c55
All checks were successful
Test / Lint (push) Successful in 14s
Details
Test / Test (push) Has been skipped
Details
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
2026-02-07 23:46:18 +01:00

480 lines
12 KiB
Markdown
Raw Permalink Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink