+

Search Tips   |   Advanced Search

Security Directory Integrator v7.2


Installation and Administrator Guide

  1. Introduction
  2. Before you install
    1. Disk space requirements
    2. Memory requirements
    3. Platform requirements
    4. Components in SDI
    5. Other requirements
    6. Root or Administrator Privileges
    7. Security Enhanced (SELinux)
    8. Authentication of AMC on Unix/Linux
    9. Graphics packages for UNIX systems
    10. Prerequisites for CE on AIX operating
    11. Prerequisite for upgrading from V7.1.1 to V7.2 on Windows 2012 operating system
    12. Installing SDI
    13. Launching the appropriate installer
    14. Using the platform-specific SDI installer
    15. Installing using the graphical installer
    16. Install Panel flow
    17. Uninstall Panel flow
    18. Add Feature Panel flow
    19. Migration Panel flow
    20. Installing using the command line
    21. Temporary file space usage during installation
    22. Performing a silent install
    23. Service name limitation on UNIX systems
    24. Post-installation steps
    25. CE Update Site
    26. Plug-ins
    27. Administration and Monitoring Console (AMC)
    28. Documentation
    29. Migration
  3. Installing local Help files
  4. Deploy AMC to a custom ISC SE or IBM Dashboard Application Services Hub

  5. Installing or Updating using the Eclipse Update Manager
    1. Post-installation steps
    2. Launching the uninstaller
    3. Performing a silent uninstallation
    4. Default installation locations

  6. Update Installer
    1. The .registry file
    2. HTTP Basic Authentication
    3. Lotus® Domino SSL specifics
    4. Certificates for the SDI Web service Suite
    5. Example Server certificate creation
    6. IBM WebSphere MQ Everyplace authentication

  7. Reconnect Rule Engine
    1. Introduction
    2. Reconnect Rules
    3. User-defined rules configuration
    4. Examples
    5. Exception considerations
    6. General reconnect configuration

  8. System Queue
    1. System Queue Configuration
    2. Apache ActiveMQ parameters
    3. Configuration
    4. Logging
    5. Using SSL with ActiveMQ
    6. IBM WebSphere MQ parameters
    7. Microbroker parameters
    8. JMSScript Driver parameters
    9. The env JavaScript object
    10. The ret JavaScript object
    11. JavaScript example
    12. System Queue Configuration Example
    13. Security and Authentication
    14. Encryption
    15. Authentication
    16. IBM WebSphere MQ Everyplace Configuration
    17. Authentication of IBM WebSphere MQ Everyplace messages to provide Queue Security
    18. Support for DNS names in the configuration of the IBM WebSphere MQ Everyplace Queue
    19. Configuration of High Availability for IBM WebSphere MQ Everyplace transport of password
    20. Providing remote configuration capabilities in the IBM WebSphere MQ Everyplace Configuration Utility

  9. Encryption and FIPS mode
    1. Configure SDI to run FIPS mode
    2. Symmetric cipher support
    3. FIPS encryption
    4. Connectors, Function Components, Parsers
    5. The SDI server and FIPS
    6. Configure SSL and PKI certificates
    7. Encrypting and decrypting using CryptoUtils
    8. Working with certificates
    9. Comparing CA-signed and Self-signed certificates
    10. Configure certificates using PKI and SSL
    11. Using cryptographic keys located on hardware devices
    12. Using IBMPCKS11 to access devices and to store SSL keys and certificates
    13. Enable or disabling padding
    14. Maintaining encryption artifacts - keys, certificates,
    15. Changed encryption key
    16. Changed password for encryption key or keystore
    17. Expired encryption certificate

  10. Configure the SDI Server API
    1. Server ID
    2. Exception for password protected Configs
    3. Server RMI
    4. Config load time-out interval

  11. Properties
    1. Working with properties
    2. Migrating using properties and the tdimiggbl tool
    3. Global properties
    4. Solution properties
    5. Java properties

  12. System Store
    1. Property stores
    2. Password Store
    3. User property stores
    4. Third-party RDBMS as System Store
    5. Oracle
    6. MS SQL Server
    7. IBM DB2 for z/OS
    8. DB2 for other OS
    9. IBM solidDB
    10. Using Derby to hold your System Store
    11. Configure Apache Derby Instances
    12. Starting Apache Derby in networked mode
    13. Enable user authentication in System Store
    14. Create statements for System Store tables
    15. Backing up Apache Derby databases
    16. Troubleshooting Apache Derby issues

  13. Command-line options
    1. Configuration Editor
    2. Server
    3. Command Line Interface - tdisrvctl utility
    4. Command Line Reference
    5. Operations
    6. Other points to note

  14. Logging and debugging
    1. Script-based logging
    2. Logging using the default Log4J class
    3. Log Levels and Log Level control
    4. Log4J default parameters
    5. Create our own log strategies

  15. Tracing and FFDC
    1. Tracing Enhancements
    2. Understanding Tracing
    3. Configure Tracing
    4. Setting trace levels dynamically
    5. Useful JLOG parameters

  16. Administration and Monitoring
    1. Installation and Configuration
    2. Deploy AMC into the Integrated Solutions Console (ISC)
    3. Deploy AMC as a Windows service
    4. Deploy AMC on existing IBM WebSphere Application Server
    5. Starting the Administration and Monitoring Console and Action
    6. Enable AMC
    7. Running Action Manager remotely
    8. AMC and Action Manager startup
    9. AMC and Derby shutdown
    10. Action Manager remote startup
    11. Action Manager shutdown
    12. AMC Logs
    13. Console user authority
    14. Administrator and the iscadmins group
    15. Action Manager
    16. Enable Action Manager
    17. Action Manager status in real time
    18. AMC force trigger for a given rule
    19. AMC and Action Manager security
    20. Introduction
    21. AMC and remote SDI server
    22. AMC and role management
    23. AMC and passwords
    24. AMC and encrypted configs
    25. Administation and Monitoring Console User Interface
    26. Log in and logout of the console
    27. AMC Console Layout
    28. Logging off the console
    29. Using AMC tables

  17. Select action drop-down menu
    1. Paging
    2. Sorting
    3. Finding
    4. Filtering
    5. Servers
    6. Add a server
    7. Modify a server
    8. Console Properties
    9. General
    10. SSL
    11. JDBC Properties
    12. Solution Views
    13. Configure ACLs
    14. Local variables
    15. Add a Solution View
    16. Config files (allows loading/reloading of configurations)
    17. Custom load
    18. Monitor Status and Action Manager
    19. Monitor Status
    20. Solution View Details
    21. Server Information
    22. View Components
    23. Show Preferred Solution Views
    24. Refreshing Solution View Details in AMC
    25. Action Manager
    26. Add/Edit configuration rules
  1. Configured actions
    1. Add/Modify Action
    2. Substitute variable for event data
    3. View Rules Summary
    4. Property Stores
    5. Select Solution View
    6. Solution Properties
    7. Global Properties
    8. Java Properties
    9. System Properties
    10. Password Store
    11. User Property Store
    12. Log Management
    13. Preferred Solution Views
    14. AMC and AM Command line utilities
    15. Example walkthrough of creating a Solution View and Rules
  2. Touchpoint Server
    1. Touchpoint concepts
    2. Touchpoint Server
    3. Touchpoint Provider
    4. Uninstalling
    5. XML Schema locations
    6. Error flows
    7. Configuration
    8. Authentication
    9. Examples
    10. Shipped example
    11. Example steps for creating a Touchpoint Instance using a JDBC Connector
    12. Provider Touchpoint Instance
    13. Initiator Touchpoint Instance
    14. Intermediary Touchpoint Instance

  3. Tombstone Manager
    1. Introduction
    2. Configure Tombstones
    3. Configuration Editor Configuration screen
    4. AssemblyLine Configuration screen
    5. The Tombstone Manager
    6. Tombstone Manager

  4. Multiple SDI services
    1. Introduction
    2. Installing and uninstalling the service
    3. Installing the service
    4. Uninstalling the service
    5. Starting and stopping the service
    6. Manual start and stop
    7. Changing service startup type
    8. Logging
    9. Configure the service
    10. SDI as Linux/UNIX Service
    11. Deployment methods
    12. Tailoring /etc/inittab
    13. SDI as z/OS Service
    14. SDI as i5/OS™ Service
    15. Command line support

  5. Appendix A. Example Property files
    1. Log4J.properties
    2. jlog.properties
    3. derby.properties
    4. global.properties

  6. Appendix B. Monitoring with external tools
    1. Monitoring SDI with ITM
    2. Short presentation of the ITM architecture
    3. Importing an existing Agent configuration in ITM Agent Builder
    4. Configuring the ITM Agent
    5. Monitoring SDI data
    6. Defining thresholds
    7. Create links between tables
    8. Purpose of links
    9. Construction of links
    10. Send custom notifications to ITM
    11. Limitations
    12. Monitoring SDI using OMNIbus
    13. Introduction
    14. Configure the EIF probe props file
    15. Determine the severity for the events
    16. Working with the EventPropertyFile.properties file
    17. Send custom notifications to OMNIbus

  7. Appendix C. NIST SP 800-131A specifications
    1. Installing fixes
    2. Rollback
    3. Troubleshooting

  8. Supported platforms

  9. Migrating
    1. Migrate files to a different location
    2. Which files do not need to be modified to be used in another location?
    3. Which files need to be modified before they can be used in another location?
    4. Which files should not be used in another location under normal circumstances?
    5. Migrating files that contain encrypted data

  10. Migrate files to a newer version
    1. Installer-assisted migration
    2. Tool-assisted migration
    3. Manual migration
    4. Backing up important data
    5. Files backed up by the Installer
    6. Upgrade from version 6.0 to 7.1
    7. Backup tools
    8. Manual backup

  11. Migrating AMC 7.x configuration settings to another AMC deployment
    1. Converting from EventHandlers to corresponding AssemblyLines
    2. TCP Server Connector
    3. Mailbox Connector
    4. JMX Connector
    5. SNMP Server Connector
    6. IBM Security Directory Server Changelog Connector
    7. HTTP Server Connector
    8. LDAP Server Connector
    9. Sun Directory Change Detection Connector
    10. Active Directory Change Detection Connector
    11. z/OS LDAP Changelog
    12. DSMLv2SOAPServerConnector
  12. Migrating BTree tables and BTree Connector to System Store
  13. Migrating Cloudscape database to Derby
  14. Migrating global and solution properties files using migration
  15. Migrating Password plug-ins properties files using migration tool

  16. Security
    1. Introduction

  17. Manage keys, certificates and keystores
    1. Background
    2. Public/private keys and certificates
    3. Secret keys
    4. Keystores
    5. Keys for SSL
    6. Keys for encryption
    7. Tools
    8. List the contents of a keystore
    9. Create keys

  18. Secure Sockets Layer (SSL) Support
    1. Server SSL configuration of SDI components
    2. Client SSL configuration of SDI components
    3. SSL client authentication
    4. SDI and Microsoft Active Directory SSL configuration
    5. Summary of properties for enabling SSL and PKCS#11 support
    6. SSL example
    7. SDI component as a server
    8. SDI component as a client

  19. Remote Server API
    1. Introduction
    2. Configure the Server API
    3. Remote Server API access on a Virtual Private Network
    4. Server API access options
    5. Server API SSL remote access
    6. Using Server API specific SSL properties
    7. Using the standard SSL Java System properties
    8. Server API authentication
    9. Local client session
    10. Remote client session
    11. JAAS authentication
    12. SSL-based authentication
    13. Username/password based authentication
    14. Authentication hook
    15. LDAP Authentication support
    16. LDAP Authentication Configuration
    17. LDAP Authentication Logic
    18. LDAP Group Support
    19. Host based authentication
    20. Summary of Server API Authentication options
    21. Server API JMX layer does not support username and password authentication
    22. Server API authentication setup examples
    23. Server API Authorization
    24. Authorization roles
    25. Server API User Registry
    26. Server Audit Capabilities
    27. Auditing scope
    28. Suppression of notifications
    29. Sending notifications

  20. SDI Server Instance Security
    1. Stash File
    2. Server Security Modes
    3. Working with encrypted SDI configuration
    4. Introduction
    5. Separation of certificates for PKI Encryption and SSL
    6. Create an encrypted SDI configuration file from scratch
    7. Using the cryptoutils command line tool
    8. Editing an encrypted SDI configuration file
    9. Standard SDI encryption of global.properties
    10. Encryption of properties in external property files
    11. The SDI Encryption utility - cryptoutils
    12. SDI System Store Security

  21. Miscellaneous Config File features
    1. The "password" configuration parameter type
    2. Component Password Protection
    3. Saving passwords to configured Properties
    4. Protecting attributes from being printed in clear text during
    5. Encryption of SDI Server Hooks
    6. Remote Configuration Editor and SSL
    7. Using the Remote Configuration Editor
    8. Summary of configuration files and properties dealing with security
    9. Miscellaneous security aspects


Introduction

For an overview of the general concepts of the Security Directory Integrator v7.2, refer to "SDI concepts," in SDI v7.2 Users Guide.

For more detailed information about SDI v7.2 concepts, see SDI v7.2 Reference Guide.

SDI v7.2 Editions

The SDI v7.2 exists in two different editions (for which different licensing agreements apply):

Unlike earlier versions of SDI, in v7.2, both the General Purpose Edition and the Identity Edition are identical in their content, functionality, and capabilities. They only differ in their licensing agreements.


Installation instructions for SDI

Before you install

The SDI v7.2 installer uses the InstallAnywhere 2012 SP1 technology. Before you install, read the following sections and make sure your system meets the minimum requirements.

Disk space requirements

See the Software requirements in the SDI documentation at http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topsysreqs.html.

Memory requirements

See the Software requirements in the SDI documentation at http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topsysreqs.html.

Platform requirements

See the Software requirements in the SDI documentation at http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topsysreqs.html.

Components in SDI

With some exceptions, the following components are available and selectable for installation as part of SDI v7.2:

Additional components automatically installed that are not selectable:

Other requirements

Root or Administrator Privileges

Note the following differences when installing SDI with administrator as opposed to non-administrator privileges:

Security Enhanced (SELinux)

RedHat Linux (RHEL) has a security feature known as Security Enhanced Linux or SELinux. SELinux provides security that protects the host from certain types of malicious attacks. RHEL version 5.0 defaults SELinux to enabled. The RHEL 5.0 SELinux default settings have been known to prevent Java™ from running properly. If you try to run the RHEL 5.0 SDI installer, an error resembling the following output may display: 

# ./install_sdiv72_linux_x86_64.bin

Initializing Wizard........
Verifying JVM...

No Java Runtime Environment (JRE) was found on this system.

The reason for this error is that the Java Runtime Environment (JRE) that InstallAnywhere 2012 SP1 extracts to the /tmp directory does not have the required permissions to run. To avoid this error:

  1. Disable SELinux: setenforce 0.
  2. Run the SDI installer.
  3. Enable SELinux again: setenforce 1.

We can also edit the /etc/selinux/config configuration file to enable and disable SELinux. The default settings for the /etc/selinux/config file resemble the following lines: 

# This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#	enforcing - SELinux security policy is enforced.
#	permissive - SELinux prints warnings instead of enforcing.
#	disabled - SELinux is fully disabled.
SELINUX=enforcing
# SELINUXTYPE= type of policy in use. Possible values are:
#	targeted - Only targeted network daemons are protected.
#	strict - Full SELinux protection.
SELINUXTYPE=targeted

Modifying SELINUX to either SELINUX=permissive or SELINUX=disabled allows the SDI installer to run. However, both modifications of the SELINUX property, to either SELINUX=permissive or to SELINUX=disabled, affect the level of security for the host.

The SDI installer uses a JRE located at install_dir/jvm that cannot run with the SELinux default settings. The installer makes a best effort to avoid the problems with the SELinux default settings by trying to change the SDI JRE security permissions that are blocking the installer. The SDI installer issues a command that changes the security permissions for the SDI JRE so that it can run. The SDI installer issues the following command: 

chcon -R -t textrel_shlib_t install_dir/jvm/jre

Note: If the installer cannot issue the chcon command, or if there is an error when issuing the command, you must edit the permissions manually.

Errors that resemble the following output indicate that the chcon command did not work: 

[root@dyn9-37-225-164 V7.2]# ./ibmdisrv 
Failed to find VM - aborting 

[root@dyn9-37-225-164 V7.2]# ./ibmditk
Failed to find VM - aborting

[root@dyn9-37-225-164 V7.2]# bin/amc/start_tdiamc.sh
Failed to find VM - aborting

Authentication of AMC on Unix/Linux

On some UNIX platforms the Administration and Monitoring Console (AMC) in ISE SE fails to authenticate users, even when correct credentials are specified. Such behavior is observed when AMC is run as a non-root user and the operating system uses a password database (for example, a /etc/shadow file). For more information on this issue, and for a workaround see "Authentication failure on UNIX when LWI runs as non-root user" in SDI v7.2 Problem Determination Guide.

Graphics packages for UNIX systems

If the required graphics packages are not installed on UNIX systems, the following error might occur later when you run the ibmditk command to start the Configuration Editor: 

No fonts found; this probably means that the fontconfig library is not correctly configured. 
You may need to edit the fonts.conf configuration file. 
More information about fontconfig can be found in the fontconfig(3) manual page 
and on http://fontconfig.org

To avoid such errors complete the following steps:

  1. Ensure that the following graphics packages are installed on UNIX systems:

    • libgtk-x11-2.0.so.0
    • libgthread-2.0.so.0

  2. Run the following command: 
    export LD_LIBRARY_PATH=/usr/sfw/lib/:/usr/lib:/lib
  3. Install or ensure that the following file is installed: 
    /etc/fonts/fonts.conf
  4. Run the following command: 
    export FONTCONFIG_PATH=/etc/fonts

Prerequisites for CE on AIX operating system

When the CE is installed as a plug-in in Eclipse on an AIX® operating system, it does not launch and creates a log file.

To use the CE, the gtk+ RPM and dependencies must be available on AIX. Install the following RPMs on AIX: 

atk-1.12.3-2.aix5.2.ppc.rpm
cairo-1.8.8-1.aix5.2.ppc.rpm
expat-2.0.1-1.aix5.2.ppc.rpm
fontconfig-2.4.2-1.aix5.2.ppc.rpm
freetype2-2.3.9-1.aix5.2.ppc.rpm
gettext-0.10.40-6.aix5.1.ppc.rpm
glib2-2.12.4-2.aix5.2.ppc.rpm
gtk2-2.10.6-4.aix5.2.ppc.rpm
libjpeg-6b-6.aix5.1.ppc.rpm
libpng-1.2.32-2.aix5.2.ppc.rpm
libtiff-3.8.2-1.aix5.2.ppc.rpm
pango-1.14.5-4.aix5.2.ppc.rpm
pixman-0.12.0-3.aix5.2.ppc.rpm
xcursor-1.1.7-3.aix5.2.ppc.rpm
xft-2.1.6-5.aix5.1.ppc.rpm
xrender-0.9.1-3.aix5.2.ppc.rpm
zlib-1.2.3-3.aix5.1.ppc.rpm

Note: The installed RPMs must be the versions listed here because earlier or later versions may not be compatible.

To install these RPM versions, complete the following steps:

  1. Download the RPMs to a new directory. We can find the RPMs at ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/.
  2. Install the downloaded RPMs by using the following command. If an existing version of an RPM is already installed, the command upgrades or downgrades it to the downloaded version. 
    rpm -U *.rpm --force
  3. Verify that the environment variable LIBPATH contains a path to the closure of the libraries. For example: LIBPATH=/opt/freeware/64/lib/.

Prerequisite for upgrading from V7.1.1 to V7.2 on Windows 2012 operating system

If you are planning to upgrade SDI Version 7.1.1 to v7.2 on Windows 2012 operating system, then ensure that Windows 7 compatibility mode is enabled on the Version 7.1.1 uninstaller.exe before starting the v7.2 installer. For more information, see the technical note at http://www-01.ibm.com/support/docview.wss?uid=swg21634336.

Installing SDI

The SDI installer allows you to install SDI v7.2 in its entirety, only those SDI components that you need, upgrade a previous version of SDI (versions 7.0, 7.1, or 7.1.1), or add features to an existing SDI v7.2 installation.

Note:

When you choose to upgrade from a previous version, SDI v7.2 uninstalls the previous version; the uninstallation does not remove any files that the user has created. User created files are still available after the new installation completes. Configuration files such as global.properties and am_config.properties are migrated to SDI v7.2, keeping any custom configuration changes that have been made.

Note: Though the SDI installer backs up and restores some of the pre-defined configuration and property files, it is a good practice to also manually back up your files and databases that have critical data before starting the installation.

The SDI v7.2 installation continues to include the features available in previous versions of SDI:

Note: For the remainder of this Directory Integrator v7.2 Installation and Administrator Guide, the variable TDI_install_dir refers to the installation directory location chosen by the user on the Destination Panel during installation. See Default installation locations for information on where SDI is usually installed.

Launching the appropriate installer

We can launch the SDI v7.2 Installer by using one of the following methods:

Once you have launched the installer, you are ready to begin the process of Using the platform-specific SDI installer.

Using the platform-specific SDI installer

The platform-specific SDI installer is launched either from the Launchpad or from the command line. The SDI installer can be used to install a new copy of SDI, add a feature to an existing instance of SDI, or upgrade a previous version of SDI. The default install location on your computer for SDI varies with the platform.

During installation, the Installer will log its actions in files (sdiv72install.log and sdiv72debug.log) residing in the system’s temporary files directory, typically /tmp or /var/tmp on UNIX platforms.

Installing using the graphical installer

Install Panel flow

Uninstall Panel flow

Add Feature Panel flow

The Add Feature flow is similar to the new install flow. Only the unique panels will be shown here.

Migration Panel flow

The Migration flow is similar to the new install flow. Only the unique panels will be shown here.

Installing using the command line

The following command line options are supported by the SDI v7.2 installer:

The following command line option is unique to the SDI installation Wizard:

Temporary file space usage during installation

During installation, the installer may use a substantial amount of temporary file space in order to stage files. If your system is constrained in this regard, errors during installation might occur.

UNIX/Linux systems typically use /tmp or /var/tmp as temporary files storage, whereas on Windows, the temporary file storage area is found in the location pointed to by the environment variable TEMP.

InstallAnywhere installers can be instructed to redirect their temporary file usage by setting the environment variable IATEMPDIR before starting the installer. For example, on UNIX: 

export IATEMPDIR=/opt/IBM/TDI/temp

Then, start your console mode installers from the session in which you have set the IATEMPDIR variable.

Performing a silent install

To perform a silent installation first generate a response file. To generate this file, perform a non-silent installation with the -r option specified, for example: 

install_sdiv72_win_x86.exe -r Response File Name

The response file is created in the directory that you specify during installation.

Note: The directory TDI_install_dir/examples/install contains a number of example response files for various installation and uninstallation scenarios.

Once the response file is created, you can install silently using the following command: 

install_sdiv72_win_x86.exe -i silent -f Response File Name

Note: The examples in this document use the Windows platform installation executable file. See Launching the appropriate installer for a list of executable file names for each supported platform.

Service name limitation on UNIX systems

During silent installation of SDI on UNIX systems, ensure that the service name for SDI and AMC does not exceed the maximum length of 4 characters. This value is specified in the response file, examples\install\TDICustomInstallRsp_Unix.txt.

The silent installation fails if you specify a name that is longer than 4 characters, for example: 

TDI_SERVER_SERVICENAME=tdisrv_silent
TDI_AMC_SERVICENAME=tdiamc_silent

The log files, /tmp/sdiv72install.log and /tmp/sdiv72debug.log, report the following error: 

tdisrv_silent must be 4 characters or less.
A service already exists with that name or the name is invalid. 
UNIX based platforms, maximum 4 characters name is valid.

If this error occurs, you must edit the response file and change the values of the TDI_SERVER_SERVICENAME and TDI_AMC_SERVICENAME properties to be 4 characters or less.

Post-installation steps

CE Update Site

If the CE Update site was installed, you now have to manually deploy into Eclipse. See the section entitled Installing or Updating using the Eclipse Update Manager for more information.

Plug-ins

If any of the password synchronization plug-ins were installed, see the SDI v7.2 Password Synchronization Plug-ins Guide for information on how to deploy the plug-in code.

Administration and Monitoring Console (AMC)

General information

Bundled embedded web platform deployment

Customer or deferred deployment

Documentation

The documentation system used by SDI is the IBM Eclipse Help System. After you have done a default installation, this means that SDI v7.2 documentation is made available to you online, on the Web in the form of an Infocenter hosted by IBM. You may, however, choose to deploy the documentation locally. See Installing local Help files.

If you are new to SDI, we recommend that you read and step through the SDI v7.2 Getting Started Guide in order to get used to the concepts used.

If you have used earlier versions of SDI, then chapter 3 of the SDI v7.2 Users Guide will be very beneficial to you in order to understand the new IDE framework and layout. It will also explain how we can import and open your existing configurations; and how the Server still uses the Config model at runtime.

Migration

If you have installed an earlier version of SDI, then you will most likely need to migrate certain aspects of your previous deployment. More information on what to do in this case can be found under Migrating.

Installing local Help files

Note: This feature is deprecated and will be removed in a future version of SDI.

The SDI installer does not contain any user documentation, other than the Java™ API documentation, which can be displayed by selecting the Help -> Welcome screen, JavaDocs link in the Configuration Editor. IBM provides the user documentation in online form in the product documentation website at http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/topwelcome.html.

SDI is equipped with code1 to provide you with context-dependent online help that we can launch from the Configuration Editor (CE). By default, this code resolves the documentation from the online product documentation as referenced above. We can, however, install the documentation locally, such that you are not dependent upon the Internet to be able to read it.

These are the steps you must take to install documentation locally:

After installing the documentation in the plugins directory as outlined above, we can also decide to host the documentation on that computer for other installations of SDI in your environment. In the TDI_install_dir/ibm_help directory there are a number of .bat files (Windows) or .sh files (Unix/Linux) that enable you to do this.

Starting and stopping the local documentation task

You must first start a local task to serve the documentation.

1. The help system is powered by Eclipse™ technology. (http://www.eclipse.org)

Deploy AMC to a custom ISC SE or IBM Dashboard Application Services Hub

If you chose to defer deployment of AMC to ISC, and are now ready to deploy, follow these steps:

If you chose a custom IBM Dashboard Application Services Hub to deploy AMC to, and are now ready to deploy, follow this step:

Installing or Updating using the Eclipse Update Manager

The SDI Rich Client Platform contains a complete runtime environment to run the SDI CE. However, it is possible to install the SDI Eclipse plug-in into an existing Eclipse installation. This is done using the Eclipse Update Manager. In Eclipse, open the Eclipse Update Manager through the Help menu.

Before you have the SDI plug-in installed you will want to add a new update site. Choose the Add Site... button and specify the location of the update site.

Depending on the location of the update site choose the appropriate action. In this example we choose a directory on the local file system. Using the Local button you are prompted to choose a directory which is then filled into the location input field. When you press OK the new update site and updates should be available:

Check the plug-ins you want to install and press Install. As the software update manager updates your installation you may be prompted to confirm the installation and you are also usually encouraged to restart the workbench after installation. After installation is complete you should see SDI in the Installed Software tab.

Post-installation steps

When the CE is installed as a plug-in in another Eclipse installation like in the procedure described above, a number of specific properties must be set to include the SDI loader. The SDI loader is an org.eclipse.osgi fragment that provides class loading for the CE. 

# TDI class loader
osgi.framework.extensions=com.ibm.tdi.loader
osgi.hook.configurators.include=com.ibm.tdi.loader.TDIClassLoaderHook
TDI_HOME_DIR=c\:/Program Files/IBM/TDI/V7.2

Note that the property TDI_HOME_DIR needs to point to an existing SDI Server installation, since the CE must be able to query many SDI component Java™ classes in order to work correctly. This installation is also used to create the local development server that the CE uses. The fragment above shows the installation default for Windows; update this to reflect your environment.

There are several ways to set these properties. One is to update the configuration/config.ini file of the Eclipse installation.

Note: After installation and configuration of the CE into Eclipse, you may run into dependency problems. A Technote published about this issue may help you resolve such problems.

Launching the uninstaller

To uninstall SDI, first launch the uninstaller:

Note: Before uninstalling, stop any component that you intend to remove, for example an instance of the SDI Runtime, an AMC service that is running, or a Password Synchronization plug-in. Not stopping running components may cause some files to not be removed (to remain after the uninstallation). On Windows, a restart may be required and the SDI Web Admin (AMC) service may remain in the Services list, requiring manual deletion.

  1. Navigate to the SDI _uninst directory, for example: 
    install_path/_uninst
  2. Launch the uninstaller by executing the uninstall executable file.

    For Windows platforms, the uninstall executable file is called uninstaller.exe. For all other platforms, the uninstall executable file is called uninstaller.bin.

  3. You will now enter the Uninstall Panel flow.

Attention: During an uninstallation, a number of directories on the computer are emptied and removed. These are:

Anything you may have put into these directories yourself that matches any of these criteria, will be removed as well during an uninstallation.

Performing a silent uninstallation

To perform a silent uninstallation of SDI you must first generate a response file. To generate this file, you must perform a full GUI or console uninstallation with the -options-record option specified; for example: 

TDI_install_dir/_uninst/uninstaller.exe -r UninstallResponseFileName

The response file is created in the directory that you specify during uninstallation.

Note: The directory TDI_install_dir/examples/install contains a number of example response files for various installation or uninstallation scenarios.

Once the response file is created, you can uninstall silently using the following command: 

TDI_install_dir/_uninst/uninstaller.exe -f UninstallResponseFileName

Note: The examples in this document use the Windows platform uninstallation executable file.

Default installation locations

SDI installs to the following default locations:


Update Installer

The SDI Update Installer called applyUpdates.bat(sh) is provided to install fix packs to an existing SDI installation.

The regular installer lays down a file named .registry in the install directory that represents the current level of installed components. A script named tdiSetBackupDir.bat or tdiSetBackupDir.sh is created in the bin directory of the installation that sets the location of the backup directory; this will be a directory named BACKUP in the maintenance directory by default. We can change the backup location by running the tdiSetBackupDir script. So for example, if a fix is named "ifix1", backup files and directories would be under install dir/maintenance/BACKUP/ifix1 in this scenario. The update installer will harvest the name of the backup directory when performing maintenance. The user performing maintenance to SDI should have write permission for the install and backup directories. You should also be aware that during a complete uninstallation, the uninstaller will attempt to delete the default backup directory.

The regular installer also handles maintenance of the .registry file during uninstalling and adding features. When performing a full uninstallation, the .registry file will be deleted along with the other files. When performing a partial uninstallation, only the components being uninstalled will be removed from the registry file, and when adding features, the .registry file will be updated to contain the newly installed features. After adding a feature, you should immediately install all of the fixes that are currently applied. While installing the fix pack, if an error occurs such as low disk space, error during system command execution, and so on, the fix pack is rolled back and the .registry file is updated to the most recent fix applied level, if any. Installing a fix that has previously been applied will only update the newly added features.

The update installer will be comprised of several Java™ files, but to avoid you having to specify the java executable, a wrapper script is created in the bin directory called applyUpdates.bat(sh). This script will use existing scripts to find the right JRE to use and call the underlying code. The script's usage is as follows: 

applyUpdates -update fix_file.zip [-clean [-silent]]
applyUpdates -rollback 
applyUpdates -queryreg
applyUpdates -queryfix fix_file.zip 
applyUpdate -enroll license_file.zip
applyUpdates -?

The options are as follows:

The .registry file

Inside the install directory will be a file named .registry. This file represents the level of all SDI components currently installed on the system in this particular install directory. This file is initially created by the installer based on the options chosen at install time.

When a fix is installed, the backed up files are stored in a directory with the name of the fix inside the backup directory. If the fix pack is installed successfully, additional entries will be made to the .registry file that represent the changes made to components by a fix. There will be a FIXES section of the .registry file that represents the fixes that have been applied, and each component will have entries representing which fixes have been applied that have altered them. However, if the fix pack is failed to install, the .registry file will not be updated and will contain the same entries that were exist before applying the fix pack.

The Update Installer recognizes the following components: