Migrating/ Upgrading TeamSite Installations
Migrating TeamSite Installations
This article describes how to take an existing TeamSite installation and rebuild or replicate it on a new server or on a new TeamSite release. It describes particular compatibility issues with backing store migration and lists some of the configuration and customization information that needs to be copied. Although this document is meant to address migration issues across all the supported platforms, it also gives steps needed to migrate from old TeamSite 6.x on Linux or AIX to TeamSite 7.1 on Linux.
*Update August 4, 2017*
Note: This article has recently been reviewed keeping in mind TeamSite 8.x and 7.5 in mind. Most of the points still apply for newer versions of OpenText TeamSite
Upgrade vs. Migration
The simplest way to move to a newer TeamSite release is to perform an upgrade install.
However, there are often situations where you may want to start with a fresh installation or where an upgrade is not possible. For example, you may want to move a TeamSite installation to a different machine or OS. Or, you may want to replicate a test installation on a production machine. If you are moving to Teamsite 6.7 on Solaris 10, you will need to do a fresh install, because an upgrade install to Solaris 10 is not supported. Likewise, if you are moving from TeamSite 6.1 on Linux or AIX to TeamSite 6.7.1 on Linux, you will need to do a fresh install, because there is no supported upgrade install for 6.7.1 Linux. In such situations, you will need to move or copy over the backing store and may need to perform the migration steps, described in the backing store compatibility section.
In addition, changes in configuration and customization files will need to be brought over manually from the original installation. Some of these files are listed in the configuration section.
Backing Store Compatibility
Compatibility across releases
Backing stores are substantially upward-compatible. For the most part, you can take a store from an older release of TeamSite and activate it on a newer release. This has been true since TeamSite 5.5.0. However, there are a number of changes across the releases that require modifications or fix-ups to the backing store.
Backing stores are not downward-compatible: you cannot take a store that has been running on a newer release of TeamSite and run it on an older release. (Service pack upgrades and patches don’t count; you can uninstall a service pack or patch without affecting the usability of the backing store.) The TeamSite server checks backing store version numbers to enforce this.
The following sections describe several changes that require a modification or conversion step you need to make to a backing store, in order to move up to a particular TeamSite release.
In TS6.5.0, the search facility was introduced. In some cases, for installations with pre-existing backing stores from TS6.1 or earlier, the initial indexing phase of search would put undue stress on the TeamSite server’s memory utilization. If these backing stores contain editions with large enough directories, the server would run out of memory during indexing (at around 2GB on Solaris and 1.5GB on Windows) and crash.
Luckily, TS6.5.0 also introduced a more compact representation of directory metadata in the backing store. This compact format consumes much less process memory, so search indexing of 6.5 stores do not cause the server to run out of memory and crash.
However pre-6.5 backing stores need to be converted to the more compact representation before search can be enabled safely. This is done by temporarily reducing the cache size to 500 and running iwmigrate.
Note that starting TS version 7.1, the Lucene based search engine has been replaced by Autonomy IDOL Search Server. So, the indices are maintained on a separate server – the TS Search server. This means there is no compatibility between old Search and post version 7.1 search.
Running iwmigrate can be a lengthy process, potentially taking many hours, so plan accordingly.
Flex roles support
There are two new migration tools in 6.7.0 and future releases: iwusermigrate and iwaccessmigrate. These are used to convert user and role information for flex roles support.
Prior to 6.7.0, user and role information were defined in either .uid files – i.e. author.uid, editor.uid, admin.uid, and master.uid – or in attributes in LDAP, in the case where TeamSite is configured to use the ldap_roles key in iw.cfg. In new versions of TS (including version 7.4 and above) , the user information is read and recorded in the iw-home/conf/roles/tsusers.xml file, if ldap_roles is not set, and in the iwhome/ conf/roles/tsldapuserscache.xml file, if ldap_roles is set. In the latter case, when TeamSite is running, the tsldapuserscache.xml file is updated regularly based on the entries in LDAP.
Role-specific information is associated with particular branches in 6.7 and has been moved to the backing store. Each branch now contains a list of users and groups and the roles they have on that branch. The only role information read from tsusers.xml or tsldapuserscache.xml is whether or not a user is a master.
During an upgrade installation of 6.7.0 (or higher), the installer automatically runs the iwusermigrate clt to create the tsusers.xml or tsldapuserscache.xml file. After the installation completes, you then must manually run the iwaccessmigrate clt to generate the metadata in the backing store to associate users with particular roles on each branch, based on the roles and access rights they had prior to 6.7.0. The installer, before it exits, will prompt you to do this.
However, the installer will not run iwusermigrate and not prompt you to run iwaccessmigrate if it is performing a non-upgrade install. If you are manually migrating an installation, then you may need to copy over the .uid files from the previous installation and run the clts explicitly. If the TeamSite user information is in LDAP, then no files need to be copied, but the clts must still be run.
If you do not run iwusermigrate, no users will be able to log into TeamSite. If you do not run iwaccessmigrate, users will not have the same roles and access rights they had prior to TS6.7.
Similarly, after installation of TeamSite 6.7.0, 7.1 or higher, if you take a pre-6.7.0 backing store and activate it, you should run iwaccessmigrate or explicitly assign users to roles on the branches in the store. (See iwaccessmigrate description in The Command Line Tool Guide.) Running iwusermigrate or iwaccessmigrate usually takes only a few minutes.
In TS6.7.1 and future versions, the iwserver process was changed to run as the iwts user, instead of root, on UNIX platforms. This requires that all the files and directories in the backing store and some files under iw-home are accessible by iwts. During installation of TS6.7.1 (whether performing upgrade or new install), the migrate_non_root script is invoked to walk all the backing stores found and change ownership and permissions on the backing store files to allow iwts user access. (Note that this only affects backing store permissions; TeamSite users will not see files owned by iwts.) The script also takes care of changing ownership and permissions on the appropriate files in iwhome. After installation, if you take a pre-6.7.1 backing store and try to activate it on TS 6.7.1, you will get an error, unless you first reset permissions an ownership of the store. You do this by running
the following UNIX commands:
su – root
chown –R iwts bs_store_path
chmod –R +x bs_store_path
Do not run the migrate_non_root script, which is invoked by the installer, to reset permissions on the store. This script also modifies files in iw-home and elsewhere.
Running the migrate_non_root script during installation or running the UNIX chown and chmod commands on the backing store may be a moderately lengthy process. It can take a short number of hours to run over all the backing stores.
Compatibility across platforms
You cannot take a store from a TeamSite server on Windows, move it to TeamSite server on a UNIX system, activate it, and expect it to work. Similarly, you cannot move a store from a UNIX system to Windows. That’s because the format of the access control information for files and folders is very different between a Windows backing store and a UNIX backing store. On Windows, this information corresponds to Windows security descriptors and ACLs, while on UNIX, this information corresponds to UNIX file modes (e.g. 0775). However you can take a store from a TeamSite server on any UNIX platform (Solaris, Linux, and AIX), move it to another TeamSite server on any other UNIX platform, activate it, and expect it to work, within the release constraints described above and as long as the user ids and group ids are the same. If user and group ids cannot be made to match up, then you must use iwidmap to change the id values to the correct ones.
Likewise you can take a store from a TeamSite server on Windows and move it to another Windows platform, within the release constraints described above. Since the values of SIDs assigned to local users and groups are always different from machine to machine, you must run iwidmap to replace the original SID values for your users and groups.
Configuration and customization files
Changes in configuration and customization files will need to be brought over manually from the original installation. In some cases, such as for iw.cfg, you may need to merge changes made in the source file into the destination file, instead of overwriting it. Exactly which files need to be copied or merged will differ from one installation to another, because of variations in the level of configuration and customization among customers. In most cases, this process should be done manually and with care, and you should compare the source file with the destination file, if it exists, so that you do not unintentionally overwrite new configuration information at the destination site.
Here is a partial list of such files on a UNIX platform:
|/etc/iw.cfg||Specifies most of the settings of theTeamSite|
|/etc/defaultiwhome||Describes the location of the TeamSiteapplication software. The default location is/usr/iw-home.|
|/etc/defaultiwstore||Describes the location of the TeamSite ContentStore directory. The default location is/usr/iw-store.|
|/etc/defaultiwmount||Describes the location of the TeamSite virtualmount point. The default location is /iwmnt.|
|/etc/defaultiwlog||Describes the location of the iwserver.logfile. The default location is/var/adm/iwserver.log.|
|/etc/defaultiwelog||Describes the location of the iwevents.logfile. The default location is/var/adm/iwevents.log.|
|/etc/defaultiwtrace||Describes the location of the iwtrace.logfile. The default location is/var/adm/iwtrace.log.|
|iw-home/iw-samba/lib/iw.smb.conf||Contains Samba configuration.|
|iw-home/local/config/submit.cfg||Specifies all file permissions that areautomatically changed at submit time.|
|iw-home/local/config/autoprivate.cfg||Specifies what types of files are automaticallymarked private.|
|iw-home/local/config/file_encoding.cfg||Contains rules that determine the characterencoding of the contents of files that do notspecify their encoding. See Specifying ContentEncoding for information about creating these|
|iw-home/local/config/templating.cfg||Specifies the forms that are used in whichTeamSite areas and how the forms map topresentation templates as well as setting formdisplay options.|
|iwhome/conf/roles/tsldapuserscache.xml||Contains TeamSite users from LDAP files.|
|xmlContains TeamSite users from LDAP files.iw-home /conf/roles/roles.xml||Contains information on operations performed byeach role, as set through the Edit Roles screen.|
|iw-home/conf/tsgroups.xml||Contains information on TeamSite groups.|
|iw-home/local/config/transform.cfg||Configures Content Transformation Services.|
|iwsearch-home/etc/search.properties||Configures the index server and search server.|
|iwsearch-home/etc/branches.cfg||Lists the branches to be indexed by the index|
|iwsearch-home/etc/FieldMapping.xml||Defines extended attributes and templatingattributes to be indexed.|
|iw-home/tsreport/conf/tsreport.xml||Configures the EAs to be used by TeamSite|
|iw-home/eventsusbystem/conf/jmsconfignew.xml||Configures the Event Subsystem.|
|iw-home/etc/iwutild.cfg||Configures commands for the utility service.|
|iw-home/local/config/datacapture.cfg||Defines rule sets for capturing metadata or|
|iw-home/local/config/metadatarules.cfg||Provides information on mapping vpaths to datacapture rules.|
|iw-home/local/entities||Specifies user preferences. Note that the hostname is in some of the path components in theentities files, so that this information may needto be reset when migrating to machines with
|iw-home/cssdk/cssdk.cfg||Specifies settings for Content Services.|
Migrating from 6.x Linux/AIX to 7.1 Linux
There is no upgrade install for TS7.1 Linux, so any migration must be manual. Here are the general steps:
1. Stop TeamSite on the source system (/etc/init.d/iw.server stop).
2. Copy the source backing store to the target system (or a location accessible to the target system, e.g. a netfiler).
3. Make sure any local users/groups, present in backing store, are added to the target
machine – with the same UID/GID – *before* installing TeamSite. (This will eliminate
any chance of ID collisions with local users and groups created by TeamSite 7.1, like
iwts and iwglobal.)
4. Install 7.1 on the target system.
5. When prompted for location of <iw-store>, specify location of the backing store copied
in step 2.
6. After install, copy .uid files to <iw-home>/conf/roles (unless TeamSite is configured to
use the ldap_roles key in iw.cfg).
7. Stop TeamSite (/etc/init.d/iw.server stop).
8. Run `<iw-home>/bin/iwusermigrate`.
9. Restart TeamSite (/etc/init.d/iw.server start).
10. Run iwaccessmigrate CLT according to the documentation.
11. Sanity-check that Teamsite is running properly.
12. Stop TeamSite (/etc/init.d/iw.server stop)
13. Copy or merge in any other changes from configuration files and customizations from the source system.
14. Restart TeamSite (/etc/init.d/iw.server start).
15. Run iwmigrate if needed for enabling search.
Note : Like with most application migrations, the steps above are only for the raw server migration. There may be many other business and application logic migration considerations that are typically necessary. It is imperative that upgrades and migrations of TeamSite server be performed by professionals who have experience in these migrations. Autowoven professional services have performed several TeamSite and LiveSite upgrades and can help you achieve your upgrade goals faster.