Update the ISPConfig Perfect Server from Ubuntu 20.04 to Ubuntu 22.04

This tutorial will take you through updating a server managed by ISPConfig from Ubuntu 20.04 (Focal Fossa) to Ubuntu 22.04 (Jammy Jellyfish). This guide works for both single- and multiserver setups. Just repeat the same steps on every server.

Warning: mailman2 is not supported in Ubuntu 22.04, and mailman3 is not (yet) supported by ISPConfig.

Be aware that the update process may cause some downtime.


  • Make sure you're logged in as root user

1. Updating the system from Ubuntu 20.04 to Ubuntu 22.04

Please go through the guide on updating Ubuntu itself: https://www.howtoforge.com/ubuntu-20-04-to-22-04-upgrade/

2. Clean up mailman

If mailman2 was installed, we must rename the data directory to prevent mail transport conflicts.

mv /var/lib/mailman /var/lib/mailman-bk

Then run these commands:

mkdir -p /var/lib/mailman/data/
touch /var/lib/mailman/data/{aliases,transport-mailman,virtual-mailman}
postmap /var/lib/mailman/data/{aliases,transport-mailman,virtual-mailman}

to create some empty files instead.

3. Install missing PHP packages

Ubuntu 22.04 ships with PHP 8.1 as default PHP version, so we have to install it (along with later needed curl):

apt -y install php8.1 php8.1-cli php8.1-cgi php8.1-fpm php8.1-gd php8.1-mysql php8.1-imap php8.1-curl php8.1-intl php8.1-pspell php8.1-sqlite3 php8.1-tidy php8.1-xsl php8.1-zip php8.1-mbstring php8.1-soap php8.1-opcache php8.1-common php8.1-readline php8.1-xml curl

Don't forget to adjust the PHP config files if necessary.

If you still want to use PHP 7.4 for some websites, install it as an additional version by following https://www.howtoforge.com/tutorial/how-to-install-php-7-for-ispconfig-3-from-debian-packages-on-debian-8-and-9/

4. Run a force update of ISPConfig

To reconfigure the services so they are correctly configured for Debian 11, we need to run the ISPConfig update script and let it reconfigure services. Run the script from the command line with

ispconfig_update.sh --force

Go through the update steps. When asked whether you want to reconfigure services or not, hit enter. If you skip this step by answering "no", ISPConfig won't configure your services for Ubuntu 22.04 and some services might be broken.

5. Update paths to use PHP 8.1 as default PHP version

As PHP 8.1 is the default PHP version shipped with Ubuntu 22.04, we need to update the PHP paths in ISPConfig.

Log in to the panel as admin user and then go to System -> Server Config -> server1.example.com (the hostname of your server) -> Web -> PHP Settings

Replace the references to 7.4 to 8.1, so it looks like this:

Apache php.ini path: /etc/php/8.1/apache2/php.ini
CGI php.ini path: /etc/php/8.1/cgi/php.ini
PHP-FPM init script: php8.1-fpm
PHP-FPM php.ini path: /etc/php/8.1/fpm/php.ini
PHP-FPM pool directory: /etc/php/8.1/fpm/pool.d
PHP-FPM socket directory: /var/lib/php8.1-fpm

Be aware that all websites on this server that use the PHP version "Default" will now use PHP 8.1 instead of the old version.

We also have to let the system use PHP 8.1 as the default PHP handler for non-ISPConfig actions. To do this, run:

update-alternatives --config php

If you need to select a PHP version, select PHP 8.1. Then, run

update-alternatives --config php-cgi

If you need to select a PHP version, select PHP 8.1 as well. Lastly, run

update-alternatives --config php-fpm.sock

If you need to select a PHP version, select PHP 8.1 again.

For servers with Apache2 installed, we have to disable PHP-FPM 7.4 as the default PHP handler and enable PHP-FPM 8.1 by running these commands:

a2disconf php7.4-fpm
a2enconf php8.1-fpm
systemctl restart apache2

6. Update phpMyAdmin (optional)

If you have phpMyAdmin installed, we recommend updating your install as many users have an outdated version installed.

Run this command to run our phpMyAdmin update script:

curl https://git.ispconfig.org/ispconfig/tools/-/raw/master/auto_update_phpmyadmin.sh -sL | sh

You can keep phpMyAdmin updated automatically from now on by using this same script. See this forum post for more information: https://www.howtoforge.com/community/threads/keep-your-phpmyadmin-installation-up-to-date-automatically.88495/

We're done! If you have any problems, open a thread on the forum.

Share this page:

4 Comment(s)

Add comment

Please register in our forum first to comment.


By: ganewbie at: 2023-01-13 13:43:37

Thanks for the great tutorial, Is there a way to be able to switch between the PHP version from GUI?

By: till at: 2023-01-13 13:54:50

There is a selector for the PHP version in the website settings which lists all additional PHP versions that you installed (and configured in ISPConfig).

By: Andre Hall at: 2023-02-25 14:50:00

I have tried multiple times following the tutorial to first update my server. The issue I'm having is that Apache is not starting after the server is updated from 20.04 to 22.04. I can't seem to figure out why the service isn't starting, I'm unable to configure the new PHP paths as instructed in Step 5 because I can't access ISPConfig due to Apache failing to start.  Can anyone provide some help as to why Apache failed to start?

By: till at: 2023-02-25 23:12:41

As mentioned in the update guide: If you have any problems, open a thread on the forum.