This section explains how to upgrade an existing installation of SuperSERVER to Release 9.
To upgrade your SuperSERVER installation, you need to complete a number of tasks:
Step 1 - Read These Instructions In Full
Read these instructions in full before starting. In addition, we recommend you also review the following instructions before you start the upgrade process:
Step 2 - Schedule Service Outage and Advise Users
The upgrade will involve a service outage. You should plan carefully when to complete the upgrade and advise your users of the outage period when SuperSERVER will not be available.
Step 3 - Record SuperSERVER Startup Parameters
Make a note of any custom port or codepage settings you are using with your SuperSERVER deployment. By default:
- SuperADMIN uses ports 9230, 9231 and 9234.
- SuperSERVER listens on TCP/IP port 9232.
- Metadata Server listens on port 8005.
To find the ports and codepage settings in use on your system, do the following:
Login to the SuperADMIN console and type the command
Review the SuperSERVER log file: scsa.logs.txt. This will typically be located in C:\ProgramData\STR\SuperSERVER SA\logs (Windows) or STR/SuperSERVER_SA/logs (Linux).
Locate a line similar to the following, which indicates the port number (9232 in this example):
Metadata Server Port
If you are using Metadata Server, check what port it is using by reviewing its configuration file: metadata.config.xml. This will be located in C:\ProgramData\STR\SuperSERVER SA (Windows) or STR/SuperSERVER_SA (Linux).
The port number is indicated by the following line:
Review the SuperSERVER log file: scsa.logs.txt. This will be located in C:\ProgramData\STR\SuperSERVER SA\logs (Windows) or STR/SuperSERVER_SA/logs (Linux).
Locate a line similar to the following, which indicates the codepage (1252 in this example):
SuperSTAR 9 provides full unicode support. When you upgrade to version 9 or above, it will not be necessary to set the SuperSERVER codepage unless you need to support old SXV4s (generated prior to version 8) that use a different codepage to the current system locale. See Unicode for more details.
Step 4 - Export the Configuration Server Settings
In the SuperADMIN console, run the following command:
This command saves any configuration settings you have applied using the
cfg command in SuperADMIN. Replace
<filename> with the full path to a file on disk where you want to save the settings. Do not use quotes even if the path contains spaces.
After you run the command, check that the file has been created in the specified location. You will need to use this file in a later step to reimport your configuration settings.
Step 5 - Stop SuperSERVER and its Components
Before starting the upgrade, you must stop any of the SuperSERVER components if they are running, including:
- SuperADMIN Server
- SuperADMIN Console
- Metadata Server (if used)
- Tomcat (if used for SuperWEB2)
If you are upgrading a Windows installation, and SuperSERVER is running as a Windows service, go to the Services console and stop the service:
Step 6 - Backup the Current System
It is a good idea to take a complete backup of the host before proceeding. If it is not possible to take a complete backup, backup the SuperSTAR components described in Backup Strategy.
Step 7 - Copy SuperSERVER Files to a Temporary Location
For Windows deployments, copy the contents of the following directories (or the equivalent directories if you are not using the standard installation location) to a separate temporary location:
You will use these files to restore some of your previous configuration settings in a later step.
On Linux, move or rename the following directories:
This allows you to install the new version to the same location. You will use the existing files in a later step to restore some of your previous settings.
If you are using SuperWEB2, copy the Tomcat instance that hosts it and any configuration files that reside outside the Tomcat structure. If you have front-ended these products with Apache or IIS or similar, ensure that this configuration is also backed up.
Step 8 - Uninstall SuperSERVER (Windows Only)
If you are upgrading a Windows deployment, go to the Windows Control Panel and uninstall SuperSERVER (and SuperSERVICE Manager if it is installed).
Wait for the uninstall process to finish, then delete the following directories if they are still present on your system:
- C:\Program Files\STR\SuperADMIN
- C:\Program Files\STR\SuperSERVER SA
- C:\ProgramData\STR\SuperSERVER SA
Step 9 - Install SuperSERVER
Follow the installation instructions to install the new version of SuperSERVER:
On Windows, the installation process will automatically install and start the SuperSTAR Windows service. As described in the next step, you will need to stop this service before continuing with the upgrade process. As an alternative to allowing the installation process to start the service, and then stopping it, there is an option you can use in the installer that prevents it from starting the service:
- When you are prompted to select the install type, choose the Custom option.
When you get to the Select Features screen, select SuperSTAR Service and clear the Launch Service check box:
- Complete the rest of the install steps as normal.
Step 10 - Stop the SuperSTAR Service (Windows Only)
Unless you specifically selected the option not to start the service, the installation process will have automatically created and started the SuperSTAR service.
Go to the Windows Services console and stop the service:
It is very important to stop the service before proceeding. The remainder of the upgrade steps will not work correctly if the service is still running.
If you are upgrading from a version prior to 9.9 and you have allowed the service to start up, then this will affect the migration of your users and datasets. See the troubleshooting steps in Step 12 below for advice on resolving this.
Step 11 - Import Your Settings
The next step is to import your settings from the old deployment to your new SuperSERVER system.
Copy across your saved configuration settings as follows:
|Settings||What You Need To Do|
The configuration server was added in SuperSTAR 9.0. If you are upgrading from a version of SuperSTAR that is older than 9.0, then you will need to make a change to the administrationServerCatalog.xml file that you have just copied to C:\ProgramData\STR\SuperADMIN\server\data\.repository (Windows) or /STR/SuperADMIN/server/data/.repository (Linux) in your new installation, as this will have replaced the new version of the file that comes with the installation.
Compare the newly installed macros directory (either C:\ProgramData\STR\SuperADMIN\console\macros on Windows or /STR/SuperADMIN/console/macros on Linux) with your backed up copy of the old macros directory.
Copy any user-defined macros that appear in the backup but not in the new installation.
If required, copy your log files from the previous installation for reference and analysis. The log files are located in the following directories:
|CORBA Settings||If the server is multi-homed, verify that the CORBA files and settings are present and correct. See Multi-Homed Hosts for more information.|
If you were using any STR-supplied API plugins, copy these from the new version rather than reinstalling the previous version. The plugins must be copied to the same location as the SuperSERVER executable (scsa.exe). The default location is C:\Program Files\STR\SuperSERVER SA (Windows) or /STR/SuperSERVER_SA (Linux).
If you have written any custom API plugins you will also need to copy these back into the new installation.
|SuperADMIN Configuration for Secure LDAP||If you have implemented secure LDAP on your system, then you will have made changes to add additional properties to the SuperADMIN server.bat file. Reapply these changes to the instance of server.bat in your new installation.|
Compare the SuperSERVER configuration files saved from the previous installation with the configuration files installed by the new version. Modify the new files to reflect any configurations that you changed in the previous version.
This includes configuration files for logging, network properties, metadata configuration, search index construction, metadata database creation.
The default files and locations are:
You should also check files to which these utilities refer (for instance, the BuildMetadataTemplate script refers to databases.txt and metacolumns.txt in the same directory).
|Search Index||Following the upgrade, you should rebuild the search index for your datasets.|
|JDBC Drivers||Copy any JDBC drivers from the backup of the C:\Program Files\STR\SuperADMIN\server\lib\endorsed (Windows) or STR/SuperADMIN/server/lib/endorsed (Linux) directory. These drivers will be required if you are using a non-default RDBMS for the user catalogue.|
Step 12 - Verify the Installation
Start each component individually, so that you can check the startup messages and verify that everything is working correctly.
Start SuperADMIN Server first, and wait for it to start completely before starting SuperSERVER and any client applications.
You must run SuperADMIN Server and SuperSERVER as a user with permissions to write to the STR program data directories (such as an administrator user). On Windows, right-click the applications and choose the Run as administrator option from the menu.
Also start the Metadata Server if your installation requires it.
When all components have started, verify the basic functionality. For example, load one of the clients and confirm that you can log in and perform basic cross tabulations.
On Windows, when you are satisfied that the applications are working:
- Stop the components.
- Restart the Windows service.
- Load one of the clients and confirm that you can log in and perform basic cross tabulations.
Users and Datasets Missing?
If you find that none of your users or datasets are present following the upgrade, then this may be because the SuperADMIN service started up automatically when you installed SuperSERVER. If you are upgrading from a version earlier than 9.9 then SuperADMIN automatically migrates its datastore from XML to an RDBMS on first start. If the service started up before you had copied across your existing XML files then it will have migrated an empty catalogue. To resolve this, do the following:
Run the following command in SuperADMIN:
- Restart the SuperSTAR service.
Step 13 - Import the Configuration Server Settings
In the SuperADMIN console, run the following command:
This command loads the configuration server settings you saved in the earlier step. Replace
<filename> with the full path to the file on disk where saved the settings. Do not use quotes even if the path contains spaces.
Step 14 - Advise Users that Upgrade is Complete
Advise your users that the upgrade is complete.