|

Debian 12 to 13 Server Upgrade: A System Administrator’s Guide

ByPieter Bakker

This guide provides a streamlined yet comprehensive approach to upgrading Debian 12 (Bookworm) to Debian 13 (Trixie) on production servers. It balances efficiency with safety, based on real-world server upgrade experience.

Pre-Flight Checklist

Essential Preparations

Schedule Maintenance Window: Plan for 30-60 minutes of downtime, depending on your server’s package count and internet speed.

Backup Critical Data: At minimum, backup:

  • /etc/ directory (system configurations)
  • Database dumps
  • Application data directories
  • Any custom scripts or configurations

Prepare for Remote Access Issues: If upgrading remotely:

  • Use screen or tmux to prevent SSH disconnection issues
  • Have out-of-band access (IPMI, console) ready
  • Ensure you have physical access if needed

Notify Stakeholders: Inform users and services about the planned maintenance window.

Quick System Health Check

# Check for broken packages
dpkg --audit

# Verify disk space (need at least 2GB free)
df -h

# Check current system version
cat /etc/debian_version

The Upgrade Process

Step 1: Update Current System

Start by ensuring your Debian 12 system is fully current:

apt update && apt full-upgrade -y

Why this matters: Starting with a fully updated Bookworm reduces the chance of conflicts during the major version upgrade.

Step 2: Update Repository Sources

Use the built-in editor to safely update your sources:

apt edit-sources

This opens your sources list in your default editor. Change all instances of bookworm to trixie. A typical server sources list will look like:

deb http://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
deb http://deb.debian.org/debian/ trixie-updates main contrib non-free non-free-firmware

Pro tip: The apt edit-sources command is safer than manually editing /etc/apt/sources.list because it validates syntax and creates automatic backups.

Step 3: Refresh Package Information

apt update

You may see warnings about version changes – this is expected during a major upgrade.

Step 4: Perform the Two-Phase Upgrade

Phase 1 – Conservative Upgrade:

apt upgrade --without-new-pkgs

This upgrades packages that can be updated without installing new dependencies or removing packages. It’s a safety net that catches potential issues early.

Phase 2 – Full Distribution Upgrade:

apt full-upgrade

This completes the upgrade by handling package additions, removals, and complex dependency changes.

Step 5: Post-Upgrade Cleanup

# Remove unnecessary packages
apt autoremove -y

# Clean package cache
apt autoclean

# Verify the upgrade
cat /etc/debian_version

Step 6: System Restart and Verification

# Restart the system
reboot

# After reboot, check for failed services
systemctl --failed

# Verify system status
systemctl status

Configuration File Handling

During the upgrade, you may be prompted about configuration files. Here’s how to handle common scenarios:

  • Keep current version (recommended): Press N or O
  • View differences: Press D to see what changed
  • Install new version: Press Y or I (only if you know you need new features)

Rule of thumb: For production servers, keep your current configurations unless you specifically need new functionality.

Server-Specific Considerations

Web Servers

  • Apache/Nginx: Configuration syntax rarely changes between Debian versions, but test your virtual hosts after upgrade
  • PHP: Check PHP version compatibility with your applications
  • SSL Certificates: Verify certificate paths and permissions

Database Servers

  • MySQL/MariaDB: Run mysql_upgrade after the system upgrade if prompted
  • PostgreSQL: Check for version-specific upgrade notes
  • Backup first: Always backup databases before system upgrades

Mail Servers

  • Postfix/Dovecot: Test mail flow after upgrade
  • Check logs: Monitor /var/log/mail.log for any issues

Monitoring and Logging

  • Update monitoring agents: Some may need reconfiguration
  • Check log rotation: Verify logrotate configurations still work
  • Restart monitoring services: Ensure they’re using updated libraries

Troubleshooting Common Issues

Held Back Packages

If packages are held back:

apt list --upgradable
apt install <package-name>  # Force upgrade specific packages

Broken Dependencies

apt --fix-broken install
dpkg --configure -a

Service Failures

# Check specific service
systemctl status <service-name>
journalctl -u <service-name>

# Restart failed services
systemctl restart <service-name>

Network Issues During Upgrade

If you lose SSH connectivity:

  • Use out-of-band access (IPMI, console)
  • Check if SSH service is running: systemctl status ssh
  • Verify network configuration: ip addr show

Rollback Strategy (Emergency Only)

If critical issues arise immediately after upgrade:

# This is complex and not always successful
apt edit-sources  # Change trixie back to bookworm
apt update
apt upgrade  # This may or may not work cleanly

Important: Rolling back a major version upgrade is unreliable. This is why backups are crucial.

Post-Upgrade Best Practices

Immediate Tasks (First 24 Hours)

  1. Monitor system logs: journalctl -f
  2. Check application functionality
  3. Verify backup systems are working
  4. Test critical services and endpoints
  5. Monitor system performance

Ongoing Tasks (First Week)

  1. Watch for unusual log entries
  2. Monitor system resources
  3. Verify automated tasks (cron jobs) are running
  4. Check for any delayed service issues

Documentation Updates

  1. Update server documentation with new OS version
  2. Note any configuration changes made during upgrade
  3. Update disaster recovery procedures if needed
  4. Record lessons learned for future upgrades

Security Considerations

Immediate Security Tasks

  • Update SSH keys if using older formats
  • Review firewall rules for any changes
  • Check for new security features in Debian 13
  • Verify SELinux/AppArmor policies if used

Ongoing Security Monitoring

  • Subscribe to Debian security announcements
  • Update monitoring systems to recognize new OS version
  • Review and update security baselines

Performance Optimization

After upgrading, consider:

  • Reviewing and updating system tuning parameters
  • Checking for new kernel features that might benefit your workload
  • Updating system monitoring thresholds
  • Reviewing resource allocation for virtual machines

Conclusion

This streamlined approach balances the need for safety with operational efficiency. The key is thorough preparation, careful execution, and comprehensive post-upgrade verification.

Remember that every server environment is unique. Adapt this process to your specific needs, always prioritize data safety, and never upgrade critical production systems without tested backups and rollback plans.

For additional servers, consider creating a standardized checklist based on this guide, customized for your specific infrastructure and applications.

This guide is optimized for server environments and system administrators managing multiple Debian installations. Always test upgrade procedures in non-production environments first.

Similar Posts