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.

In case the current system is still running a 32-bit installation, moving to a 64-bit system is required, as newer versions of the Registration Server no longer support 32-bit environments.

In case the current system uses a Linux OS other than Red Hat Enterprise Linux 6 or a derivative like Cent OS 6, Oracle Linux 6, Scientific Linux 6 or Amazon Linux, you must perform the upgrade by starting a new instance and migrating the configuration as outlined in Moving an Older Installation to a Newly Installed Instance.

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 and local configuration files and templates are the crucial pieces of data that need to be preserved during updates. Take backups prior to performing an update and verify they worked correctly. In case of an in-place upgrade, the databases and most configuration files can be taken over “as is”. When performing a migration to a new instance, the databases and supporting files need to be copied or moved to the new host.

Updates between different Registration Server major versions (e.g. from 3.0.017 to 3.0.018) 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.

Starting with version 3.0.018, updates to a new build (e.g. from 3.0.018.0 to 3.0.018.1) can be performed using yum/RPM. Updating from older major versions (e.g. 3.0.017 or 3.0.015) requires manual intervention, as the installations were performed without automatic package management.

Upgrading Version 3.5.0 or Later to a Newer Build

The use of RPM packages makes updating within a major version from one build to another (e.g. from 3.5.0 to 3.5.1) a fairly straightforward and automatic process.

Usually, you can simply replace the existing packages while the service is running. The update performs an immediate restart of the services (httpd and td-regserver automatically):

[root@regserver ~]# yum update td-regserver

Check the chapter releasenotes-3.5.0 for the changes introduced in each build.

In-place Upgrading from 3.0.018 to 3.5.0

These instructions assume a default installation of the TeamDrive Registration Server (version 3.0.018) on RHEL6 or a derivative distribution like CentOS 6 (64-bit) that was set up based on the Registration Server installation instructions or using the TeamDrive Registration Server Virtual Appliance for VMware. 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 a few configuration settings by performing the following steps:

  • Stop the Apache HTTP Server and PrimeBase processes (PBAC)
  • Perform a backup of the Registration Server’s MySQL Databases and support files
  • Remove the PrimeBase Application Environment and related files
  • Remove old Apache modules
  • Install the new Registration Server RPM package td-regserver
  • Review/update the configuration files, remove backup configuration files after merging the settings
  • Perform necessary conversions of the MySQL table structures
  • Review/update the email templates
  • Start the TeamDrive Registration Server background service and Apache http Server, check the log files for any errors
  • Test the new setup with a local test client before allowing all user Clients to connect to the new instance again

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 ~]# service httpd stop

Next, stop the Registration Server background tasks:

[root@regserver ~]# pbctl stop

Use pbctl status to check that the services have been stopped (their Status needs to be Stopped) and ps or pstree to double check that there are no stray httpd, pbeas, ase, pbas, pbac or smm processes running. Use kill <pid> or pkill <name> to terminate these, if they don’t disappear shortly after you issued the stop commands.

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 \
--databases td2apilog td2reg \
| gzip > td-regserver-mysql-$(date +%Y-%m-%d_%H.%M).sql.gz

Backup the old Installation and Configuration Files

Next, create a backup the old PrimeBase Application Environment, Apache Modules and config files, if you don’t have a full system backup already (e.g. a VM snapshot) that you could revert to in case of issues.

Note that some of these files might not exist on your local installation. The following sample shell script will skip these and add all existing ones to a backup tar archive named td-regserver-backup-YYYY-MM-DD.tar.gz in the current directory:

#!/bin/sh
BACKUP="td-regserver-backup-$(date +%Y-%m-%d).tar"

FILES="
/etc/httpd/conf.d/adminconsole.conf
/etc/httpd/conf.d/fastcgi.conf
/etc/httpd/conf.d/pbt.conf
/etc/httpd/conf.d/ssl.conf
/etc/httpd/conf/httpd.conf
/etc/httpd/modules/mod_pbt*.so
/etc/httpd/myssl
/etc/init.d/primebase.boot
/etc/logrotate.d/teamdrive
/etc/php.ini
/etc/php-fpm.d/www.conf
/etc/primebase
/etc/profile.d/custom.csh
/etc/profile.d/custom.sh
/etc/profile.d/primebase.sh
/etc/profile.d/teamdrive.sh
/etc/sysconfig/httpd
/usr/local/lib
/usr/local/lib64
/usr/local/primebase
/var/www/html/activation
/var/www/html/adminconsole"
for a in $FILES
do
  if [ -e $a ]
  then
      tar rvf $BACKUP $a
  fi
done
gzip $BACKUP

Review and save values from Configuration File

Before starting the upgrade, please copy a few existing settings. They are stored in a binary file and could not be extracted later on after the old Primebase components are removed. As described in the documentation for version 3.0.018:

http://docs.teamdrive.net/RegServer/3.0.018.8/html/TeamDrive-Registration-Server-Admin-Guide-en/Upgrading.html#review-configuration-files

use the tool pbee (PrimeBase Environment File Editor) to ewview and copy the values from the following settings to store them later on in the admin console after the update:

240    Mail Server Address            <SMTP Server hostname>
243    Email Sender Address           <you@yourdomain.com>
244    Host Name                      <reg server hostname>

Leave the tool pbee with the command quit

Install the new Registration Server Software

The TeamDrive Registration Server components are available in the form of RPM packages, hosted in a dedicated yum repository. This makes the installation and applying of future updates very easy — you can simply run yum 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 the 3.5 TeamDrive Registration Server yum 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 \
http://repo.teamdrive.net/td-regserver.repo

Now you can simply update the installed packages by entering:

[root@regserver ~]# yum update td-regserver td-regserver-adminconsole \
PrimeBase_TD

The update removes the old primebase components in /usr/local/primebase but will keep your mail templates in the path /usr/local/primebase/setup/scripts/template/. They will be imported to the database later on in the update process.

Removing the old primebase components might require additional changes in the configuration. If you used the default teamdrive user and the default password for the mysql database connection, the update will automatically create a new connection definition using the default values. Please change the mysql user and password in the file /etc/td-regserver.my.cnf in case that you dont use the defaults.

As described in the Release Notes 3.5 the Apache HTTP Server no longer requires to be configured using the “worker” MPM, which simplifies the overall installation and configuration of the base operating system and allows for using the PHP Apache module instead of the FastCGI implementation for the Administration Console. Please remove the FastCGI module with:

[root@regserver ~]# yum remove php-fpm

Please disable using the “worker” MPM in the file:

/etc/sysconfig/httpd

and comment out the line:

HTTPD=/usr/sbin/httpd.worker

to:

#HTTPD=/usr/sbin/httpd.worker

In order to facilitate access to the Registration Server’s API and update screens via SSL, the following needs to be added to the end of the default <VirtualHost> section in /etc/httpd/conf.d/ssl.conf:

#   Per-Server Logging:
#   The home of a custom SSL log file. Use this when you want a
#   compact non-error SSL logfile on a virtual host basis.
CustomLog logs/ssl_request_log \
          "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

RewriteEngine on
RewriteLogLevel 0
RewriteLog "/var/log/httpd/rewrite.log"

RewriteRule ^/setup$ /setup/ [R]
RewriteRule ^/setup(.*) /yvva/setup$1 [PT]
RewriteRule ^/pbas/td2as/(.*)$ /yvva/$1 [PT]
RewriteRule ^/pbas/td2api/(.*)$ /yvva/$1 [PT]

</VirtualHost>

Proceed with the database update step. This could be done using a web browser or the linux shell. For using a web browser you have to start the apache server again, but you have to make sure, that no client could connect during the database update.

To be safe we recommend using the linux shell.

Update the database using a browser

Start the apache again:

[root@regserver ~]# service httpd start

and follow the update process in the web interface:

https://regserver.yourdomain.com/setup/

Please restart the apache after the successfull update:

[root@regserver ~]# service httpd restart

and make sure, that all other necessary services will be started as described in chapter Starting and stopping the TeamDrive Registration Server components

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.

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.

Update the MySQL Configuration

Review the content of the /etc/my.cnf configuration file. In particular, make sure that the option max_allowed_packet and max_connections is included in the [mysqld] option group and is set to:

[mysqld]
max_allowed_packet=2M
max_connections=512

The max_allowed_packet value is necessary for Registration Server Version 3.5.0 and later, to support the upload of user profile data by Clients that support this feature.

The max_connections=512 is the minimum value. It might be necessary to increase the value on your system depending on how many clients are connected to your server.

Start the Registration Server Components

Now start the TeamDrive Registration Server background service:

[root@regserver ~]# service td-regserver start
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 ~]# service httpd start
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. Set the above email configuration values in the admin console in Server Management –> Registration Server Settings –> Email. The old values must be stored in these new fields:

Mail Server Address --> SMTPServer
Mail Server Timeout --> SMTPServerTimeOut
Email Sender Address --> MailSenderEmail
Host Name --> MailSenderHost

Check other new values in the provider settings section. Former global server settings are now provider specific settings. A full list of all settings could be found in the chapter Settings

Mail templates

The name of the mail templates beginning with “td3-” in the file name changed:

td3-privacyinvited-email-utf8” to “inv-email-invited

td3-privacyinvitedsecure-email-utf8” to “inv-email-invited-passwd

td3-privacyinvited-user-utf8” to “inv-user-invited

td3-privacyinvitedsecure-user-utf8” to “inv-user-invited-passwd

Please check the imported mail templates in the admin console in Manage Templates and customize new email templates for your provider(s).

Please delete the old path /usr/local/primebase/ using the command:

[root@regserver ~]# /bin/rm /usr/local/primebase/ -R

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 ~]# chkconfig | grep td-regserver
td-regserver          0:off   1:off   2:off   3:off   4:off   5:off   6:off
[root@regserver ~]# chkconfig td-regserver on
[root@regserver ~]# chkconfig | grep td-regserver
td-regserver          0:off   1:off   2:on    3:on    4:on    5:on    6:off
[root@regserver ~]# chkconfig | grep httpd
httpd                 0:off   1:off   2:on    3:on    4:on    5:on    6:off

Moving an Older Installation to a Newly Installed Instance

Please refer to the Registration Server 3.0.018 documentation how to upgrade to version 3.0.018 before upgrading to version 3.5.