domingo, 28 de agosto de 2011

TIBCO TRA Installation Notes

These are some notes I have written in order to help myself to get ready to clear the TIBCO ActiveMatrix BusinessWorks 5 Certification Exam (TB0-123). More details about the exam, click here. This entry is about TIBCO Runtime Agent installation. Any comment or suggestion, please write to luisagcenteno@gmail.com. Further details can be found at TIBCO Documentation. I hope these notes can help you as well as they did to me...

TRA Installation Notes...
- TRA stands for TIBCO Agent Runtime
- Software that comes with TRA
    -TIBCO Designer
    -TIBCO Runtime Agent (TRA) - Includes Domain Utility, TIBCO Wrapper, etc
    -Third Party Libraries
    -JRE
    -TIBCO Rendezvous
    -TIBCO Hawk
- After installation using a 64-bit installation package on a machine, all administration servers,
    TIBCO Hawk agents and applications on that machine will run on a 64-bit mode
- After installation using a 64-bit intallation package, Hawk Microagents (tibhawkma) and
    TIBCO Rendezvous (rvd) will still run in 32-bit mode
- When a 32-bit installation exists,
    - A 32-bit installer can be used
    - Uninstall completely current 32-bit installatiion before using 64-bit installer
    - Configure existing 32-bit installation to run in 64-bit mode (follow documentation acompanying the software release)
- When a 64-bit installation exists, a 64-bit installer must be used
- If a 32-bit installation exists, but it is configured to run on 64 mode, then a 64-bit installer must be used
- Having a 32-bit installation and using a 64-bit installer will render the existing 32-bit installation non-operational.
- Having a 64-bit installation and using a 32-bit installer will render the existing 64-bit installation non-operational.
- TIBCO uses a 3-digit release number
    major.minor.servicePack
- When installing a Service Pack, it will overwrite the current installation
- installing a new major or minor version, it will create a new folder
- If there is a product already installed in the machine, installation path cannot be changed until it gets uninstalled.
- Installation registry is named Vital Product Database
- Installation registry gets stored in vpd files (Vital Product Database)
- VPD files are updated after a new product is installed
- VPD files are checked by applications
- VPD file location
    Windows
        %SystemRoot%/vpd.properties
        %SystemRoot%/vpd.properties.tibco.systemName
    UNIX (non-root user)
        User_Home_Directory/vpd.properties
        User_Home_Directory/vpd.properties.tibco.systemName
    UNIX (root user)
        Solaris and HP-UX
            root's home directory (which is /) as vpd files
        Linux
            /root as vpd files
        AIX
            /usr/lib/objrepos as vpd files
- Installer looks for a JVM, if it does not find one, it extracts a bundled JVM and uses more space in temporary directory.
    If installer finds an installed JVM, it will use less disk space
- In order to run installer using a different folder as temporary folder
    TIB_tra-suite_version_sol8_sparc.bin -is:tempdir /new_tmp
- Entries are appended to a Installation History file each time a new softawre is installed.
    Windows
        %SystemRoot%/TIBCOInstallationHistory.xml
    UNIX
        User_Home_Directory/TIBCOInstallationHistory.xml
- TIBCO Runtime Agent depends on TIBCO Rendezvous and TIBCO Hawk
- Version and location information is contained in many files, typically *.tra files
- Supported Platforms
    Windows (Only 32-bit installers are supported on windows platforms)
        Windows Server 2003 SP1 (x86)
        WIndows Server 2003 SP1 (x86_64)
        Windows Server 2008 on (x86)
        Windows Server 2008 on (x86_64)
        Windows XP (x86)
        Windows Vista Business Edition (x86) with latest patches
    UNIX
        IBM (Power)
            AIX 5.2 with patch 5200-04
            AIX 5.3
        HP-UX 11i (v2, v3) (IA-64/Itanium)
        HP-UX 11i (v1, v2, v3) (PA-RISC)
            J2SE patches are required for all HP-UX platforms
        Red Hat (x86)
            Red Hat Enterprise Linux 4
            Red Hat Enterprise Linux 4.5
            Red Hat Enterprise Linux 5
            Red Hat Enterprise Linux 5.1
        SuSE (x86)
            SuSE Linux Enterprise 9
            SuSE Linux Enterprise 10 SP1
        Solaris (SPARC)
            Solaris 8
            Solaris 9
            Solaris 10
        Solaris 10 (x86)
        
        
- It is recommended to use vendor-supplied JDBC drivers as TIBCO-supplied drivers are deprecated
- Supported Vendor-supplied drivers
    Oracle Thin Client
    Oracle Thick Client
    Microsoft SQL Server
    IBM DB2
- Requirements
    - Minimim free space required by the installer is 250 MB
    - Minimum free space in temp area required by installer
        Windows (150 MB)
            SystemDrive:/Temp
            SystemDrive:/Documents and Settings/user-name/Local Settings/Temp
        HP-UX (200 MB)
            Temporary directory
        UNIX (200 MB)
            Temporary directory
    - User account with administrator privileges
    - Permissions to write on a networked drive (if necessary)
    
- On Windows 2003 without the SP1 not installed, installed creates VPD files in user home directory rather than
    C:/windows. As Hawk Agent looks for VPD file in c:/windows, the administration domain does not get updated.
    To resolve this issue,
    - Upgrade Windows 2003 with SP1
    - Or, copy vpd files to c:/windows (copy *.vpd c:/windows)
    
- There are two modes in Windows Terminal Server
    - Execute
        Users are logged on this mode by default
        User can run applications when logged into this mode        
    - Install
- Logon as administrator in install mode to install TIBCO Runtime Agent and everyone can use it
- When the adapter is installed in install mode the installation registry is maintained in SystemDrive:/WINNT
    - To change modes
        C:\> change user /install (Changes to install mode)
        C:\> change user /execute (Changes to execute mode)
        C:\> change user /query         (Checks current mode)
- Windows Terminal Server must be running in remote admin mode, not application sharing mode. TIBCO Runtime Agent is not supported if installed on a machine that is using Windows Terminal Server in application sharing mode.
- The best way to instal TIBCO Runtime Agent is using Add/Remove Programs control panel applet.
- Installation modes
    - GUI
        TIB_tra-suite_version_win_x86_32.exe
    - Console
        TIB_tra-suite_version_win_x86_32.exe -s -a -is:javaconsole -console
    - Silent (No prompting information)
        -silent argument uses default values
            TIB_tra-suite_version_win_x86_32.exe -s -a -is:silent -silent    (install silent mode)
            TIB_tra-suite_version_win_x86_32.exe -s -a -is:silent -silent -options <> (install in silent mode with response file)
        -options responseFile argument uses values specified when response file was generated
            TIB_tra-suite_version_win_x86_32.exe -s -a -is:javaconsole -console -options-record <> (create responseFile)
            TIB_tra-suite_version_win_x86_32.exe -s -a -is:javaconsole -console -options <>         (install with responseFile)
- TIBCO TRA location must not contain space characters
- Response file contains name=value pairs
- JDBC Vendor drivers are configured after all TRA files have been installed to the computer
- JDBC Driver configuration tool can be run later with traDBConfig
- TIBCO Installation Manager (Start>TIBCO>TIBCO Installation Manager) displays all TIBCO software installed and helps to uninstall.
- Only files created during installation are uninstalled by TIBCO Installation Manager
- If a database is used as administration domain repository, Domain Utility must be used in order to delete the domain
    before uninstalling TIBCO Runtime Agent in order to drop database tables
- Products that depend on TIBCO TRA should be uninstalled first
- Products uninstallation (after uninstalling all products that depend on TIBCO Runtime Agent)
    Using TIBCO Installation Manager
        TIBCO Runtime Agent
        TIBCO Designer
        Java Runtime Environment
        Third Party Core Libraries
    Using Add/Remove Programs utility
TIBCO Hawk. Before uninstalling, stop TIBCO Hawk HMA Service in Services dialog
        TIBCO Rendezvous. Before uninstalling, kill rvd daemon from Task Manager

- If 64-bit kernel is used and a 32-bit TIBCO Hawk is installed, some statistics will remain undefined
- Regular (non-root) users can install TIBCO Runtime Agent at different locations. Dependencies will be resolved at user level
    using installation registry maintained at user's home registry.
- Commands to install TIBCO Runtime Agent to a UNIX System
    GUI Mode
        TIB_tra-suite_version_sol8_sparc.bin
    Console Mode
        TIB_tra-suite_version_sol8_sparc.bin -is:javaconsole -console
    Install and create a response file
        TIB_tra-suite_version_sol8_sparc.bin -is:javaconsole -console -options-record /dir/responseFile
    Install with a response file
        TIB_tra-suite_version_sol8_sparc.bin -is:javaconsole -console -options /dir/responseFile
    Install in silent mode
        TIB_tra-suite_version_sol8_sparc.bin -is:silent -silent
    Install in silent mode with a response file
        TIB_tra-suite_version_sol8_sparc.bin -options /dir/responseFile -is:silent -silent
- Use ksh shell when installing TIBCO Runtime Agent in AIX 5.2 64-bit
- If multiple Administration Domain users are deploying applications, each domain user must have write access to /tmp/tempdats
- Modify the permissions of the TIBCO Hawk HMA (tibhawkhma) as shown
    cd $TIBCO_HAWK_HOME/bin/tibhawkhma
    chown root tibhawkhma
    chmod u+s tibhawkhma
- On AIX platform, tibhawkhma must be run as root and it must not use setuid
- On all supported platforms, TIBCO Hawk is dynamically linked with TIBCO Rendezvous client libraries (on AIX platforms,
    TIBCO Hawk is statically linked to Rendezvous client libraries)
    - Post-Install steps
        HP-UX 11i PA-RISC 32-bit
            Add TIBCO Rendezvous library path to /etc/dld.sl.conf file (contains trusted paths to search libraries)
        No post-install steps are required for HP-UX 64-bit and Itanium platforms
        Linux x86 32-bit/64-bit
Update /etc/dld.so.conf file and add $RV_HOME/lib to the list (this must be an actual path, not an environment variable)
            Run ldconfig
        Solaris
Add the $RV_HOME/lib directory to the trusted list using crle command on 64-bit and 32-bit
The crle command allows you to create and display a runtime linking configuration file
                Solaris 8-10 SPARC 32-bit/64-bit
                    crle -u -s $RV_HOME/lib
                    crle -u -s /path/to/directory
                Solaris 10 x86 32-bit/64-bit
                    crle -u -s <>
                    where
-u specifies that the configuration file needs to be updated
-s specifies the new trusted directory for secure objects
- To uninstall TIBCO Runtime Agent
    Navigate to TIBCO_HOME
    Invoke TIBCOInstallationManager
- TIBCO Hawk and TIBCO Rendezvous do now uninstall because of the missing Tibuninstall.bin files under
$TIBCO_HOME/tibrv/version/_uninst and $TIBCO_HOME/hawk/_uninst on HP-UX 11i, v3 (PA-RISC) operating system.
To uninstall TIBCO Hawk or TIBCO Rendezvous, go to $TIBCO_HOME/tibrv/version/_uninst or
    $TIBCO_HOME/hawk/_uninst and run the command
    java -cp uninstaller.jar run
- TIBCO Runtime Agent has two main functions
    - Supplies an agent that runs in background on each machine
- The agent is responsible for starting and stopping processes that run on a machine as specified on deployment information
- The agent monitors the machine. The information is then visible on TIBCO Administrator Enterprise Edition
- Supplies the runtime environment (all shared libraries including third party libraries)
        TIBCO Designer
        TIBCO Hawk
        TIBCO Rendezvous
        Java Runtime Environment
        Third Party Libraries
        TIBCO Runtime Libraries

-TIBCO Designer allows to configure TIBCO products
-TIBCO Designer is an easy to use GUI to create integration projects
- When TIBCO Designer is installed, it contains the framework and a small number of palletes
    Framework
        Includes Drag and Drop instation, customizable layout, and online help.
    Adapter Resources Palette
- Generic Adapter configuration and Adapter Resources pallete allow to configure an Adapter-SDK-based adapter program.
- If no custom pallete exists for an adapter, and the adapter is opened in TIBCO Designer the elements are represented as resources inside a Generic Adapter Configuration.
Adapter Schema pallete
    The AESchemas folder and associated Adapter Schemas folder can be used to define schema for a custom adapter
Repository Pallete
    By default is not displayed because in most cases, repositories must be modified by editing the project directly.
- TIBCO Runtime Agent bundles Java Runtime Environment
- JRE is embedded in TRA
- TIBCO TRA requires the JRE bundled to be installed
- TIBCO Java applications will use the JRE installed by TIBCO
- Environment variables can be modified in order to enforce to use another JRE
- TIBCO Runtime Agent includes a TIBCO Hawk Agent
- A Hawk agent is an autonomous process that runs in each machine where TRA is installed and monitors TIBCO applications on that computer.
- Hawk agent operates autonomously and is active whenever the operating system it monitors is active
- Hawk uses a set of rules called rulebases to configure system management, status and automation tasks
- Hawk monitors conditions on its local machine and sends alerts only when problems are detected
- TIBCO Rendezvous provides a common message-based communication mechanism
- A main component is TIBCO Rendezvous daemon which runs on each participating machine
- All information that travels between adapter instances passes through TIBCO Rendezvous daemon as the information enters and exits host machine. It also passes information between adapters running on the same machine.
- TIBCO Rendezvous uses subject-based addressing technology to direct messages to their destinations
- An adapter configured with a publication service, sends information on a well-defined subject name. An adapter configured with a subscription service listens on the subject name. The TIBCO Rendezvous daemon manages the network messages corresponding to the peer-to-peer communication between the publication adapter and subscription adapter. This allows adapters to communicate without knoing details about connections or addresses. Subject-based conventions define a uniform name space for messages and their destination.
- TIBCO Runtime Agent contains an evaluation copy of TIBCO Rendezvous
- Third Party Core Libraries (tpcl) installer is part of TIBCO Runtime Agent suite installer
- The tpcl does not include JRE which is included in its own folder
- TIBCO Domain Utility is used to manage components available in administration domain.
    - Machine Management. Add machine where Domain Utility is running to an existing domain or add a node that is part of a cluster to a Domain
    - Domain Configuration. Create a new admnistration domain. Add a secondary server to the domain. Delete an administration domain; administration server and TIBCO Hawk agent must be shutdown before proceeding with this task. Enable and configure HTTPS for a selected administration domain on the machine where the Domain Utility is running.
    - Server Settings. Change TIBCO Rendezvous parameters used by TIBCO Administrator and TIBCO Hawk for a selected administration domain on the machine on which TIBCO Domain Utility is running. Change administration user and password, LDAP configuration, and database configuration for a selected administration domain.
    - Migration. Upgrade a release 5.x to release 5.6
    - TIBCO EMS plug-in. Add, Update or Remove a TIBCO EMS Server from an administration domain.
    - Servlet Engine Plugin. Add or remove a servlet engine plugin.

- The TIBCO Wrapper Utility allows deployment of TIBCO product or TIBCO Adapter SDK based custom adapter as a service (operating system to start application on reboot regardless of the operation system). On Windows it can be installed and run a Windows Service. On UNIX, the functionality serves as process abstraction. Hooks to TIBCO Administrator which will monitor applications restarted on reboot.
- When invoked TIBCO Wrapper Utility searches its current directory for the appname.tra file. If the file is not found, then it searches the PATH for appname.tra. If a .tra file cannot be found in one of those locations, then Wrapper Utility cannot start.
- If TIBCO Adapter SDK is installed, then TIBCO Wrapper Utility can be used for both Java and C++ adapters. The utility uses standard java properties for configuration of Service and Java Virtual Machine (JVM) parameters.
- The TIBCO Wrapper Utility fails if it is not started from the bin directory (‘Failed to load shared library’ error message. Location of .tra file can be specified by using --propFile argument for the wrapper.
- The obfuscate utility allows to encrypt confidential information in property files using an encription key. It reqrites Java properties files by encrypting property values that start with #!! or #! prefix (in file content). It supports three types of encryption keys.
    - Custom encryption key. The encryption key is derived from a password. To use the password, add #!! to the data to obfuscate and use -password or -passwordFile command line parameters as appropriate. The password can be any keyboard characters and has no length limit.
    - A machine key. Add the #!! prefix and do not use the -password or passwordFile parameters. It can be used to obfuscate a custom key in a properties file. Then you can use the obfuscated key to encrypt data (with the -passwordFile parameter) in the properties file. If using a machine key, the data cannot be decrrypted on anoother machine.
    - Fixed key. Add the prefix #! to the data to obfuscate. Fixed key is compatible with earlier versions of TIBCO but it does not provide the same level of security as the use of a machine key or a custom encryption key. It is used to encrypt an administration domain’s password.

        - password. prompts to type a password.
        - passwordFile. read a password from a given file.

- In order to encrypt passwords, only one custom key can be used at a time.

obfuscate -password <> (prompt for password)

obfuscate <>
obfuscate <> -passwordFile <>

- The ae2xsd utility generates XSD schemas from a project metadata (TIBCO ActiveEnterprise classes and operations). Source is a multi-file project saved in ActiveEnterprise XML format (cannot be used on a .dat file.
    ae2xsd -project <> [-output <>]
- If -output <> parameters are omitted, a folder AE2XSD-generated is created in current working directory. Folders are generated that reflects their namespaces which in turn reflects the locations of .aeschema files within the project.
- The ae2xsd utility has the same functionality as TIBCO Designer “Tools>Export As XML Schemas” menu command

The utility is found in TIBCO_HOME/tra/version/bin.

- The tramodify utility is deprecated. traUpgradeManager should be used instead.
- The tramodify utility is used to switch adapter dependency from one TIBCO Runtime Agent version to another. It is also used to upgrade the references in a TIBCO product’s template .tra files to use a new release.
    Syntax
        tramodify product-home n.n directory
- product-home. home directory of TIBCO adapter for which TRA should be changed
- n.n. Two digit TRA version number to which adapter dependency needs to be changed
- directory. absolute location of the directory that contains set of custom TRA files to be modified
    tramodify --usage
        Displays tramodify online help
    tramodify --ladapters
Generates a text file in TIBCO_HOME/log with a list of adapters installed on the machine, install location and dependent TRA version for each adapter
- The tramodify utility can be found TIBCO_HOME/tra/version/bin
- The traUpgradeManager utility is used to
    - change the Rendezvous version that TIBCO Runtime Agent uses
- change the TIBCO Runtime Agent version and Rendezvous version that a deployed application or TIBCO product uses. This includes updating references to TRA, JRE and TPCL directories.
- Do not use traUpgradeManager to upgrade a domain
- Make sure to upgrade Aministration domain and applications in the domain to use the same Rendezvous version.
    traUpgradeManager -path <> -traversion <> -rv <>
    traUpgradeManager -path <> -revert
    traUpgradeManager -help
        path. The path of the tra file to modify or a directory withmultiple tra files to modify.
traversion. Two digit TRA version number to which adapter dependency needs to be changed
rv. Home directory of the Rendezvous release to which the application or TRA dependency needs to be changed
revert. Revert to the previous settings
help. Print the help information
- The traDBConfig utility is used to configure a supported vendor-supplied database driver
- TIBCO Administrator and TIBCO Hawk Agent must be restarted after traDBConfig utility is used for the changes to be reflected.
traDBConfig -type <> -dbPath <> (-ociPath <>) [-product <>|-path <>|-fileList <>]
        -type. SQLServer|DB2|OracleThin|OracleThick
        -dbPath. The path of the vendor-supplied driver
-ociPath. The path of the Oracle OCI client directory. This must be specified if type=OracleThick
-product. The product to configure (tra or admin). This utility updates TRA or Administrator
-path. The path of tra file to update or directory with multiple tra files to update
-fileList. A text file that includes a list of files to update. Application files can be included
    FILES file1,file2,file3,...

- If TRA and Administrator are installed in a machine, but it has not been added to a domain, running traDBConfig -tra and traDBConfig -admin to update TRA and Administrator files. Then, vendor-supplied drivers can be used when creating new domains.
- If TRA and Administrator are installed in a machine as well as created domains, then all tra files must be updated for the existing Hawk agent and administrator servers. In that case, a list of all the files that must be updated can be created and then use -fileList parameteror run with the -pat parameter for each of the domain directories.
- Files to update with traDBConfig
    Runtime Agent Files
TIBCO_HOME/tra/template/domainutility/hawkagenttra.template
TIBCO_HOME/tra/bin/domain_create.tra
TIBCO_HOME/tra/bin/CorpUserSynchronizer.tra
TIBCO_HOME/tra/bin/CorpRoleSynchronizer.tra
TIBCO_HOME/tra/bin/AppManage.tra
TIBCO_HOME/tra/bin/RedeployAllAppsForUser.tra
TIBCO_HOME/tra/bin/MoveMachine.tra
TIBCO_HOME/tra/bin/ImportDomainSecurity.tra
TIBCO_HOME/tra/bin/Import2xSecurity.tra
TIBCO_HOME/tra/bin/ExportDomainSecurity.tra
TIBCO_HOME/tra/bin/domainutilitycmd.tra
TIBCO_HOME/tra/bin/domainutility.tra
    Domain Hawk Files
TIBCO_HOME/tra/domain/domain/hawkagent_domain.tra
TIBCO Administrator Files
TIBCO_HOME/administrator/version/template/tibcoadmintra.template
    Domain Administration Server files
        TIBCO_HOME/administrator/domain/domain/tibcoadmin_domain.tra
- Other libraries included with TIBCO Runtime Agent
- Repository Client Libraries and Utilities. Repository client commnicates with TIBCO Administrator
- TIBCO EMS Libraries. Allows to configure TIBCO EMS with TIBCO Administrator
- XML-related libraries
- Persistent Object Framework libraries. POF libraries are used by TIBCO Administrator and TIBCO Domain Utility to implement domain management. The API is not intended for customer use
- TIBCO Crypto library. Includes APIs used by TIBCO applications to encrypt data. The APIs are not intended for customer use. They are included as TIBCrypt.jar. The TIBCO Crypto library does not include encryption, but provides an interface that allows pluggable support of third party encryption libraries. The installation includes following security vendors
- Entrust. The default vendor. It can be configured in FIPS140-2 compliant mode
- IBM. Also a FIPS140-2 compliant vendor. Only available for IBM systems. When using it, installation of Unlimited Strength Jurisdiction Policy is needed.
- Sun. Java cryptography extension provided by J2SE
- In order to use Entrust or IBM security vendors in FIPS140-2 compliant mode, the following line mst be added to .tra file.
    java.property.com.tibco.security.FIPS=true
- For applications that require a different security vendor
    1. Java classpath must include security vendor .jar files.
    2. In the .tra file for the application, define a new property
        java.property.TIBCO_SECURITY_VENDOR=vendor
            where vendor can be entrust61, ibm, or j2se
- Unicode conversion. If Unicode conversion to or from arbitrary encodings is required, a file containing a lookup table is required. Set environment table TIB_ICU_DATA to point to the directory that contains the file tibicudata.dat which contains the lookup table.
    The tibicudata.dat file is located in TIBCO_HOME/tra/version/config/g11n
- Schema Files. To verify a prepared configuration by editing an XML file. Used before using RepositoryImport to convert the schema to project format.
    Located in TIBCO_HOME/tra/version/schema
- TIBCO Installation Manager. Used to uninstall TIBCO Products in the correct order. Located in TRA_HOME
- Hotfix Libraries. A file or collection of files that are applied to a TIBCO Runtime Agent installation to correct a specific problem. Hotfixes are only applied to software already installed. TRA hotfixes, jars and other files are installed under the hotfix folder. If a hotfix is installed, tra_home/hotfix/bin location is specified before the tra_home/bin and tra_home/lib in PATH, CLASSPATH, SHLIB_PATH or LD_LIBRARY_PATH, .tra file (if used) and so on.
-Set DISPLAY environment variable in order to indicate UNIX operating system, on which screen window should be shown.
    DISPLAY=IP_address:screen_address