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. Check the chapter :ref:`releasenotes-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 `` or ``pkill `` to terminate these, if they don't disappear shortly after you issued the stop commands. .. _createmysqlbackup: 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/setup/pbvm.env \ /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 installation instructions for the Registration Server and Administration Console outlined in the Registration Server Installation Guide: :ref:`enableyumrepo`, :ref:`installregserverpackage` and :ref:`installadminconsole`. 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 ``.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 243 Email Sender Address 245 Email Envelope Sender Address 244 Host Name 340 Protocol Log File /var/log/pbvm.log .. _update mysql table structures: 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 :ref:`dbconfigure` 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 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 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 Admin 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 chapter :ref:`adminconsoleconfig` for details. .. _update mail templates: Review/update the Email Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A new version of the Registration Server sometimes adds new mail templates and updates 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/``) 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 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 :ref:`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 it gets started automatically when the system reboots:: [root@regserver ~]# chkconfig | grep teamdrive td-regserver 0:off 1:off 2:off 3:off 4:off 5:off 6:off [root@regserver ~]# chkconfig teamd on [root@regserver ~]# chkconfig | grep teamdrive 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 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 :ref:`createmysqlbackup` 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/``) to the new installation and update the templates as described in :ref:`update mail templates`. There are a number of Provider specific HTML pages located in the directory ``activation`` in the Apache http Server's document root (usually ``/var/www/html``). These need to be copied to the new instance's document root file 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 :ref:`dbconfigure` and :ref:`adminconsoleconfig` in the *Registration Server Installation Guide*. (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 :ref:`update mysql table structures`. 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 setup/registration server upgrade to version 3.0.015: 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. .. _registration server setup/registration server upgrade to version 3.0.015/database schema update: 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; .. _registration server setup/registration server upgrade to version 3.0.015/reg server source update: 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 |pbversion| 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 |pbshortver| 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(); .. _registration server setup/registration server upgrade to version 3.0.015/mail templates: 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. .. _registration server setup/registration server upgrade to version 3.0.015/redirector page update: 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 :ref:`admin console/manage updates` and the *Settings* chapter in the *Reference Guide*).