Note: only upgrade from TLD Linux 2019.01 is supported. If you are running older version of TLD Linux you may try to follow an upgrade path of “one version at the time”, but we strongly recommend to perform clean install of TLD Linux 2024.01 instead.

Version 2024.01 of TLD Linux introduces some big changes that you should be aware of before upgrading your systems.

First, the content of the distribution has been heavily stripped down to limit the time and resources needed for maintenance and development. This was a necessary step, and the alternative was to close the project.

In fact, TLD Linux is currently a micro-distribution with a limited set of packages. It is still focused on the server environment and can still happily run your servers and services… if they are still supported.

Secondly, you need to know that all packages have been rebuilt from scratch for better library compatibility and compatibility with the newer RPM version. This means that the update to version 2024.01 will replace any package that is still supported.

Third, there is some work you need to do on your systems before you can upgrade…

As usual the first step you should do is to perform full backup of your system so you will be able to revert back if something goes wrong.

It is also a good idea to get rid of all *.rpmnew files from /etc to be sure you will have newest default configurations for all packages for which old one cannot be adjusted or updated.

Before you will be able to upgrade the system it is required to upgrade RPM and poldek to new versions. You will need to modify your poldek configuration to temporarily use archived TLD Linux 2019.01 package repository. Change contents of file /etc/poldek/repos.d/tld.conf to:

# TLD Linux - https://tld-linux.org/

_arch   = x86_64
_prefix = http://dist.tld-linux.org/TLD
_branch = archive/2019.01

############################################################

# TLD Linux
[source]
type   = pndir
name   = ti
path   = %{_prefix}/%{_branch}/main/%{_arch}/RPMS/

[source]
type   = pndir
name   = ti
path   = %{_prefix}/%{_branch}/main/noarch/RPMS/

# TLD Linux, test packages
[source]
type   = pndir
name   = ti-test
path   = %{_prefix}/%{_branch}/test/%{_arch}/RPMS/
auto   = no
autoup = no

[source]
type   = pndir
name   = ti-test
path   = %{_prefix}/%{_branch}/test/noarch/RPMS/
auto   = no
autoup = no

# TLD Linux, archived packages
[source]
type   = pndir
name   = ti-archive
path   = %{_prefix}/%{_branch}/archive/%{_arch}/RPMS/
auto   = no
autoup = no

[source]
type   = pndir
name   = ti-archive
path   = %{_prefix}/%{_branch}/archive/noarch/RPMS/
auto   = no
autoup = no

This is a standard poldek configuration except for URL (which uses http not https) and branch (which points us to arcihved TLD Linux 2019.01). If you are using 32-bit version of TLD Linux don't forget to change architecture from x86_64 to i686.

Now, make sure that your poldek indexes are up to date:

poldek --upa

And finally you may perform the upgrade:

poldek -u rpm poldek

If upgrade will fail complaining about broken dependencies or conflicting packages you may need to remove them, for example:

poldek -e rpm-pythonprov rpm-specdump systemtap-client

List of packages that you will need to remove will vary depending on what is installed in your system. After removal try to upgrade again.

After upgrading poldek and RPM you need to import TLD package signing key:

rpm --import /etc/pki/rpm-gpg/TLD-Linux.asc

If your installation of TLD Linux 2019.01 is not up to date, it is strongly recommended to update it before attempting an upgrade to version 2024.01.

poldek -v --nohold --upgrade-dist

Note: this is not an upgrade yet. Your poldek configuration still points to archived TLD Linux 2019.01.

As support for MySQL 5.7 ended in October 2023, it is no longer available on TLD Linux. Additionally, MySQL packages have been modified to be co-installable, so you can run multiple versions in parallel if necessary (like we did with PostgreSQL in TLD Linux 2018.02).

For this reason, you must migrate to MySQL 8.0 before upgrading your system, otherwise you may irreversibly damage your MySQL installation. There are two ways to migrate your databases, manually or automatically.

We do not recommend a manual migration. It is a bit complicated and time consuming process. Use it only if automatic migration fails.

Notes:

1. Migration assumes that you use single MySQL cluster. If you have multiple clusters you must migrate all of them.

2. If you are using localhost as server address your applications/websites will stop working after upgrade. That is because MySQL client will try to connect via UNIX socket and its path has changed. You have three options to fix this:

• Change localhost to 127.0.0.1 to force connection over TCP. This also requires commenting out skip-networking and setting bind-address=127.0.0.1 in /etc/mysql/8.0/mysqld.conf. This is recommended option.

• Set option mysql.default_socket and/or pdo_mysql.default_socket to /var/lib/mysql/8.0/mysql.sock in your php.ini. The drawback is that this will fix only PHP applications.

• Symlink old path to MySQL socket to new path. The drawback is that this will point to specific version of MySQL which may not be desired if you run more than one version in parallel.

rm -f /var/lib/mysql/mysql.sock
ln -s /var/lib/mysql/8.0/mysql.sock /var/lib/mysql/mysql.sock

Automatic migration

1. Stop MySQL 5.7 on your server:

service mysql stop

2. Copy away and/or backup following folders:

• /etc/mysql
• /usr/share/mysql
• /var/lib/mysql
• /var/log/mysql
• /var/log/archive/mysql

3. Install MySQL 8.0 libraries to prevent automatic removal of pacakges which depend on “mysql-libs”.

poldek -i mysql-8.0-libs

4. Remove all MySQL packages from system:

poldek --cmd "uninstall mysql-*"

5. Remove following folders:

• /etc/mysql
• /usr/share/mysql
• /var/lib/mysql
• /var/log/mysql
• /var/log/archive/mysql

6. Install MySQL 8.0:

poldek -i mysql-8.0 mysql-8.0-client

7. Initialize MySQL 8.0 cluster:

service mysql-8.0 init

8. Remove contents of newly created cluster:

rm -rf /var/lib/mysql/8.0/main/mysqldb/*

9. Copy or restore contents of old /var/lib/mysql/mysqldb/ to /var/lib/mysql/8.0/main/mysqldb/

10. Start MySQL 8.0 (this may take some time as automatic cluster upgrade will be run):

service mysql-8.0 start

11. If MySQL 8.0 has started then migration was probably successful. Please check /var/log/mysql/8.0/mysqld.log for details to confirm that MySQL cluster data have been successfuly upgraded or to find reasons of failure. You should see something like this:

2024-03-31T18:56:20.136830Z 0 [System] [MY-010116] [Server] /usr/lib64/mysql/8.0/sbin/mysqld (mysqld 8.0.35) starting as process 2884
2024-03-31T18:56:20.174510Z 1 [System] [MY-011012] [Server] Starting upgrade of data directory.
2024-03-31T18:56:20.174611Z 1 [System] [MY-013576] [InnoDB] InnoDB initialization has started.
2024-03-31T18:56:20.639578Z 1 [System] [MY-013577] [InnoDB] InnoDB initialization has ended.
2024-03-31T18:56:23.061789Z 2 [System] [MY-011003] [Server] Finished populating Data Dictionary tables with data.
2024-03-31T18:56:24.023143Z 5 [System] [MY-013381] [Server] Server upgrade from '50700' to '80035' started.
2024-03-31T18:56:28.379152Z 5 [System] [MY-013381] [Server] Server upgrade from '50700' to '80035' completed.

12. Optionally make adjustments to MySQL 8.0 config to match your requirements and reload MySQL 8.0 service to apply the changes.

Manual migration

1. Make a full backup of all of your databases using mysqldump command. This will not be covered here, there are plenty of howtos available online.

2. Stop MySQL 5.7 on your server:

service mysql stop

3. Remove all MySQL packages from system:

poldek --cmd "uninstall mysql-*"

4. Move away or remove following folders:

• /etc/mysql
• /usr/share/mysql
• /var/lib/mysql
• /var/log/mysql
• /var/log/archive/mysql

5. Install MySQL 8.0:

poldek -i mysql-8.0 mysql-8.0-client

6. Initialize MySQL 8.0 cluster:

service mysql-8.0 init

7. Restore your databses from your backups. Manually recreate all users and their privileges.

As noted on the beginning, lots of packages have been removed from distribution and are no longer supported. You should remove all these packages or your upgrade may be blocked by unresolved package dependencies. Following script will create list of removed packages for you:

#!/bin/sh

rpm -qa --qf="%{name}\n" > installed_packages.txt
poldek --cmd "ls --qf=%{name}\n" > dist_packages.txt
sed -i -e 's/\+/\\\+/g;' installed_packages.txt
rm -f removed_packages.txt
for pkg in $(cat installed_packages.txt | sort); do
  if ! grep -q -E "^"$pkg"$" dist_packages.txt && [ "$pkg" != "ldconfig" ]; then
    echo "$pkg" >> removed_packages.txt
  fi
done
test -f removed_packages.txt && sed -i -e 's/\\//g;' removed_packages.txt
rm -f installed_packages.txt dist_packages.txt

Carefully inspect contents of file removed_packages.txt created by above script to see what packages must be removed. Adjust the list to your needs and when ready remove packages with:

rpm -ev --nodeps $(cat removed_packages.txt)

If you do need some packages that is no longer supported feel free to contact us and perhaps it will be possible to revive them.

Warning! Read notes about Grub below and perform necessary actions before continuing or your system may become unbootable.

Now you are ready to upgrade your system to TLD Linux 2024.01, but first you need to update your poldek configuration to point to current stable release. To do this please change branch in /etc/poldek/repos.d/tld.conf from archive/2019.01 to stable. It is also recommended to use https protocol, but if you wish you may leave http. Alternatively, if poldek upgrade has created tld.conf.rpmnew you may simply overwrite your configuration with default one by running:

mv /etc/poldek/repos.d/tld.conf.rpmnew /etc/poldek/repos.d/tld.conf

Clean and update poldek indexes:

poldek --clean --upa

Perform system upgrade:

poldek -v --nohold --upgrade-dist

If you'll run into some unresolved dependencies you may try following things:

1. Remove problematic package. If it hauls half of your system use:

rpm -e --nodeps pakcage

2. Do forced upgrade of problematic package via poldek command line:

poldek --cmd "upgrade --force package"

Add –nodeps if necessary.

TLD 2024.01 contains updated version of Grub bootloader. It is required to reinstall Grub on your system after upgrade or your system will fail to boot. If you are using BIOS/legacy boot simply reinstall bootloader. Example:

grub-install /dev/sda

If you are using UEFI boot you need to:

1. Make sure that partition formatted as FAT32 is mounted at /boot/efi. Example:

mount -t vfat /dev/sda2 /boot/efi

2. Make sure that efivarfs kernel module is loaded:

modprobe efivarfs

3. Make sure that /sys/firmware/efi/efivars is mounted. If not, mount it:

mount -o rw -t efivarfs efivarfs /sys/firmware/efi/efivars

Now you can reinstall bootloader. Example:

grub-install /dev/sda

If you are using software RAID, remember to reinstall Grub on all disks. After reinstalling make sure that EFI partition on all disks have same content. You can copy entire partition using dd. First, unmount EFO parition:

umount /boot/efi

Now copy it to each disk, for example:

dd if=/dev/sda2 of=/dev/sdb2
dd if=/dev/sda2 of=/dev/sdc2

Linux firmware packages have been reorganized. If your devices need to load firmware to work properly, please check the *-firmware packages and install the required ones before rebooting.

Service spamd will not be able to start after upgrade due to version change from 3.x to 4.x. To fix this you will need to run:

/usr/bin/sa-update
/usr/bin/sa-compile