Upgrading the TeamDrive Registration Server¶

General Upgrade Notes¶

There are two basic approaches to updating a TeamDrive Registration Server: in-place, by replacing the software with a newer version on the live system, or starting a new instance and migrating the configuration and data (MySQL Database and configuration files) to the new instance.

For older installations, performing a migration to a freshly installed instance might be the better approach, to get rid of accumulated “cruft” and to start from a clean slate.

Updating requires a brief service interruption, as the Registration Server components (e.g. the Apache HTTP Server) need to be stopped while the update is in progress. Short downtimes usually pass unnoticed by the TeamDrive Clients, they will simply try again after a short waiting period. Local Client operations can continue.

The Registration Server-specific MySQL Databases is the crucial pieces of data that need to be preserved during updates. Take a backup prior to performing an update and verify they worked correctly.

Updates between different Registration Server versions may require changes to the MySQL table structures.

These changes need to be applied manually prior to starting the services after updating. Reversing these changes (e.g. reverting to the previous database version) requires going back to the previous backup, there is no automatic roll-back of changes to the database/table structures.

[root@regserver ~]# wget -O /etc/yum.repos.d/td-regserver.repo https://repo.teamdrive.net/td-regserver.repo

[root@regserver ~]# dnf update td-regserver td-regserver-adminconsole yvva

Check the chapter Release Notes - Version 5.0 for the changes introduced in each build.

Now update the database to version 5.x as described in the steps below Update the database using the linux shell

In-place Upgrading to a newer version¶

These instructions assume a default installation of the TeamDrive Registration Server on RHEL9 or a derivative distribution like CentOS 9 (64-bit) that was set up based on the Registration Server installation instructions or using the TeamDrive Registration Server Virtual Appliance. They further assume that the MySQL database and Administration Console run locally as well.

The overall procedure is similar in all cases — we’ll remove the old software components while retaining the MySQL databases and configuration files, install the current versions of the Registration Server RPM packages and and manually migrate the database to the new version by performing the following steps:

Stop the Apache HTTP Server and td-regserver service
Perform a backup of the Registration Server’s MySQL Databases
Install the new Registration Server RPM package td-regserver and td-regserver-adminconsole
Perform necessary conversions of the MySQL table structures using the command line tool yvva
Start the TeamDrive Registration Server background service td-regserver and Apache http Server, check the log files for any errors

The following paragraphs explain these steps in more detail.

Stop the TeamDrive Services¶

As a first step, the currently running TeamDrive Registration Server needs to be shut down. If you have any monitoring services that send out alerts for system outages, you might want to disable these beforehand. If your Registration Server is behind a load balancer or firewall, it might make sense to block incoming Client connections from there, too. This prevents unwanted accesses while you are still working on bringing up the updated instance.

Start by stopping the Apache HTTP Server:

[root@regserver ~]# systemctl stop httpd

Next, stop the Registration Server background tasks:

[root@regserver ~]# systemctl stop td-regserver

Create a MySQL Backup¶

After all TeamDrive Services have been stopped, you should now create a backup of the MySQL databases, e.g. using mysqldump:

[root@regserver ~]# mysqldump -u root -p --force \
--max_allowed_packet=64M --databases td2apilog td2reg > backup.sql

Install the new Registration Server Software¶

The TeamDrive Registration Server components are available in the form of RPM packages, hosted in a dedicated dnf repository. This makes the installation and applying of future updates very easy — you can simply run dnf update to keep your Registration Server software up to date.

Note

Please just follow the steps that describe the software installation! The MySQL user and databases have been created already, so there is no need to perform these steps again.

To enable a newer TeamDrive Registration Server dnf repository, you need to download the updated td-regserver.repo file and place it into the directory /etc/yum.repos.d/, e.g. by using wget:

[root@regserver ~]# wget -O /etc/yum.repos.d/td-regserver.repo \
https://repo.teamdrive.net/td-regserver.repo

Now you can simply update the installed packages by entering:

[root@regserver ~]# dnf update td-regserver td-regserver-adminconsole yvva

Proceed with the database update step.

Update the database using the linux shell¶

To view the databases changes and start the database update use the command:

[root@regserver ~]# yvva

The upgrade commands will be listed:

UPGRADE COMMANDS:
-----------------
To upgrade from the command line, execute:
yvva --call=upgrade_now --config-file="/etc/yvva.conf"

print_changes;;
Print a list of changes will be performed when you run 'upgrade_now'.

upgrade_now;;
Perform upgrade changes to the database (this command cannot be undone).

Type in print_changes;; to view the list of changes and start the update with upgrade_now;;.

You will get the output:

Upgrade in progress...

Upgrade completed successfully.

Exit yvva with quit.

Change the mysql authentication from the old mysql_native_password, which is depreacted, to the new caching_sha2_password. To check if you have to change the authentication, open the /var/lib/mysql/mysqld.log file and search for this warning:

[Warning] [MY-013360] [Server] Plugin mysql_native_password reported:
''mysql_native_password' is deprecated and will be removed in a future
release. Please use caching_sha2_password instead'

Login with the root user to MySQL:

[root@regserver ~]# mysql -u root -p

and execute (replace <password> with the teamdrive mysql password –> see /etc/td-regserver.my.cnf):

mysql> alter user teamdrive@localhost identified with caching_sha2_password by '<password>';

Review Configuration Files¶

During installation, RPM may detect that some local configuration files differ from the ones to be installed. Instead of overwriting these, RPM will create the distribution’s default configuration files as <filename>.rpmnew. Carefully review the differences and manually migrate any relevant changes to the new files before renaming them to their original file names, which will overwrite the previous versions.

Start the Registration Server Components¶

Now start the TeamDrive Registration Server background service:

[root@regserver ~]# systemctl start td-regserver
Starting TeamDrive Registration Server Auto Tasks:         [  OK  ]

Check the log file for any errors:

[root@regserver ~]# less /var/log/td-regserver.log

Next, start the Apache HTTP Server if not already done above:

[root@regserver ~]# systemctl start httpd
Starting httpd:                                            [  OK  ]

Check the log files for any errors:

[root@regserver ~]# less /var/log/httpd/error_log

In case of any errors, check the chapter Troubleshooting for guidance.

Log into the Administration Console¶

Clear your browser cache before accessing the admin console.

Enable the TeamDrive Registration Server at System Boot¶

If the update was successful and the service is up and running, make sure they get started automatically when the system reboots:

[root@regserver ~]# systemctl enable td-regserver
[root@regserver ~]# systemctl enable httpd

Migrate to a newer version on new server¶

Migrating a server to a new instance is similar to the in-place upgrade described above.

Follow the above steps for Stop the TeamDrive Services and Create a MySQL Backup. Copy your ssl certificates and the database backup to the new instance and import the database with:

[root@regserver ~]# mysql -u root -p < backup.sql

On the new instance, store the SSL certificates in the same location as on the previous server and update the settings in /etc/httpd/conf.d/ssl.conf for SSLCertificateFile, SSLCertificateKeyFile and SSLCACertificateFile as on the previous server.

Execute Start Update the database using the linux shell to upgrade the database to the current version.

Follow the above Start the Registration Server Components on the new instance and check the log files for errors.

In the last step, transfer the IP address from the old instance to the new one and adjust your external firewall if necessary.