Server Preparation for Ubuntu 22.04

Introduction

This guide gives you detailed information on preparing your Ubuntu 22.04 server for the use with ownCloud.

The target audience for this document are experienced admins with additional needs and setup scenarios. Ubuntu 22.04 by default only provides PHP 8.1. However, PHP versions 8.0 and 8.1 are currently not supported, therefore this guide describes how to install PHP version 7.4 on Ubuntu 22.04 by the means of the ondrej/php PPA. For more information, see Currently Supported PHP Versions. This document considers two basic scenarios. You plan to upgrade from 20.04 LTS to 22.04 LTS or you have a fresh Ubuntu 22.04 LTS installation.

PHP 8.x is currently not supported by ownCloud server.
Read the openSSL Version notes which are important when planning to use encryption.
The commands and links provided in this description should give you proper hints but we cannot take any responsibility.

Upgrading from Ubuntu 20.04 to 22.04

Without going into the upgrade details, you can now upgrade directly from Ubuntu 20.04 LTS to 22.04 LTS when using the do-release-upgrade command. For more details see an example description at Upgrade Ubuntu 20.04 to 22.04 LTS using command line

sudo apt update
sudo apt upgrade
sudo apt dist-upgrade
sudo apt autoremove
sudo apt install update-manager-core
sudo do-release-upgrade

If you have upgraded successfully and had previously installed any versions of PHP, better uninstall all PHP versions and ALL extensions and perform a fresh PHP 7.4 native installation. To do so, stop any services which depend on or use PHP like your Web Server. Then get a list of all PHP related programs and extensions by typing:

dpkg -l | grep php | awk '{print $2}' | tr "\n" " "

Disable all extensions listed (see the section Useful Commands For Managing PHP Extensions).

Then purge them step by step:

sudo apt purge <package name from the list above>

Alternatively, if you are fine removing all packages listed, you can run:

sudo apt purge `dpkg -l | grep php | awk '{print $2}' | tr "\n" " "`
Keep a copy of your relevant php.ini and other configuration files as reference before you start purging, to quickly reconfigure your PHP 7.4 installation afterwards.

After deinstallation of all versions and extensions of PHP and cleaning up all remnants, you should have an empty /etc/php directory. You can proceed like on a fresh installation of Ubuntu 22.04 LTS.

Clean Ubuntu 22.04 Installation

After you have installed your Ubuntu 22.04 LTS server from scratch, use the following commands to first add the ondrej/php PPA and then install PHP 7.4 and all necessary extensions:

sudo add-apt-repository ppa:ondrej/php -y
sudo apt update && sudo apt upgrade
sudo apt install php7.4 php7.4-intl php7.4-mysql php7.4-mbstring \
       php7.4-imagick php7.4-igbinary php7.4-gmp php7.4-bcmath \
       php7.4-curl php7.4-gd php7.4-zip php7.4-imap php7.4-ldap \
       php7.4-bz2 php7.4-ssh2 php7.4-common php7.4-json \
       php7.4-xml php7.4-dev php7.4-apcu php7.4-redis \
       libsmbclient-dev php-pear php-phpseclib

Note that the php-phpseclib package is a pure PHP implementation for handling various ciphers and not dependent to the php source.

Use the following commands to install some common prerequisites:

sudo apt install smbclient
sudo apt install redis-server
sudo apt install unzip
sudo apt install openssl
sudo apt install rsync
sudo apt install imagemagick

Multiple Concurrent PHP Versions

If you have multiple concurrent PHP versions installed, which will happen when using the ondrej/php PPA, you must tell your Web Server and your CLI environment which one to use. Please note that ondrej/php installs ALL versions of PHP. To list all available versions installed and choose one of them, use the following command:

sudo update-alternatives --config php

Here is an example output:

There are 2 choices for the alternative php (providing /usr/bin/php).

  Selection    Path             Priority   Status
------------------------------------------------------------
* 0            /usr/bin/php7.4   74        auto mode
  1            /usr/bin/php7.4   74        manual mode
  2            /usr/bin/php8.0   80        manual mode

Press <enter> to keep the current choice[*], or type selection number:

You can also directly set the required PHP version:

sudo update-alternatives --set php /usr/bin/php7.4
After selecting your PHP version, it is highly recommended to switch to the correct compiling environment which is essential e.g. when using PECL! 
sudo update-alternatives --set phar /usr/bin/phar7.4
sudo update-alternatives --set phar.phar /usr/bin/phar.phar7.4
sudo update-alternatives --set phpize /usr/bin/phpize7.4
sudo update-alternatives --set php-config /usr/bin/php-config7.4

When using Apache PHP-FPM, you have to configure your PHP version in an Apache config file manually. In any case, the PHP version used must always be the same.

You can read more about the update-alternatives command in the man page.

When switching a PHP version, you MUST also configure the corresponding php.ini files and extensions accordingly! Extension binaries are not shared!
You may get completely unexpected behaviour or a broken environment if the PHP version for the Web Server and for CLI are different!

Avoiding a Nasty Pitfall

If you are using a PECL install later on, check the output of the installation command soon after it has started. You will find a text like:

...
PHP Api Version:         20190902
Zend Module Api No:      20190902
...

Then do a test by just entering the following command:

php -i | grep extension_dir

If the output is different than the style below, there is a problem that needs fixing:

extension_dir => /usr/lib/php/20180731 => /usr/lib/php/20180731

This is the output that shows a fix is needed:

PHP Warning:  PHP Startup: smbclient: Unable to initialize module
Module compiled with module API=20190902
PHP    compiled with module API=20180731
These options need to match

As you see above, the API modules do not match and have been compiled with different versions and therefore will not work. To fix this, uninstall the PECL module with pecl uninstall <extension_name>, set the correct update-alternatives as described above and reinstall it.

Updating pear

The following step is necessary to upgrade PEAR because of a change in PHP 7.4.1+ Note that you should always use the latest stable PEAR release.

pear version
sudo mkdir -p /tmp/pear/cache
sudo pear upgrade --force \
      --alldeps http://pear.php.net/get/PEAR-1.10.13
sudo pear clear-cache
sudo pear update-channels
sudo pear upgrade --force
sudo pear upgrade-all
pear version

If you get any notices containing You should add "extension=…​, check if the extension is listed in /etc/php/7.4/mods-available. If it is not present, add the .ini file manually and enable it.

Post upgrading pear, you can safely remove the directory /tmp/pear/cache.

See the php-imagick Library section if you are interested why an updated version of ImageMagick is necessary.

Apache Web Server

The following command installs the Apache Web Server.

sudo apt install libapache2-mod-php7.4 apache2

See the important note on using the correct Multi-Processing Module (MPM).

Although it’s not supported by ownCloud, you can configure Apache to use php-fpm, the FastCGI Process Manager, which is a non-standard setup and not covered by this document.

libsmbclient-php Library

libsmbclient-php is a PHP extension that uses Samba’s libsmbclient library to provide Samba-related functions to PHP programs. You need to install it if you have installed smbclient as described above. smbclient is e.g. necessary if you are using the Windows Network Drives app from ownCloud’s Enterprise Edition. To install it, run the following command:

sudo apt install php7.4-smbclient

When the command completes, perform the following tasks:

  • Create /etc/php/7.4/mods-available/smbclient.ini with the following content: extension=smbclient.so.

  • Enable the module by running phpenmod smbclient.

  • Restart PHP and your web server by running the following command:

    sudo service apache2 restart
Alternatively you can install smbclient from source.

php-imagick Library

When using new or extended formats for previews like HEIC or SVG, the standard installation of ImageMagick 6 lacks this functionality. You have to manually install ImageMagick 7 (while the php wrapper version should be 3.7.0, which is fine, when following the install instructions above). To do so, follow the Install an Updated ImageMagick Version guide. See the Previews Configuration guide how to enable preview providers for various file types.

Useful Commands For Managing PHP Extensions

List Enabled PHP Extensions

If you want to retrieve a list of enabled PHP extensions run the following command:

ls `php -i | grep "^extension_dir" | sed -e 's/.*=> //'` | sort

Enabling and Disabling PHP Extensions

To enable or disable a PHP extension for CLI, FPM or Apache, use the commands phpenmod or phpdismod.

Example:

sudo phpenmod php-ldap

or

sudo phpdismod php-ldap

Type the command without parameters or see this guide to read more about the commands in the php-common package.

Notes for PHP Library phpseclib

phpseclib’s BigInteger uses the php-gmp (GNU Multiple Precision Arithmetic Library), php-bcmath and OpenSSL extensions, if they’re available, for speed, but doesn’t require them to maintain maximum compatibility. The GMP library uses an internal resource type, while the BCMath library uses strings as datatype. The most salient difference is that GMP works on arbitrary precision integer values whereas BCMath allows arbitrary precision] decimal / float-like values.

Database Installation

To install a database, see the Manual Installation Databases guide.

Follow the procedure described in Useful Tips if you want to Disable Transparent Huge Pages (THP),Transparent Huge Pages.

You may want to use the latest version of phpmyadmin as the OS default versions lags behind the latest available stable version a lot and may report PHP errors with PHP 7.4. Follow this quick upgrade guide to install it.

Useful Tips

Start a Service After a Resource is Mounted

If you have network resources, such as NFS or iSCSI based mounts, and you want to make sure that the database or web server only starts after the resource is mounted, then consider the following example setup when configuring your system.

The example below is based on an NFS mount which you want to be available before the service with <name.service> starts. The same procedure can be used for iSCSI. For details setting up an iSCSI mount see the Ubuntu iSCSI Initiator guide.

The name in <name.service> could be any valid service, including apache2, mysql or mariadb.

  • Add _netdev to the list of NFS mount point options in /etc/fstab.

    This option ensures, that the mount happens after the network is up:

    resource:foreign_path local_path nfs (<your options>),_netdev

  • Make sure that all mounts in /etc/fstab are mounted by running:

    sudo mount -a

  • Run the following command to list mounts which must be up first:

    systemctl list-units | grep -nP "\.mount"

    You should see lines printed to the console. Look for the mount you want to be up in the command’s output.

    <folder.mount>
  loaded active mounted <local_path>

    where <folder.mount> and <local_path> are examples!

  • Edit the service you want to change:

    sudo systemctl edit <name>.service

    Add the following directive in the editor opened, using your chosen folder.mount from above:

    [Unit]
After=folder.mount

    You can add more than one dependency if needed by separating them with spaces. This procedure keeps <name>.service in its original state but makes it possible to override the current setup with new parameters. This is necessary, because on updates, the original service data will be overwritten. It automatically creates a directory in /etc/systemd/system, named <name>.service.d, and a file in that directory called override.conf. In the example above, the parameter is added to the existing list of parameters of the After directive.

    For more details please read section Example 2. Overriding vendor settings

    Please keep the following points in mind, regarding if <name>.service is linked or not:

    • If the file is linked from /lib/systemd/system, it is for packaged unit files. They are overwritten when Systemd (or whatever package provides them) is upgraded.

    • If the file originates in /etc/systemd/system, it is for your own and customised unit files. Unit files you place in here override the package-provided file and will not be replaced on upgrade.

    It is recommended to keep things simple and future-proof by creating an override file via systemctl edit For more details see Editing Unit Files.

  • Run the following command to apply your changes:

    sudo systemctl daemon-reload

  • Check if <name>.service has been properly added:

    sudo systemctl show <name>.service | grep "After="

    folder.mount should be part of the parameter list.

  • Restart your service by invoking:

    sudo system <name> restart

Disable Transparent Huge Pages (THP)

Transparent Huge Pages should be disabled when using databases. This is applicable when using Redis, as well as MariaDB. For more information read: Why THP (Transparent Huge Pages) are not recommended for Databases.

To disable Transparent Huge Pages, follow these steps:

  • Create in /etc/systemd/system a file like disable-thp.service add the following content:

    [Unit]
Description=Disable Transparent Huge Pages
DefaultDependencies=no
After=sysinit.target local-fs.target
Before=basic.target

[Service]
Type=oneshot
ExecStart=/bin/sh -c '/bin/echo never > /sys/kernel/mm/transparent_hugepage/enabled'
ExecStart=/bin/sh -c '/bin/echo never > /sys/kernel/mm/transparent_hugepage/defrag'

[Install]
WantedBy=basic.target

  • Run the following command to apply and activate your changes and start it automatically at boot time:

    sudo systemctl daemon-reload
    sudo systemctl enable disable-thp
    sudo service disable-thp start