Automation Script: Upgrading Debian 11 to 12 and VitalPBX 4 to 4.5

FAQ
1

This script automates the process of upgrading a Debian 11 system to Debian 12 and includes a seamless migration from VitalPBX 4 to VitalPBX 4.5, along with cleanup tasks to optimize the environment.

Before upgrading your system, it is strongly recommended that you make a full backup, or at least back up any data or configuration information you can’t afford to lose. The upgrade tools and process are quite reliable, but a hardware failure in the middle of an upgrade could result in a severely damaged system.

Please read the Debian Release Notes to be clear about the risks

Please read carefully before proceeding.

:white_check_mark: Best Practices Before Running the Migration Script

1. Backup Everything

  • Take a full system backup (snapshot preferred if using a hypervisor).
  • Export the VitalPBX configuration and database manually or using the backup module on VitalPBX.
  • Backup any custom configuration files under /etc/apache2/, /etc/nginx/, /etc/firewalld/, and /etc/php/.

2. Test in a Lab Environment First

  • If possible, clone the production server and perform the migration in a test environment first.

3. Check for System Customizations

  • Review whether Apache2 has custom modules or third-party integrations.
  • Verify if any services are bound to Apache ports (80, 443).
  • Audit the firewall configuration to ensure no manual rules will be lost.

4. Prepare for Web Server Changes

  • Understand that after migration, NGINX will replace Apache2.
  • If there are manually created Apache virtual hosts, plan to migrate them to NGINX manually.

5. Clear and Update APT Sources Manually (Optional)

  • Ensure /etc/apt/sources.list and files in /etc/apt/sources.list.d/ are clean and only contain valid Debian and VitalPBX repositories.

6. Allocate Maintenance Window

  • Plan for potential downtime of at least 1-2 hours.
  • Notify users that the system will reboot after migration.

7. Monitor Migration Carefully

  • Be ready to respond manually if the script stalls or prompts for input.
  • Monitor log outputs during the script execution.

:warning: Potential Points of Failure

1. Custom Packages or Manual Changes

  • Systems with non-standard software may encounter upgrade failures.
  • Manual changes in Apache or PHP settings may not translate cleanly to NGINX.

2. Package Dependency Conflicts

  • Debian 12 introduces newer versions of libraries.
  • Some dependencies may break during or after the upgrade.

3. Apache Dependency

  • Applications still dependent on Apache2 will fail after removal.
  • VitalPBX config files (such as custom extensions) might rely on Apache if customized manually.

4. Firewall and Fail2Ban Reset

  • The script rebuilds the firewall and fail2ban configurations, which might wipe custom IP lists or rules.

5. Database Integrity Risks

  • Although the DB migration is not direct, if MariaDB upgrades encounter issues, the database may become inaccessible.

6. Human Error During Script Execution

  • If the script prompts for input and wrong choices are made, migration could fail.

7. Automatic Reboot After Migration

  • If critical errors occur during upgrade but go unnoticed, the server may reboot into an unstable system.

:rocket: How to Use

  1. Download the script file.
wget https://raw.githubusercontent.com/VitalPBX/VPBX4toVPBX45SS/refs/heads/main/vpbx4tovpbx45.sh
  1. Make the script executable:
chmod +x vpbx4tovpbx45.sh
  1. Execute the script:
./vpbx4tovpbx45.sh
  1. Configuration Prompts During Script Execution
    When running the script, you may encounter prompts like the following:
*** mpm_event.conf (Y/I/N/O/D/Z) [default=N] ? <press Enter>
........
*** firewalld.conf (Y/I/N/O/D/Z) [default=N] ? <press Enter>
  1. Optional: Remove All Unused Kernels from Version 5.x
dpkg --list | grep 'linux-image-5' | awk '{print $2}' | grep -v "$(uname -r)" | xargs sudo apt remove -y

:bar_chart: Post-Migration Checks

After the reboot, verify:

  • VitalPBX web interface functionality.
  • SIP registrations and call routing.
  • NGINX service status.
  • Firewall and Fail2Ban are active and correctly configured.
  • MariaDB is running and accessible.

:bulb: Final Advice

Do not attempt this migration directly on critical production systems without testing or snapshots.
When in doubt, plan for a clean installation of Debian 12 and migrate the VitalPBX using the backup and restore module as described in this link.

“Preparation is the difference between a successful migration and an emergency recovery!”

4 Likes