Migration Utility

This Utility can be used for migrating from a lower version of HOD to a higher version. Host On-Demand migration is a two-step process:

Exporting the files from the source HOD server (HOD11 onwards). This process will create the Migrationpackage.zip file
Importing the exported files to the target HOD server. This process will import the files from Migrationpackage.zip file to target HOD server (HOD12 onwards)

HOD source and target server can be on the same machine or a different machine.

Note: If HOD Source and target server are on different machines then Migrationpackage.zip file created in the export operation must be placed in the target machine (This is a manual process that the administrator has to take care of)

Allowed Host On-Demand migrating versions and environments

Host On-Demand migrating versions

HOD11 to HOD12, HOD13
HOD12 (lower version) to HOD12 (higher version)
HOD12 to HOD13, HOD 14, HOD 15
HOD13 to HOD14, HOD 15
HOD 14 to HOD 15

Host On-Demand migration supported environments

Win 7, Win 10 - 32 bit, 64 bit
Win 11
Windows Server 2012 and above
RHEL 7.2 and above
AIX 7.2 and above
AS400 7.2 and above
Ubuntu 16.0.4 and above

Note: Export and Import operations are supported only on the same platform (e.g Windows to Windows, Linux to Linux etc.)

Location of HOD migration utility and installation

HODMigrationUtility.zip will be available on Fix central. Admin must download the zip file and place it in the Host On-Demand publish directory. There is no other installation that is needed.

Files available in the HODMigrationUtility.zip

Build.ID: contains the "buildid" that is HOD version and the build date
HODMigrationUtility.jar: Migration utility jar file
Export.xml: Input file required for "export" operation
Import.xml: Input file required for "import" operation

Steps to run the HOD migration utility

Unzip the HODMigrationUtility.zip file
Modify the contents of export.xml and import.xml file as needed. Refer to "5 .Export and Import input files" section below to understand what inputs are needed
Open a command prompt and navigate to the directory where HODMigrationUtility.jar file is available.
e.g cd C:\Program Files (x86)\IBM\HostOnDemand14\HOD14\HODMigrationUtility
Provide command to run migration operation
Export operation: java -jar HODMigrationUtility.jar c:\Test\Export.xml
Note: Once the export operation is completed, a completion message will be displayed along with the location where migration package zip file is created
Import operation: java -jar HODMigrationUtility.jar c:\Test\Import.xml
Note: Once the import operation is completed, a successful message will be displayed.
Rollback operation: java -jar HODMigrationUtility.jar c:\Test\Rollback.xml
Note: Rollback xml file gets generated automatically after an import operation is performed. Rollback can be performed only once

Note: Users must add JAXB jars to the classpath if using JDK 11 or higher versions.

Export and Import input files

Export:

Table 1. List of input attributes for export and what they mean
Input attribute	Explanation
migrationInput	This is the root directory for the input xml file.
mode	This tag specifies the mode of operation. Input is mandatory for this tag. Input for this tag should be "export" (upper or lower case does not matter).
HODPublishDirectory	Specifies Host On-Demand publish directory Input is mandatory for this tag e.g. <HODPublishDirectory>C:\Program Files\IBM\HostOnDemand\HOD</HODPublishDirectory>
sourceMigratingPackage	Specifies location to save Migration package zip If not specified, the current location is used to save the Migration package zip. e.g. <migratingPackageLocation>C:\Test</migratingPackageLocation>
overWrite	Input is mandatory for this tag. Input "yes" (default): If the migration package already exists, utility will overwrite the existing package. Following message will be displayed. Migration Package already exists at : C:\Program Files (x86)\IBM\ HostOnDemand\HOD\HODMigrationUtility\MigrationPackage.zip Migration is overwriting the existing migration package. Migration package has been created successfully at... C:\Program Files (x86)\IBM\ HostOnDemand11\HOD11\HODMigrationUtility\MigrationPackage.zip Input "no": If the migration package already exists, utility will not create the migration package. Instead, the following message will be displayed. Migration Package already exists at.. : C:\Program Files (x86)\IBM\ HostOnDemand\HOD\HODMigrationUtility\MigrationPackage.zip Migration is terminated due to existing migration package. HOD Migration process Terminated.
customFiles	customFiles is the parent tag for fileLocation sub tags. If there are custom files (.kmp .bar .col .pmp,.mac) files saved in locations other than default location (user/HODObjs) those locations need to be provided in this tag so that files in those locations are also picked for migration. Each custom file location needs to be provided in the fileLocation tag. e.g. <customFiles> <fileLocation>C:\Test1</fileLocation> <fileLocation>C:\Test2</fileLocation> </customFiles> Refer to the table below for a list of files that will be exported into the migration package

Table 2. List of files covered by export operation
Files	Location	Files directly copied to target machine	Files modified by migration utility
Deployment wizard files
DW created html, z_*.html, _J2.html, .jnlp	HOD publish directory	No	All
Complete HOD Data folder .cf files wInfo.txt Policy.obj Preload.obj Params.txt udparams.txt	HOD publish directory HODData	Following files will be copied directly to target HOD server Policy.obj Preload.obj Params.txt	wInfo.txt .cf file udparams.txt
Custom files
Default Custom files	User directory HODObjs folder e.g.: C:\Users\<SystemUser>\HODObjs	Yes	None
User defined custom files	User defined location (Shared or network location)	Yes (customfiles folder will be created and all custom files will be copied)	None
Private Directory files
Private Files (All files and folders)	HOD Install directory private	Yes	None
Directory Utility
Sample.xml and user created .xml	HOD Install directory lib\samples\DirUtil	Yes	None
Security
HODSerKeyDb.kdb HODServerKeyDb.sth HODServerKeyDb.rdb	bin directory	Yes	None
WellKnownTrustedCAs.class WellKnownTrustedCAs.jks WellKnownTrustedCAs.p12	HOD publish directory	If a file with the same name already exists, it will not be copied to target HOD server	Conversion of .p12 to jks file
pdfpdt files
Printer Definition File: All the files	HOD publish directory/ pdfpdt	Yes	None
Property file
Config.properties	HOD publish directory	Yes	None

Table 3. List of input attributes for Import and what they mean
Input attribute	Explanation
migrationInput	This is the root directory for the input xml file.
mode	This tag specifies the mode of operation. Input is mandatory for this tag. Input for this tag should be "import" (upper or lower case does not matter).
HODPublishDirectory	Specifies Host On-Demand publish directory Input is mandatory for this tag e.g. <HODPublishDirectory>C:\Program Files\IBM\ HostOnDemand\HOD</HODPublishDirectory>
migratingPackageLocation	Specifies location to save Migration package zip If not specified, the current location is used to save the Migration package zip. e.g. <migratingPackageLocation>C:\Test</migratingPackageLocation>
systemJavaBinDirectory	Specifies z/OS and AS/400 system java bin folder This tag input required only for z/OS and AS/400 OS e.g. <systemJavaBinDirectory>>/usr/lpp/javapkg/ J6.0/bin</systemJavaBinDirectory>
options	options tag is the parent tag to provide input for following child tags. Terminal, FileTransfer, Icon, FTPTerminal, dbaOptions, targetUI These tags need to be provided in the following format: <Terminal key="" value=""/> <FileTransfer key="" value=""/> <FTPTerminal key="" value=""/> <dbaOptions key="" value=""/> Above mentioned tags are related to session parameter Security related parameters can also be specified to convert SSL3 to JSSE TLS1.2. This needs to be set under Terminal tag Input for these tags is key and value in double quotes e.g. <Terminal key="LUName" value="abc"/> Key should not be null, value can be null These key value pairs will be written to the cf file on the target system of the corresponding sessions To provide more than one session parameter, tag has to be repeated with different key and value pair. e.g. <Terminal key="LUName" value="abc"/> <Terminal key="History" value="false"/> <Terminal key="fontStyle" value="0"/>
targetUI	HTML file look and feel of HOD 11 and HOD12 /HOD13/HOD14 is different. HOD12, HOD13 and HOD14 has the "Nimbus" look and feel for HTML files. Input "yes" (default): All the migrating HTML files will get the Nimbus look and feel in their UI. Input "no": To retain the source UI look and feel for HTML files.
codebase	Input is mandatory for this tag. This codebase is required for webstart client pages. The URL that you specify here must identify the target Host On-Demand publish directory. e.g. <codebase>http://server_name.mycompany.com/ hodalias</codebase> where server_name.mycompany.com is the name of the server on which Host On-Demand is installed, and hodalias is the Host On-Demand publish alias.
targetBackup	Input is mandatory for this tag. Input "yes" (default): Backup file will be created for the target Host On-Demand server files. The target Host On-Demand server where import will be run, files are backed up before running the Import - refer to the table below for a list of files that will be backed up Input "no": Backup file will not be created for migrating Host On-Demand server files.
overwriteHODPublishDirectory	Input is mandatory for this tag. Input "yes" (default): Files with same name (source and target files) will be overwritten in the target HOD server in publish directory Input "no": Files with same name (source and target files) will not be overwritten in publish directory, only new files or directories will be migrated to target
overwritePrivate	Input is mandatory for this tag. Input "yes" (default): Files with same name (source and target files) will be overwritten in the target HOD server in private directory Input "no": Files with same name (source and target files) will not be overwritten in private directory, only new files or directories will be migrated to target
overwritePdfPdt	Input is mandatory for this tag. Input "yes" (default): Files with same name (source and target files) will be overwritten in the target HOD server in pdfpdt directory Input "no": Files with same name (source and target files) will not be overwritten in pdfpdt directory, only new files or directories will be migrated to target
overwriteDirUtil	Input is mandatory for this tag. Input "yes" (default): Files with same name (source and target files) will be overwritten in the target HOD server in DirUtil directory Input "no": Files with same name (source and target files) will not be overwritten in DirUtil directory, only new files or directories will be migrated to target

Table 4. List of files in the Target directory that will be backed up
Folder	Files
Private Directory	All the files and directories
Bin directory	HODServerKeyDb.kdb , HODServerKeyDb.sth, HODServerKeyDb.rdb, HODServerKeyStore.jks
HOD publish directory->pdfpdt	Printer Definition File
HOD publish directory	WellKnownTrustedCAs.class WellKnownTrustedCAs.jks WellKnownTrustedCAs.p12 CustomizedCAs.p12 CustomizedCAs.jks CustomizedCAs.sth Config.properties Deployment Wizard Files
lib folder	redir.properties
lib\samples\DirUtil	All the files
HostOnDemand\HOD\HODData	All folders and files

Background information about Import operation

Custom files (both default and those provided in the export xml) will get imported.
- Custom File Location: /lib/CustomFiles/
- Default File location: System user/admin/HODObjs/
Security keystore will get imported if doesn't exist in target.
- If only P12 and KDB keystore exist on the target then, P12 and KDB from source system gets converted to JKS.
- If target already consists of JKS, P12 and KDB then the import will ignore all the keystores. The keystore on the target will be left intact.
Import Summary.
- Successful import process will create
  1. ImportSummary.txt under current directory
  2. .importSuccess under /lib/.importSuccess
- If import process is tried a second time, then on the console, a message will be displayed.
```
Files from a source HOD server were already migrated to target. C:\lib\.importSuccess. HOD Migration process Terminated.
```
- ImportSummary.txt will have report of imported files from source to target.
Rollback
- If there are any errors/exceptions in the import process or any abnormal condition happens, then Rollback is run automatically
- Rollback will be performed for the current target server. Whatever backup got created from target, all those all file are reverted back to their previous state.
- Import process will generate Rollback.xml in the current directory. On the console, a message will be displayed
```
Rollback File created in current directory to perform rollback. C:\Test\Rollback.xml
```
- .rollback file gets created in lib folder
- Generated Rollback.xml will get utilized to run rollback process only once.
- Every directory where backup has been taken, there will be an extra file by name .checkSumTemp that will be created and an entry will be added to /lib/ImportDirectory.txt. After rollback is completed, .checkSumTemp file gets deleted.
- Rollback process can also be run manually using the generated rollback.xml. This will remove all imported files from current HOD directory and restore to the previous stage.
- After rollback is completed, timestamp of the file will also gets changed not just content.
- After successful rollback, rollback process will generate a file by name .rollbackSuccess in /lib folder
- After successful rollback, if rollback process is manually tried again, a message will be displayed on the console.

Points to remember

Host On-Demand services should be stopped while running the migration utility. After completion of migration process, Host On-Demand services should be restarted.
Never rename the "HODMigrationUtility.jar"
After migration following extra files will be created. This is for recording information to be used by the migration utility. Don't delete or tamper with these files: .rollback, .rollbackSuccess, .importsuccess, .checksumtemp, and ImportDirectory.txt.
HOD uninstall does not delete HODMigrationUtility.jar from HOD publish directory

Limitations

Post migration redirector IP needs to be updated in the target machine i.e. if the export consisted of redirector sessions, migration utility does not change the destination address for those sessions. Users need to manually change the destination address.
If users have Dynamic HTML override configured in their sessions, those settings will not be migrated. So it is not recommended to run Migration Utility if users have configured Dynamic HTML overriding.
Users using Programmable HOD also not recommended to run Migration Utility, for the same reason as above.
If location of Custom files is identical with just a difference of drive, post import, all the Custom Files will be merged and copied under one directory.

Pre-requisites

Source and target systems where the utility needs to be run should have installed java and java path should be set in environment variable.
All the directories of Host On-Demand should have full control access - this is especially needed for non-Windows servers.
If custom files are available in a shared directory or network location, then those locations should also be accessible.

Using Migration Utility for User Based Sessions in Host On-Demand:

Starting from version 14.0, Host On-Demand supports a managed model where users can connect to HOD sessions using the following two options:

HTML-based model: By creating html pages, adding sessions to these pages and then accessing these pages from browsers.
Note: HTML-based model allows user to change the session properties of all sessions together.
Configuration server-based model: By creating users, adding sessions to these users, and then login with the user's credentials to access the sessions.
Note: In the Configuration server-based model, users cannot change the session properties for all sessions using the 'html' parameter.

Refer to below steps to change session properties in the Cofiguration server-based model using Migration Utility:

Navigate to the HOD server location, and create a .properties file (e.g abc.properties).
Mention the session parameter which needs to be updated and provide the new value for this session parameter inside this .properties file.
Open the Command Prompt, and run the below command.
Syntax: java -jar MigrationUtility.jar <.properties file location>
Examlple: java -jar MigrationUtility.jar /test/abc.properties
Provide the required values for the below parameters when prompted:
- HOD publish directory
- Admin user name and password
After successful execution, the session properties for all sessions will get updated.

Limitations of Migration Utility to change Session Properties:

Currently, this utility works only for Display and VT sessions but not for the other session types such as Printer and FTP.
A user with the Admin role can run the Migration Utility.
If an Admin user runs this utility, it updates the session properties of all the sessions under all groups instead of changing the sessions under the Admin.