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.

Updating requires a 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 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 versions requires manual intervention, as the installations were performed without automatic package management.

Upgrading Version 3.0.018 to a Newer Build

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

Usually, you can simply update the installed packages while the service is running by entering the following command:

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

The update performs an immediate restart of the services (httpd and teamdrive) automatically. It also removes the file $PRIMEBASEHOME/setup/scripts/StartupCache.pbt and re-creates it by calling the HTTPRequest.pbt script via pbac in the background.

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

In-place Upgrading from Older Versions to 3.0.018

These instructions assume a default installation of the TeamDrive Registration Server (version 3.0.017) 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.

Note

The following approach does not work on 32-bit systems and it does not apply to custom installations on other Linux distributions. If you performed an installation to different locations/directories, the process might work, but has not been tested/verified.

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 packages PrimeBase_TD, td-regserver and td-regserver-adminconsole
  • 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 pbpg td2apilog td2reg \
| gzip > td-regserver-mysql-$(date +%Y-%m-%d_%H.%M).sql.gz

Note

Older versions of of the Registration Server (3.0.015 and older) used an additional pbpg database to store public and private encryption keys. The --force option in the example above ensures that the dump continues, even if the database does not exist in your setup.

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

Remove Obsolete Files and Binaries

Now, remove the manually installed files and binaries that are no longer required or will be replaced with never versions by the yum package manager (except for some config files). Again, note that not all of these files might exist on your local installation:

[root@regserver ~]# rm -rf \
/etc/httpd/modules/mod_pbt.so \
/etc/init.d/primebase.boot \
/etc/logrotate.d/teamdrive \
/etc/primebase \
/etc/profile.d/custom.csh \
/etc/profile.d/custom.sh \
/etc/profile.d/primebase.sh \
/etc/profile.d/teamdrive.sh \
/usr/local/primebase/bin \
/usr/local/primebase/include \
/usr/local/primebase/Installer.log \
/usr/local/primebase/lib \
/usr/local/primebase/PBinstaller.info \
/usr/local/primebase/pbstab \
/usr/local/primebase/plugins \
/usr/local/primebase/versions \
/var/www/html/adminconsole

The system has now been prepared for installing the new version of the Registration Server Software.

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.

Follow the software installation instructions for the Registration Server and Administration Console outlined in the TeamDrive Registration Server Installation Guide: Enabling the TeamDrive Registration Server yum Repository, Installing the Registration Server package and Installing the Administration Console.

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.

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.

In the case of the binary configuration file pbvm.env, you can usually keep the old one in place. Since it’s a binary file, you need to use the tool pbee (PrimeBase Environment File Editor) to review and edit the configuration settings of the PrimeBase Environment. In particular, the following settings should be checked:

240    Mail Server Address              <SMTP Server hostname>
243    Email Sender Address             <you@yourdomain.com>
245    Email Envelope Sender Address
244    Host Name                        <reg server hostname>
340    Protocol Log File                /var/log/pbvm.log

Update the MySQL Configuration

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

[mysqld]
max_allowed_packet=2M

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

Update the MySQL Table Structures

When updating to a new version of the Registration Server, it’s necessary to make some changes to the existing MySQL databases and tables. This section explains the necessary steps you need to perform.

Warning

Before making these changes, make sure that no other Registration Server instance is currently accessing the MySQL database! Changing the MySQL schemas while an older version of the Registration Server is still accessing them will likely lead to a service disruption.

Remove some obsolete table indexes by executing the following migration script v3.0.017_to_v3.0.018.sql as the MySQL teamdrive user:

[root@regserver ~]# mysql -u teamdrive -p < \
/opt/teamdrive/regserver/mysql/v3.0.017_to_v3.0.018.sql
Enter password:
[root@regserver ~]#

Double check that the MySQL connection information provided in the connect.def file is correct. See Configuring the Registration Server’s MySQL configuration for details.

Once the connection has been verified, you need to execute the PBT script HTTPRequest.pbt to analyze the necessary updates to the MySQL tables.

Change to the directory /usr/local/primebase/setup, remove the cache file scripts/StartupCache.pbt start pbac and choose connection 2 (TD2REG_WRITE) to execute the file HTTPRequest.pbt using the following commands:

[root@regserver ~]# cd /usr/local/primebase/setup
[root@regserver ~]# rm scripts/StartupCache.pbt
rm: remove regular file `scripts/StartupCache.pbt'? y
[root@regserver setup]# pbac
PrimeBase Automation Client.
Copyright 2007-2014, PrimeBase Systems GmbH.
Web:    http://www.primebase.net
E-mail: support@primebase.net

Select a connection by number, and Login:
Or enter 'A' to add, 'D' to delete, or 'E' to edit an entry.
Or enter 'T' to move an entry to the top of the list.

File: ./connect.def

   Alias                Protocol             Server
   -------------------- -------------------- --------------------
0  (exit without connecting)
1  td2as                Internal/Runtime
2  TD2REG_WRITE         Internal/Runtime     OpenServer
3  TD2REG_SLAVE         Internal/Runtime     OpenServer
-----------------------------------------------------------------

Connection..: 2
User........: teamdrive<Enter>
Password....: *********<Enter>
 1: Connected to "TD2REG_WRITE" as "teamdrive".

For a list of commands enter "#help"

 1:   1> execute file "HTTPRequest.pbt";
 1:   2> go
 1: Execution begins...
09/08/2014 12:24:29.78 ERROR : INIT ERROR: TD2User.ShadowKey column missing
09/08/2014 12:24:29.79 ERROR : INIT ERROR: TD2User.MD5Password incorrect size: 40
09/08/2014 12:24:29.79 ERROR : INIT ERROR: TD2Ticket.MD5Password incorrect size: 40
09/08/2014 12:24:29.80 ERROR : INIT ERROR: TD2Owner.MD5Password incorrect size: 40
09/08/2014 12:24:29.80 ERROR : INIT ERROR: TD2Device.MD5Password is no
longer used, and should be removed
09/08/2014 12:24:29.80 ERROR : INIT ERROR: TD2MessageSF.ClientVersion incorrect size: 10
09/08/2014 12:24:29.81 ERROR : INIT ERROR: TD2MessageFD.ClientVersion incorrect size: 10
09/08/2014 12:24:29.81 ERROR : INIT ERROR: TD2User.PrivDataModCount column missing
09/08/2014 12:24:29.81 ERROR : INIT ERROR: TD2User.PubDataSecret column missing
09/08/2014 12:24:29.81 ERROR : INIT ERROR: TD2User.PubDataModCount column missing
09/08/2014 12:24:29.81 ERROR : INIT ERROR: TD2User.PubUserData column missing
09/08/2014 12:24:29.81 ERROR : INIT ERROR: Table TD2UserBlob missing
09/08/2014 12:24:29.81 ERROR : INIT ERROR: The public data secret key must be generated
09/08/2014 12:24:29.81 ERROR : EXECUTE: TDUpgrade:generatePublicDataSecret();
09/08/2014 12:24:29.84 ERROR : INIT ERROR: The version number in the
database must be upgraded to the 00.00.00.00000 format
09/08/2014 12:24:29.84 ERROR : EXECUTE: TDUpgrade:upgradeVersionNumbers();
09/08/2014 12:24:29.84 ERROR : INIT ERROR:
UseExternalAuthentification/UseExternalAuthentificationCall still exist
09/08/2014 12:24:29.84 ERROR : EXECUTE: TDUpgrade:deleteDeprecatedSettings();
09/08/2014 12:24:29.84 ERROR : INIT ERROR: TD2Ticket.TicketPhase column missing
09/08/2014 12:24:30.15 TRACE : Adding auto-task: Expire Licenses
09/08/2014 12:24:30.16 ERROR : **** CREATED UPDATE SCRIPT ****
09/08/2014 12:24:30.16 ERROR : /usr/local/primebase/setup/mysql_update_to_3.0.018.sql
09/08/2014 12:24:30.16 ERROR : CONTENTS:
09/08/2014 12:24:30.16 ERROR : ---------
09/08/2014 12:24:30.16 ERROR : USE td2reg;
ALTER TABLE TD2User ADD COLUMN ShadowKey VARCHAR(40) CHARACTER SET ascii
NULL after MD5Password;
ALTER TABLE TD2User MODIFY MD5Password VARCHAR(120) CHARACTER SET ascii NOT
NULL;
ALTER TABLE TD2Ticket MODIFY MD5Password VARCHAR(120) CHARACTER SET ascii
NULL;
ALTER TABLE TD2Owner MODIFY MD5Password VARCHAR(120) CHARACTER SET ascii NOT
NULL;
ALTER TABLE TD2Device DROP COLUMN MD5Password;
ALTER TABLE TD2MessageSF MODIFY ClientVersion VARCHAR(20) CHARACTER SET
ascii NULL DEFAULT '';
ALTER TABLE TD2MessageFD MODIFY ClientVersion VARCHAR(20) CHARACTER SET
ascii NULL;
ALTER TABLE TD2User ADD COLUMN PrivDataModCount INT UNSIGNED NOT NULL
DEFAULT 0;
ALTER TABLE TD2User ADD COLUMN PubDataSecret VARCHAR(40) CHARACTER SET ascii
NULL;
ALTER TABLE TD2User ADD COLUMN PubDataModCount INT UNSIGNED NOT NULL DEFAULT
0;
ALTER TABLE TD2User ADD COLUMN PubUserData BLOB;
CREATE TABLE TD2UserBlob
(
    ID                    BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY
    KEY,
    UserID                INT UNSIGNED    NOT NULL,
    Type                  VARCHAR(20)     CHARACTER SET ascii NOT NULL,
    GlobalID              VARCHAR(45)     CHARACTER SET ascii NOT NULL,
    Content               MEDIUMBLOB,
    UNIQUE(UserID, Type)
) ENGINE=InnoDB;
CREATE UNIQUE INDEX IndUserData ON TD2UserBlob(GlobalID);
ALTER TABLE TD2Ticket ADD COLUMN TicketPhase TINYINT UNSIGNED NOT NULL
DEFAULT 0 AFTER ValidUntil;

 1: Execution completed successfully.
 1:   1> quit
 1: Closed.

Among other things, HTTPRequest.pbt noticed that there are some changes required in the MySQL table structures and wrote these into an SQL script mysql_update_to_3.0.018.sql in the current directory (/usr/local/primebase/setup). We’ll address these first before performing the other required changes. You can review the content of this SQL file with a text editor before running the SQL script using the MySQL command line client as the teamdrive MySQL user:

[root@regserver setup]# cat mysql_update_to_3.0.018.sql
USE td2reg;
ALTER TABLE TD2User ADD COLUMN ShadowKey VARCHAR(40) CHARACTER SET ascii
NULL after MD5Password;
ALTER TABLE TD2User MODIFY MD5Password VARCHAR(120) CHARACTER SET ascii NOT NULL;
ALTER TABLE TD2Ticket MODIFY MD5Password VARCHAR(120) CHARACTER SET ascii NULL;
ALTER TABLE TD2Owner MODIFY MD5Password VARCHAR(120) CHARACTER SET ascii NOT NULL;
ALTER TABLE TD2Device DROP COLUMN MD5Password;
ALTER TABLE TD2MessageSF MODIFY ClientVersion VARCHAR(20) CHARACTER SET
ascii NULL DEFAULT '';
ALTER TABLE TD2MessageFD MODIFY ClientVersion VARCHAR(20) CHARACTER SET ascii NULL;
ALTER TABLE TD2User ADD COLUMN PrivDataModCount INT UNSIGNED NOT NULL DEFAULT 0;
ALTER TABLE TD2User ADD COLUMN PubDataSecret VARCHAR(40) CHARACTER SET ascii NULL;
ALTER TABLE TD2User ADD COLUMN PubDataModCount INT UNSIGNED NOT NULL DEFAULT 0;
ALTER TABLE TD2User ADD COLUMN PubUserData BLOB;
CREATE TABLE TD2UserBlob
(
    ID                    BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    UserID                INT UNSIGNED    NOT NULL,
    Type                  VARCHAR(20)     CHARACTER SET ascii NOT NULL,
    GlobalID              VARCHAR(45)     CHARACTER SET ascii NOT NULL,
    Content               MEDIUMBLOB,
    UNIQUE(UserID, Type)
) ENGINE=InnoDB;
CREATE UNIQUE INDEX IndUserData ON TD2UserBlob(GlobalID);
ALTER TABLE TD2Ticket add column TicketPhase TINYINT UNSIGNED NOT NULL
DEFAULT 0 AFTER ValidUntil;
[root@regserver setup]# mysql -u teamdrive -p < mysql_update_to_3.0.018.sql
Enter password:
[root@regserver setup]#

After performing these changes, delete the cache file scripts/StartupCache.pbt once again and re-run the HTTPRequest.pbt PBT script. This time it should not report any necessary database changes, but still observe some other pending update tasks:

[root@regserver setup]# rm scripts/StartupCache.pbt
rm: remove regular file `scripts/StartupCache.pbt'? y
[root@regserver setup]# pbac
PrimeBase Automation Client.
Copyright 2007-2014, PrimeBase Systems GmbH.
Web:    http://www.primebase.net
E-mail: support@primebase.net

Select a connection by number, and Login:
Or enter 'A' to add, 'D' to delete, or 'E' to edit an entry.
Or enter 'T' to move an entry to the top of the list.

File: ./connect.def

   Alias                Protocol             Server
   -------------------- -------------------- --------------------
0  (exit without connecting)
1  td2as                Internal/Runtime
2  TD2REG_WRITE         Internal/Runtime     OpenServer
3  TD2REG_SLAVE         Internal/Runtime     OpenServer
-----------------------------------------------------------------

Connection..: 2
User........: teamdrive
Password....: *********
 1: Connected to "TD2REG_WRITE" as "teamdrive".

For a list of commands enter "#help"

 1:   1> execute file "HTTPRequest.pbt";
 1:   2> go
 1: Execution begins...
09/08/2014 14:22:42.72 ERROR : INIT ERROR: The public data secret key must
be generated
09/08/2014 14:22:42.72 ERROR : EXECUTE: TDUpgrade:generatePublicDataSecret();
09/08/2014 14:22:42.72 ERROR : INIT ERROR: The version number in the
database must be upgraded to the 00.00.00.00000 format
09/08/2014 14:22:42.72 ERROR : EXECUTE: TDUpgrade:upgradeVersionNumbers();
09/08/2014 14:22:42.72 ERROR : INIT ERROR:
UseExternalAuthentification/UseExternalAuthentificationCall still exist
09/08/2014 14:22:42.72 ERROR : EXECUTE: TDUpgrade:deleteDeprecatedSettings();
 1: Execution completed successfully.
 1:   1>

To perform these remaining changes, you need to call the respective upgrade function, each followed by the keyword go:

 1:   1> TDUpgrade:generatePublicDataSecret();
 1:   2> go
 1: Execution begins...
 1: Execution completed successfully.
 1:   1> TDUpgrade:upgradeVersionNumbers();
 1:   2> go
 1: Execution begins...
09/08/2014 14:33:57.59 TRACE : Table TD2Device (column ClientVersion): Upgrading 20 row(s)
09/08/2014 14:33:57.62 TRACE : Table TD2Device: Upgraded 10 of 20 row(s)
09/08/2014 14:33:57.62 TRACE : Table TD2Device: Upgraded 20 of 20 row(s)
 1: Execution completed successfully.
 1:   1> TDUpgrade:deleteDeprecatedSettings();
 1:   2> go
 1: Execution begins...
 1: Execution completed successfully.
 1:   1> quit
 1: Closed.

This concludes the necessary database and configuration changes. Delete the StartupCache.pbt file one more time and run HTTPRequest.pbt once again, to verify that no more modifications are pending:

[root@regserver setup]# rm scripts/StartupCache.pbt
rm: remove regular file `scripts/StartupCache.pbt'? y
[root@regserver setup]# pbac
PrimeBase Automation Client.
Copyright 2007-2014, PrimeBase Systems GmbH.
Web:    http://www.primebase.net
E-mail: support@primebase.net

Select a connection by number, and Login:
Or enter 'A' to add, 'D' to delete, or 'E' to edit an entry.
Or enter 'T' to move an entry to the top of the list.

File: ./connect.def

   Alias                Protocol             Server
   -------------------- -------------------- --------------------
0  (exit without connecting)
1  td2as                Internal/Runtime
2  TD2REG_WRITE         Internal/Runtime     OpenServer
3  TD2REG_SLAVE         Internal/Runtime     OpenServer
-----------------------------------------------------------------

Connection..: 2
User........: teamdrive
Password....: *********
 1: Connected to "TD2REG_WRITE" as "teamdrive".

For a list of commands enter "#help"

 1:   1> execute file "HTTPRequest.pbt";
 1:   2> go
 1: Execution begins...
 1: Execution completed successfully.
 1:   1> quit
 1: Closed.

Configure the Registration Server Administration Console

The Administration Console’s configuration file globals.php needs to be edited, to provide the correct login credential to access the Registration Server’s MySQL databases. See the chapter Administration Console MySQL Configuration for details.

Review/update the Email Templates

Newer versions of the Registration Server sometimes add new mail templates and update existing ones. The default template set is located in the directory $PRIMEBASEHOME/setup/scripts/template/default.

You should review the mail templates belonging to the provider(s) hosted on this Registration Server (stored in $PRIMEBASEHOME/setup/scripts/template/<Provider code>) for missing templates and new macros. For example, version 3.0.018 of the Registration Server added a new macro [[BRAND]] that can be used to replace the previously hard-coded string “TeamDrive” with a custom brand name as defined in the EMAIL/BRAND_NAME Provider setting.

A quick way to review the additions and differences is to use a recursive grep:

[root@regserver ~]# cd $PRIMEBASEHOME/setup/scripts/template
[root@regserver template]# diff -urN <Provider Code> default

Take note of all the differences and missing files. Copy any missing files from the default directory into your Provider code directory and update the new templates based on your requirements.

Start the Registration Server Components

Now start the TeamDrive Registration Server background service:

[root@regserver ~]# service teamdrive start
Starting teamdrive services:                               [  OK  ]

Check the log file for any errors:

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

Example:

09/08/2014 12:18:45 [Protocol] 09/08/2014 12:18:45.82 TRACE : ---AUTO TASK...
09/08/2014 12:18:45 [Protocol]
09/08/2014 12:18:45 [Protocol] 09/08/2014 12:18:45.87 TRACE : ---DONE
09/08/2014 12:18:45 [Protocol]

Next, start the Apache http Server:

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

Check the log files for any errors:

[root@regserver ~]# less /var/log/httpd/error_log
[root@regserver ~]# less /var/log/pbvm.log
[root@regserver ~]# less /var/log/pbt_mod.trace

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

Log into the Administration Console

After the services have been started, try logging into the Administration Console and verify the settings.

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

Perform the installation of the 3.0.018 Registration Server instance from scratch as outlined in the Registration Server Installation Guide or start off booting and setting up a new Registration Server Virtual Appliance.

For the setup, initial installation and migration, the new instance can be started with a different IP address and host name. You need to be able to reach the new and old instance via SSH, in order to be able to copy files from one host to the other. Ideally, both hosts should be able to establish a direct SSH connection.

Once the Software has been installed and configured, access from Clients should be blocked, e.g. by changing a Firewall rule or load balancer configuration. Then stop the Apache Server and Services on the old Registration Server and make sure they are not yet running on the new instance, either. Copy over the MySQL databases from the old system, e.g. by creating a mysqldump as outlined in chapter Create a MySQL Backup and importing these databases into the new instance’s MySQL Server.

Also migrate the email template files of all providers from the old instance (located in $PRIMEBASEHOME/setup/scripts/template/<provider code>) to the new installation and update the templates as described in Review/update the Email Templates.

In addition to the mail templates, there are a number of Provider specific HTML pages located in the directory activation/<provider code> in the Apache http Server’s document root (usually /var/www/html). The entire activation directory needs to be copied to the new instance’s web server document root as well.

Also review the Apache http Server’s configuration files, particularly /etc/httpd/conf/httpd.conf or /etc/httpd/conf.d/ssl.conf (e.g. the ServerName setting or any other customizations like rewrite rules or access control restrictions). Manually apply these to the configuration files on the new instance, if necessary.

If the Registration Server’s MySQL Database is located on an external host, it’s sufficient to simply point the new Registration Server instance to this server by providing the appropriate login credentials as explained in chapters Configuring the Registration Server’s MySQL configuration and Administration Console MySQL Configuration. (You likely have to create a new MySQL user account and grant privileges to allow incoming connections to these databases from the new Registration Server). Once the new instance can access the MySQL database, perform a schema upgrade as outlined in Update the MySQL Configuration.

Before starting the services and making the new Registration Server available to the TeamDrive clients, it must be accessible under the original hostname, e.g. “regserver.yourdomain.com”. Make sure to update your DNS records accordingly (a change of IP address is fine, but remember to change the IP address on any associated Host Server’s API white list (APIAccessList).

Registration Server Upgrade to version 3.0.015

There are a few steps necessary for upgrading an existing server from version 3.0.014 to 3.0.015. Please contact TeamDrive Systems for upgrading from a version below 3.0.014 or for upgrading to the version 3.0.017.

We recommend stopping the apache web server and the pbac background task using pbctl and to just leave the database running. Execute the following update steps before restarting the services again.

Database Schema update

Please open a MySQL client and connect to the TeamDrive Registration Server database and run the following database changes. To identify errors during the update we recommend to execute each line step by step. (You will also find the schema update in the release package):

USE td2reg;
ALTER TABLE TD2User ADD COLUMN TdnsUserName VARCHAR(64) CHARACTER SET
utf8 COLLATE utf8_bin NULL UNIQUE after UserName;
CREATE INDEX IndUserNameHashTD2User ON TD2User(TdnsUserName);
CREATE INDEX IndOwnerIDTD2User ON TD2User(OwnerID);
ALTER TABLE TD2FreeUserStorage ADD FreeOffset BIGINT(20);
ALTER TABLE TD2FreeUserStorage ADD Fixed BOOLEAN;
ALTER TABLE TD2Device ADD PublicKey2 VARCHAR(8000) CHARACTER SET utf8 NULL;
ALTER TABLE TD2Email ADD column OwnerID INT UNSIGNED NOT NULL DEFAULT 0
AFTER ID;
ALTER TABLE TD2Email ADD column DestUserID INT UNSIGNED NOT NULL DEFAULT 0
AFTER Status;
ALTER TABLE TD2Email MODIFY ErrorMessage TEXT CHARACTER SET utf8 NULL;
ALTER TABLE TD2Setting ADD COLUMN Format VARCHAR(200) CHARACTER SET utf8
COLLATE utf8_unicode_ci NOT NULL AFTER Type;
ALTER TABLE TD2Ticket ADD COLUMN ExtReference VARCHAR(100)
CHARACTER SET utf8 COLLATE utf8_bin NULL;
ALTER TABLE TD2Ticket DROP INDEX IndTD2AccessTypeDateServer;
CREATE TABLE TD2BlobData
(
        ID INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
        OwnerID INT UNSIGNED NOT NULL,
        CreationTime TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
        ModifyTime TIMESTAMP NULL,
        Type VARCHAR(20) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
        IsActive INT UNSIGNED NOT NULL,
        Language VARCHAR(5) CHARACTER SET utf8 COLLATE utf8_general_ci NOT NULL,
        Name VARCHAR(100) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
        Extension VARCHAR(200) NULL,
        Data MEDIUMBLOB
) ENGINE=InnoDB;
CREATE INDEX IndOwnerIDTypeTD2BlobData ON TD2BlobData(OwnerID, Type);
USE pbpg;
ALTER TABLE `Keys` MODIFY Data VARCHAR(8000) CHARACTER SET utf8
COLLATE utf8_unicode_ci DEFAULT NULL;
ALTER TABLE `Keys` ADD Version INT UNSIGNED DEFAULT 1000 AFTER UniqueDevice;

Reg Server source update

You will get a package with new source files which must replace the existing files in:

/usr/local/primebase/setup/scripts

You have to install the new PrimeBase version 4.5.48 Compare the connect.def file from the package and add missing values in the connection definitions and remove the entries in your connect.def which are not longer used in the new release package. Update the file:

/usr/local/primebase/pbstab

and change the version number to 4548 for the pbac entry.

Update the admin console if you are using it.

Open a terminal, change to:

/usr/local/primebase/setup/scripts

start a “pbac” and choose connecting 1. Type in:

execute file "HTTPRequest.pbt";

This script will add new server and provider settings. A file “StartupCache.pbt” will be created in:

/usr/local/primebase/setup/scripts

which is necessary for the application. Quit the pbac again and login to the admin console. Check the new values in the server settings section:

  • CacheIntervall
  • ClientUsernameLength
  • Set UserNameCaseInsensitive to $true, if not already set
  • UserEmailUnique

Switch to the provider settings and check / set the following parameters:

  • API_ALLOW_CHECKSUMERR (might be necessary, if you use the API and didn’t send the checksum which was optional in the version 3.0.014 and which is now required; using this parameter you could disable the check again)
  • API_USE_SSL_FOR_HOST (if your hosting service offers HTTPS communication, you could enable SSL API communication for the admin console API requests)
  • ACTIVATION_DEFAULT_LANG (language settings for activation pages)
  • ACTIVATION_ALLOWED_LANG (language settings for activation pages)
  • CSV_IMPORT_ACTIVE (set to true if you use the CSV import)

Go back to the terminal and start a pbac again executing the script again and the “updateAllUsers”:

execute file "HTTPRequest.pbt";
TDNSConnect:updateAllUsers();

Mail templates

The name of the mail templates with “privacyinvited” or “privacyinvitedsecure” in the file name changed. Please rename your existing mail templates and add a “td3-” in front of the name. See the update package for an example.

Redirector page update

If it does not already exist, please add a “download” case in the redirector page which is necessary for the client update information (see Managing Updates and the Settings chapter in the Reference Guide).