Welcome to Tivoli Kernel Services 1.1.1!

Congratulations on your decision to deploy Tivoli management software!

Tivoli Kernel Services provides a set of components that are used to manage a wide variety of users, devices, and services. These components are used in conjunction with the Tivoli management software you have purchased. Be sure to read the documentation included with that Tivoli management software before installing Tivoli Kernel Services. Any planning, prerequisite, and installation information provided with that software supersedes similar information included with Tivoli Kernel Services.

This readme file contains information that changed after the documentation and online help provided with Tivoli Kernel Services were complete. The information in this document supersedes the information provided in the online help and the product documentation included on the Installation and Bootprint CD-ROMs. There is no Release Notes document associated with Tivoli Kernel Services.

Before You Install

Before installing Tivoli Kernel Services:

  1. Read the documentation provided with the Tivoli management software you have purchased.
  2. Verify that the systems on which you plan to install Tivoli Kernel Services are supported and are at the proper service level. Refer to the prerequisite information in both the Tivoli management software documentation and in Planning for Tivoli Kernel Services. There are a number of prerequisites that must be met before installing on these platforms:

    Note: See Prerequisties for Installing on AIX 4.3.3 in this readme file for the correct list of APARs for your AIX system. The list provided in the Planning for Tivoli Kernel Services book is not complete.

  3. Complete the Planning Worksheet in Planning for Tivoli Kernel Services.
  4. Read Installing Tivoli Kernel Services and perform the necessary prerequisite steps.

Documentation

Documentation for Tivoli Kernel Services consists of the following documentation available in HTML and PDF formats on the Installation and Bootprint CD-ROMs:

Planning for Tivoli Kernel Services
Describes how to plan for the deployment of Tivoli Kernel Services. The concepts of the installation depot, the bootprint, and other Tivoli Kernel Services concepts are explained. This document also contains a Planning Worksheet to enable you to quickly and accurately deploy Tivoli Kernel Services.
Installing Tivoli Kernel Services
Describes how to use the installation programs to install the installation depot and other Tivoli Kernel Services servers.
Introducing Tivoli Kernel Services Administration
Describes how to administer Tivoli Kernel Services and introduces the Tivoli Console, the graphical user interface (GUI) used for user and system management.
Tivoli Kernel Services Command Reference
Describes the command line interface (CLI) provided with Tivoli Kernel Services which can also be used for user and system management.
Tivoli Kernel Services Quick Reference Card
Describes the syntax of the command line interface (CLI) provided with Tivoli Kernel Services. (Available in PDF format only.)

If you are viewing this readme file from either the Installation or Bootprint CD-ROM, you can go directly to the Tivoli Information Center. The Tivoli Information Center contains links to these documents, plus a link to the Tivoli Console Guided Tour.

You can also view the Tivoli Information Center by inserting either the Installation or Bootprint CD-ROM into your CD-ROM drive and pointing your Web browser to the tivolidocs directory in the root directory.

Known Problems

The following problems and limitations exist in Tivoli Kernel Services. Workarounds are provided if they are available. Report any other problems to your Tivoli Customer Support personnel.

Note: Some of the workarounds described in this section require you to issue commands to Tivoli Kernel Services using the command line interface, or CLI. The wcmd commands provided in this readme file assume that the person issuing the commands is implicitly identified in Tivoli Kernel Services by the appropriate account and user information. If this is not the case, you must use the -u option on each wcmd and explicitly specify a Tivoli Kernel Services user ID that is authorized to perform the command.

For example, to issue the wcmd info getOrbs command using the default user ID of superadmin: 

wcmd -u superadmin info getOrbs

When prompted for a password, enter password if you have not changed the default.

Additional information on command authorization can be found in the Tivoli Kernel Services Command Reference in the section entitled Security Implications for wcmd Commands.

Error using convertSerialLog.bat and convertSerialLog.sh scripts

The scripts convertSerialLog.bat and convertSerialLog.sh fail with the following error message: 

	Exception in thread "main" java.lang.NoClassDefFoundError:
		com/ibm/logging/utilities/SerialViewer

This error occurs because the location of the JLOG toolkit jar file has been changed.

To fix this problem on a Microsoft Windows system, edit script file %ORBDIR%\bin\w32-ix86\convertSerialLog.bat and change the line that reads: 

	set LOGJARS=%ORBDIR%\boot\external\log\2.0.2\log.jar

to read:

	set LOGJARS=%ORBDIR%\boot\external\log\2.0.4\log.jar

To fix the problem on a UNIX system, edit the file $ORBDIR%/bin/solaris2/convertSerialLog.sh or $ORBDIR%/bin/aix4-r1/convertSerialLog.sh and change the line that reads:

	LOGJARS=$ORBDIR/boot/external/log/2.0.2/log.jar

to read:

	LOGJARS=$ORBDIR/boot/external/log/2.0.4/log.jar

Install to an NTFS Drive on Windows Systems

Install Tivoli Kernel Services on an NTFS drive on Microsoft Windows machines. Tivoli does not recommend installing to a disk formatted with the FAT file system because of the large number and small size of many of the files installed.

Install Fails if PATH Length Exceeded or Contains Quotes

The installation program might fail when initially launched if the length of the PATH environment variable exceeds the maximum allowed by the operating system. If you encounter this problem, reduce the size of the PATH environment variable and then restart the installation program.

The installation program also might fail if the PATH environment variable contains quote characters. If you encounter this problem, edit the PATH environment variable to remove the quote characters and then restart the installation program.

MQSeries Server Install Might Fail on Solaris Systems

The install of an MQSeries server might fail on Sun Solaris 2.7. This error occurs because the installation program cannot determine if the MQSeries group and user ID being used by Tivoli Kernel Services have already been defined.

To correct the problem:

  1. Define a group called mqm and a user ID called mqm.
  2. Replace the /etc/system file with the /etc/system.updated.1 file.
  3. Reboot the system.
  4. Run the installation program again to install the MQSeries server.

Installing a Tivoli DAS Server on Solaris

If you plan to install a Tivoli DAS server on a Sun Solaris system, the machine must be a Sun Ultra or higher class machine. Otherwise, the Tivoli DAS server might encounter errors working with secure sockets.

Installing MQSeries and Tivoli DAS Servers on Same Solaris System

If you plan to install an MQSeries server on the same Sun Solaris system as a Tivoli DAS server, you must install the MQSeries server last. After installing the MQSeries server, replace the /etc/system file with the /etc/system.updated.1 file and reboot the system.

Increasing Threadpool Size for a Tivoli DAS Server Datasource

The number of threads that the Tivoli DAS server uses for a particular datasource should be changed to reflect the number of connections to the datasource. In particular, the slash datasource should have at least 5 more threads than the pool size specified during the Tivoli Kernel Services installation. If the Tivoli DAS server does not have enough threads for processing requests, the Tivoli DAS server might stop processing requests or hang.

To increase the number of threads used by the Tivoli DAS server, you need to modify the dasOrbCfg.tks file in the Tivoli DAS server installation directory. When changing the threadpool value you must change the existing line in the file, which looks similar to the following: 

DAServer.datasource.datasource_name.threadpool=nnn

and add an additional line of the form: 

tdo.poa.datasource_name.thread_pool=nnn

where datasource_name is the name of the datasource, such as slash, ps, or tmd, and nnn is the new larger value for the threadpool, such as 65.

For the slash database, this value should be set to at least 5 more than the pool size specified during the installation. To determine the current pool size setting for the slash database, direct the following command (all on one line) to the installation depot ORB: 

wcmd -u superadmin cfg get /com/tivoli/core/directory/slash
   DBPOOL.CONNECTION.POOL.SIZE

Then change the dasOrbCfg.tks file to include these lines: 

DAServer.datasource.slash.threadpool=nnn
tdo.poa.slash.thread_pool=nnn

where nnn is at least 5 more than the DBPOOL.CONNECTION.POOL.SIZE value.

You must stop and restart the Tivoli DAS server for this change to take effect.

Database Connectivity Considerations on AIX

You might experience database connectivity problems when running your DB2 database server and the Tivoli Data Access Services (DAS) server on an AIX system. This is caused by the use of shared memory by DB2 when communicating with the Tivoli DAS server and an AIX IPC defect.

A workaround for this problem is to configure the server to behave as a remote client, which causes DB2 to use TCP/IP sockets instead of shared memory for communication. This procedure is documented in Appendix A of the Installing Tivoli Kernel Services document.

MQSeries Server Might Not Automatically Restart on AIX

An MQSeries server installed on an AIX system might not automatically restart when the system is rebooted. Use the following command to manually start the MQSeries server: 

/usr/mqm/tksSi/startMqOnReboot start

Losing the Installation Program Progress Window

If you minimize the installation program on a UNIX system and subsequently restore it, the installation progress window ends up being hidden behind the black background of the installation panel. To bring the progress window back to the foreground, resize the background installation panel so that the progress panel is partially visible, and then click on the progress window.

Installation Depot ORB Does Not Work if Microsoft IIS is Running

The installation depot ORB might fail to work properly on Microsoft Windows systems if the Microsoft Internet Information Service (IIS) or other Web server is running. One symptom of this problem is that the launch of the installation depot ORB results in an error message in the ORB message log indicating that "http://your-host-name" was in use. Another symptom of this problem is that you cannot connect your Web browser to http://your-host-name/Repository after the ORB is running.

To correct the problem, do one of the following before launching the installation depot ORB:

Only Use Characters Supported by the Database

Tivoli Kernel Services stores its Unicode character data, such as security registry information, preference node names, keys, and values, in the DB2 databases created by the tdacl script. Only use Unicode characters that are supported by your database.

If you plan to run Tivoli Kernel Services in a multi-language or multilingual environment, be sure that you have created your DB2 databases using the appropriate code page, language, and territory to ensure your Unicode data can be stored and retrieved correctly. More information can be found in Installing Tivoli Kernel Services.

Improving Performance

Tivoli Kernel Services relies heavily on its underlying DB2 databases for managing configuration and security information. As significant amounts of data are written to these databases, overall performance of Tivoli Kernel Services might degrade. This might be especially noticeable after the initial install of the installation depot, after the install of one or more bootprints, or after installing an application on Tivoli Kernel Services.

To improve performance, it is strongly recommended that you generate statistics for the Tivoli Kernel Services databases on a regular basis. Tivoli Kernel Services provides a script to perform this activity for you. Refer to Installing Tivoli Kernel Services for information on running this script.

Always Use Fully Qualified Name for MQSeries Server

When running the installation program, always make sure that a fully qualified host name is used for the MQSeries server. On some operating system platforms, failure to use a fully qualified name results in Tivoli Kernel Services being unable to connect to the MQSeries server.

Tivoli Console Help Might Not Be Available from Installation Depot on Solaris

During the initial start of the installation depot ORB on a Sun Solaris system, you might see the following error in the Local ORB Creator and Killer (LOCK) output log: 

2000.12.04 14:53:57.181 McrClientServer$BackgroundHelpBuilder buildHelp() java.io.IOException: Read-only file system
       at java.io.UnixFileSystem.createFileExclusively(Native Method)
       at java.io.UnixFileSystem.createFileExclusively(Compiled Code)
       at java.io.File.createNewFile(Compiled Code)
       at com.tivoli.pf.mcr.McrClientServer$BackgroundHelpBuilder.buildHelp(Compiled Code)
       at com.tivoli.pf.mcr.McrClientServer$BackgroundHelpBuilder.run(Compiled Code)

2000.12.04 14:53:57.224 McrClientServer$BackgroundHelpBuilder buildHelp() FWP1731E An error occurred creating or writing to the file mcrbhs.inv.

This is caused by a problem in the Tivoli Assistant online help build utility.

To correct the problem, shut down and restart the installation depot ORB. After the ORB initialization is complete, issue the following command to build the help: 

wcmd -u superadmin psmcr rebuildHelp

Until the help is built, no Tivoli Console in the installation will have online help available to it.

Tivoli Console Icon Does Not Appear on Windows Desktop

The Tivoli Console icon does not show up on the Windows Desktop until both the installation depot ORB and either the Presentation Services ORB or the Tivoli Console bootprint ORB have started completely. Do not install any Tivoli management software on the installation depot until the Tivoli Console is available.

If the Tivoli Console icon does not appear on the Desktop after waiting a reasonable amount of time, enter the following commands to force a restart of the PsJcLauncherService:

<p>wcmd cfg remove /com/tivoli/core/mmcd/inventory/usableComponents PsJcLauncherService@1.1.0 wcmd lci rebuild

Unexpected Error When Starting Tivoli Console on a Bootprint the First Time

You might see the following error message the first time you start the Tivoli Console on a Tivoli Console bootprint: 

  FWP0015E Connection to Management Component Repository server failed.

To recover from this error, simply close the pop-up error window and click OK on the Sign on to Tivoli Console window. The sign on should complete successfully.

Tivoli Console Does Not Start After Failed Sign On Attempt

If your attempt to sign on to a Tivoli Console fails, and you close the sign on window without successfully signing on, future sign on attempts might fail. The symptom of this problem is that when you start the Tivoli Console you see the Tivoli Console splash screen displayed momentarily and then disappear. You will not be prompted to sign on to the Tivoli Console. This failure also might be accompanied by an error similar to the following in the Local ORB Creator and Killer (LOCK) output log: 

  2001.02.08 15:58:49.779 com.tivoli.pf.jc.JcConsole launchJC() FWP0035E Unable to create new Fmk instance
  because the Fmk instance has already been created.  Already running an instance of the console.

If you encounter this problem, there are two ways to resolve it:

  1. (Recommended) Issue the following command to stop the failed instance of the Tivoli Console. If the failure is encountered on the installation depot machine, direct the command to the Presentation Services ORB (orb.2). Otherwise, direct the command to orb.1 on the bootprint machine encountering the failure. 
    wcmd -u superadmin accmgr stopService -s PsJcImpl
  2. Recycle the ORB. If the failure is encountered on the installation depot machine, recycle orb.2 on that machine. Otherwise, recycle orb.1 on the Tivoli Console bootprint machine.

Restart the Tivoli Console and enter a valid user ID and password to sign on.

Initial Start of Installation Depot Takes a Long Time

The initial start of the installation depot ORB takes a long time and results in data being written to the security registry a number of times during initialization. Stopping the installation depot ORB while it is writing a lot of data to the security registry might leave the ORB in an inconsistent state and might require a re-install to correct the situation.

To ensure that the installation depot ORB is fully operational after it has been started for the first time, ensure that all of the following conditions are met:

  1. You see the following messages in the ORB message log for the installation depot ORB: 
    FNGCP0069I All components have been started.  Some components might not be ready for use.

FNGTM0005I Baseline completed in nnnnnn milliseconds.
  2. You see the following message in the Local ORB Creator and Killer (LOCK) output log for the installation depot ORB: 
    FWP1734I The build help set utility has completed successfully.

Launch Times for ORBs

The launch time for an installation depot or bootprint ORB, after their initial install and launch, is dependent on a number of factors, such as:

The ORB launch time is also affected by the Tivoli management software that you purchased which is using Tivoli Kernel Services.

Assuming the minimum recommended processor speeds and memory requirements, you can usually expect the launch of the installation depot ORB to complete in about 5 minutes. The launch of the second ORB on the installation depot or the launch of a bootprint ORB usually completes in about 2.5 minutes. To check on the progress of the ORB, you can monitor the ORB message log.

These times should be considered best case on the minimum recommended hardware, and were measured in our test laboratory with no Tivoli management software installed. Launch times will increase as Tivoli applications are added to the configuration. More accurate information might be included in the documentation provided with the Tivoli management software that you purchased.

Bootprint Installation Might Hang on Machines Running Winsock Applications

The bootprint installation program might hang on Windows machines running programs that interact with Winsock, the Windows component that routes internet traffic through TCP/IP. Such programs include custom dialers, socksification programs, and some VPN solutions. Disabling these applications does not necessarily correct the problem. It is recommended that you do not attempt to install a bootprint on a machine with these types of programs installed.

Error in MFC42U.DLL Running Bootprint ORB on Windows NT

When starting the bootprint ORB on a Microsoft Windows NT 4.0 system after the bootprint installation program has completed, you might encounter the following error:

The ordinal 6871 could not be located in the dynamic link library MFC42U.DLL

This is caused by a down-level version of the MFC42U.DLL file on the target system. Locate the MFC42U.DLL in your Windows directory and replace it with the updated version provided with Tivoli Kernel Services. The proper DLL to use is \TivoliBP\orb.1\lib\w32-ix86\mfc42u.dll

After replacing the DLL, you must reboot the machine. The bootprint ORB should run as expected.

Sign on to Tivoli Console Window Might Not Appear in Foreground

When starting the Tivoli Console, the "Sign on to Tivoli Console" window might open behind other windows on the desktop. To view the window, either minimize other windows on your desktop or use your window manager or taskbar to bring the signon window to the foreground.

Problem Closing the Tivoli Console with Tasks Open

If you attempt to close the Tivoli Console using the Console->Exit menu item, or by clicking the close window control (the X on the title bar) when there are active task windows displayed, the tasks will close but the Tivoli Console remains running.

To close the Tivoli Console, repeat the close operation.

Refreshing the Manage ORBs Window in the Tivoli Console

To refresh the status of an ORB displayed in the Manage ORBs window, you must select the ORB and then click Refresh. If you do not select an ORB, the status is not refreshed.

Can Only Add One Role to a Resource at a Time in the Tivoli Console

In the Security Registry window, when you right click on an object and click on either Role Member - Existing Role or Role Target - Existing Role, a list of roles is displayed. Even though multiple selection is allowed, only the first role selected is actually added to the object.

Search Security Window in the Tivoli Console Hangs

In the Search Security window, there is a drop down list that allows a user to set properties for a particular object class. After selecting an object class, a filter window appears and the Tivoli Console appears to be hung because the buttons on the panel are not active.

Resizing the filter window or moving the slider refreshes the display and the buttons become active.

Tivoli Console Outside a Firewall Needs Access to the Tivoli DAS Port

If you intend to install a Tivoli Console outside a firewall, the communications port used by the Tivoli DAS server needs to be open in the firewall. Otherwise, the Tivoli Console will not work correctly.

Set DISPLAY Variable Before Launching Tivoli Console on UNIX

The DISPLAY environment variable must be set appropriately before launching the Tivoli Console on UNIX systems. Otherwise, the Tivoli Console does not start and an exception is recorded in the Local ORB Creator and Killer (LOCK) error log. The error might look something like this:

<p>FNGCP0027I Starting component PsJcLauncherService version x.x.x java.lang.InternalError: Can't connect to X11 window server using '0.0' as the value of the DISPLAY variable.

The DISPLAY environment variable must be set on those ORBs that run the Tivoli Console:

If the desired ORB is already running, you must stop the ORB, set the DISPLAY environment variable appropriately, and then restart the ORB. These steps are outlined in the following procedure.

  1. Locate the LOCKCfg.properties file appropriate for your platform and the ORB in question:
    AIX
    $ORBDIR/bin/aix4-r1/LOCKCfg.properties
    Solaris
    $ORBDIR/bin/solaris2/LOCKCfg.properties

    where $ORBDIR is the directory associated with the ORB.

  2. Set the DISPLAY environment variable in the LOCKCfg.properties file by adding a line like: 
    DISPLAY=hostname:0.0

    where hostname is the fully qualified name of the system where you want the Tivoli Console to be displayed. This system could be either the UNIX system itself or a remote system. If you do not know the name of the UNIX system, use the hostname command to find it.

    Be careful not to press Return after adding the DISPLAY line. If the LOCKCfg.properties file has a blank line in it (even at the end) the subsequent start of the ORB might fail with a malloc error.

    Note: XWindows security must be set appropriately on the system where you want the Tivoli Console to be displayed by using xhost +.

  3. If the ORB is already running, stop it using wcmd orb shutdown.
  4. Issue an xhost + command.
  5. Restart the ORB, to pick up the change.

On UNIX systems, you can start the Tivoli Console by entering the following commands: 

. ./setupEnv.sh
JCLaunch.sh

The JCLaunch.sh script is available after the PsJcLauncherService is active.

If you are starting the Tivoli Console on a UNIX machine and using Hummingbird Exceed, be sure to use version 6.2.0.16 or later. Earlier versions might cause the start of the Tivoli Console to hang without any indication of an error.

Link to the Readme File on Windows Systems Might Not Work

After the installation program runs, an entry for Tivoli Kernel Services 1.1.0 is added to the Programs menu. The link to the Readme from that entry might fail, or generate a misleading error message, if Netscape Navigator is the default Web browser on the system. If the launch of the readme file fails, point your browser to the appropriate location, such as:

C:\Tivoli\readme\readme.htm

Icon for Tivoli Console Might Remain on Desktop After Uninstall

After uninstalling the installation depot or a Tivoli Console server on Microsoft Windows, the Tivoli Console icon might still appear on the desktop. To remove the icon, right click on the icon and click Delete.

Ping and Traceroute of GatewayIPService Require Administrator Authority on Windows

Users running on Windows NT or Windows 2000 systems must have Administrator authority to use the ping and traceroute commands of the GatewayIPService. You can disable the security check by editing the Windows registry and creating the following variable and setting its value to DWORD 1:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Afd\Parameters\DisableRawSecurity

Always make a backup of your registry before changing it. You must restart your computer for the change to take effect.

(This is a feature of Windows platforms that only users with Administrator authority can create ICMP raw packets. Those packets are used by the ping and traceroute commands. The URL for the problem resolution is http://support.microsoft.com/support/kb/articles/Q195/4/45.ASP)

Stopping ORBs

Tivoli Kernel Services ORBs should be stopped using the ORB shutdown command:

wcmd orb shutdown

or using the methods outlined in Chapter 5 "Stopping an ORB" in the Installing Tivoli Kernel Services document.

If an ORB appears to be hung and is not responding to commands directed to it, you can terminate the ORB using the standard operating system functions, such as kill or the Windows Task Manager. However, use caution when terminating an ORB in this matter. If an ORB is stopped while writing data to the security registry, the ORB might end up in an inconsistent state, possibly requiring a re-install to correct the problem.

ORB Taking java.net.UnknownHostException Exceptions

During either installation or normal running of Tivoli Kernel Services, an ORB might unexpectedly take java.net.UnknownHostException exceptions. This exception usually occurs in multi-domain environments where the short name for the machine, instead of its fully qualified host name, was used or exported.

To determine if this was the cause of the exception, locate the exception in the Local ORB Creator and Killer (LOCK) output log. For a failure during the installation program, the exception might look similar to this:

2000.10.31 17:21:57.089 BootPrintNSInstall registerOrb(BootPrintNSInstallData, LocalOrbVault)
  RuntimeRemoteException( : java.net.UnknownHostException: kpg057 )
        at java.lang.Throwable.fillInStackTrace(Native Method)
        at java.lang.Throwable.fillInStackTrace(Compiled Code)
        at java.lang.Throwable.(Compiled Code)
        at java.lang.Exception.(Compiled Code)
        at java.lang.RuntimeException.(RuntimeException.java:37)
        at com.objectspace.voyager.RuntimeRemoteException.(RuntimeRemoteException.java)
        at com.objectspace.voyager.Proxy.osInvoke(Proxy.java)
        at com.objectspace.voyager.Proxy.osobjectInvoke(Proxy.java)
        at com.tivoli.core.ns.NetSecurityService_IProxy__Proxy.issueNewOrbCertificate(Unknown Source)
        at com.tivoli.core.ns.BootPrintNSInstall.registerOrb(Compiled Code)
        at com.tivoli.core.ns.BootPrintNSInstall.installNS(BootPrintNSInstall.java:57)
        at BPNetSecuritySetup.configure(BPNetSecuritySetup.java:73)
        at States$getInstallerIdAndPassword_State.valid(States.java:695)
        at States$getInstallerIdAndPassword_State.run(Compiled Code)
        at TKSInstall.install(Compiled Code)
        at TKSInstall.main(Compiled Code)

In the example above, the name of the unknown host is kpg057. If that name corresponds to a machine in your domain, such as kpg057.mycompany.com, verify that you have network connectivity to it by using the ping command. If you have connectivity using the fully qualified host name, the use of the short name is the most likely cause of the exception.

A workaround for this situation is to ensure that all machines in the Tivoli Kernel Services installation can be identified by their short names. To do this:

  1. Shut down all the ORBs running in the installation.
  2. Modify the /etc/hosts files on each machine to map the short names of each machine to the fully qualified host name. Be sure to include the machine on which you encountered the exception.
  3. Restart the ORBs that were running.
  4. Restart the ORB that initially took the exception (or run the installation program again if the failure occurred during an install.)

wcmd Directed to an ORB Fails With Message FNGOB3013E

If you are certain that an ORB is up and running, but when you direct a wcmd to it using the -i option you receive the following message:

FNGOB3013E No CLI server found for ORB ID nnnnnnnn

You might want to check the Local ORB Creator and Killer (LOCK) output log to see if a java.net.UnknownHostException occurred. If an exception occurred, see the workaround information in ORB Taking java.net.UnknownHostException Exceptions.

Using Exceed to Install on UNIX Systems

If you plan to use Hummingbird Exceed to install Tivoli Kernel Services on a UNIX system remotely from a Microsoft Windows system, use version 6.2.0.16 or later. Earlier versions might not work as expected. If you use a lower-level version, the installation program might fail with an error indicating that there is a missing class file.

Changing the Encryption Strength Used in ORB Communications

To change the strength of the encryption used in SSL (secure socket layer) communications, use the wcmd cfg command to change the encryptionStrength key in the configuration node com/tivoli/core/orb/ssl to the desired value:

WEAK
Use 40-bit encryption (the default)
STRONG
Use 128-bit encryption

You will need to recycle the ORB for these changes to take effect.

Windows Application Event Log Can Fill Up on MQSeries Servers

An MQSeries server running on a Windows system might generate a lot of events that could result in the Application Event Log filling up. To correct this problem, increase the size of the Application Event Log, or enable the wrapping of events in the log.

Tivoli Kernel Services Requires Fully Qualified Host Names

Some machines might be configured to return a short host name, such as kendall instead of a fully qualified host name, such as kendall.myorg.mycompany.com. This causes problems for several Tivoli Kernel Services components which are expecting the ORB to always be using fully qualified host names.

To ensure that your operating system is configured to return a fully qualified host name:

Solaris
Verify that the /etc/resolv.conf file exists and contains the appropriate information, such as: 
domain myorg.mycompany.com
nameserver 123.123.123.123

A short host name is used if the /etc/nsswitch.conf file contains a line that starts with: 

  hosts:     files

and the /etc/hosts file contains the short name of the machine. To correct this:

  1. Change the line in the /etc/nsswitch.conf file to: 
      hosts:    dns nis files
  2. Stop the inet service: 
       /etc/init.d/inetsvc stop
  3. Restart the inet service: 
       /etc/init.d/inetsvc start
  4. Recycle the ORB to pick up the change.
Windows NT
Specify a Primary DNS Suffix in the Network settings (Start -> Settings -> Control Panel -> Network -> Protocols -> Properties... -> DNS)

Reboot the machine when prompted.

Windows 2000
There are two places where the Primary DNS Suffix can be set, in Network Identification and in your system properties. To confirm that the Primary DNS Suffix is properly set:
  1. Right click on My Computer and click Properties.
  2. Click the Network Identification tab.
  3. Confirm that the Full Computer Name field displays the fully qualified host name.

    4. If this field does not contain a fully qualified host name:

  4. Click on Properties and then More....
  5. Enter your domain information in the Primary DNS suffix for this computer field.

Reboot the machine when prompted.

AIX
The default domain name search order is:
  • BIND/DNS (named)
  • Network Information Service (NIS)
  • Local /etc/hosts file

To ensure that AIX always provides a fully qualified host name:

  1. Verify that the /etc/resolv.conf file exists and contains the appropriate information, such as: 
    domain myorg.mycompany.com
nameserver 123.123.123.123

    2. (If the /etc/resolv.conf file does not exist, the /etc/hosts file is always used.)

  2. If nis+ is installed, the /etc/irs.conf file overrides the default behavior. 
     hosts = bind,local
  3. The /etc/netsvc.conf file, if it exists, overrides the /etc/irs.conf file as well as the system default behavior. 
     settings in the /etc/irs.conf file
 hosts = bind,local
  4. If the NSORDER environment variable is set, it overrides all of the above. 
      export NSORDER=bind,local
  5. If only the /etc/hosts file is used, the fully qualified host name must be the first one listed after the IP address.

Set up your network configuration appropriately so that systems can be reached using either their short name or their fully qualified host name. This is especially important in mixed operating system environments.

Erroneous MQSeries Messages After Abnormal ORB Termination

After an ORB terminates abnormally, the Messaging Service might generate error messages similar to the following in the ORB message log: 

FNGMS0007E Subscription references non-existent queue suffixed.java.lang.Object/com.tivoli.tes.TESTopicImpl/
FNGMS0007E Subscription references non-existent queue java.lang.Object/com.tivoli.tes.TESTopicImpl
FNGMS0008E Orphaned subscriber discovered java.lang.Object/com.tivoli.tes.TESTopicImpl
FNGMS0009I MQSeries subscription was successfully deregistered java.lang.Object/com.tivoli.tes.TESTopicImpl
FNGMS0011E Unable to delete orphaned subscriber, MQSeries may become unstable java.lang.Object

These messages, which appear every 10 minutes, are caused by the Messaging Service trying to delete queues that have already been deleted. These messages do not represent a problem and can be ignored.

Performance Degradation if Clocks Not Synchronized

If the system clocks on Tivoli Kernel Services servers are not kept synchronized to within an hour of each other, significant performance degradation can occur due to the extra processing required to validate expired security contexts. Having servers in different time zones does not cause a problem, because GMT is used by Tivoli Kernel Services.

The only indication that this problem exists is a message that appears in the installation depot ORB message log during ORB start up: 

FNGCS0032E The security context for principal system/services/principals/serviceManager has either expired or is not valid.

To correct the problem, make sure that the servers in a Tivoli Kernel Services installation can reach a stratum 2 NTP server on the Internet or provide a list of accessible NTP servers, separated by spaces. This value can be set in the Tivoli Console, or with a command similar to the following: 

wcmd cfg put /com/tivoli/core/time
    SERVER_LIST="timeserver.almaden.ibm.com timeserver.raleigh.ibm.com"

More information on configuring the time synchronization service can be found in Appendix B, "Configuring the Properties of Components" in the Installing Tivoli Kernel Services document.

Known Problems with the Tivoli Console

The following problems have been identified in using the Tivoli Console.

  1. Context menus always open to the right of and below the cursor regardless of the cursor position. If you open a context menu when the cursor is near the bottom right corner of the screen, the context menu opens partially offscreen. You should reposition or resize the Tivoli Console until you can see the context menu in its entirety.
  2. The PgUp and PgDn keys do not work properly for scrolling the portfolio. To scroll in the portfolio, use the arrow keys or the scroll bar.
  3. The scroll button on a mouse is not supported in the Tivoli Console. To manipulate scroll bars use the mouse pointer or a keyboard shortcut.
  4. When you resize the Tivoli Console, the menu bar does not wrap to another line. Therefore, some menus might be hidden. To prevent this problem, always resize the Tivoli Console such that the entire menu bar is visible.
  5. The Tivoli Console does not support screen resolutions with only 256 colors.
  6. When you close a window that is a child of a detached task window, the focus always returns to the Tivoli Console rather than to the parent task window.
  7. If the session between the Tivoli Console and the server is lost, and if you immediately sign onto the Tivoli Console again, the portfolio might not reflect new tasks that were added as a result of adding new roles to the existing user. To solve this problem, exit the Tivoli Console, and restart it. The new tasks will then be displayed in the portfolio.
  8. Sometimes when you exit the Tivoli Console, the task windows close but the Tivoli Console window remains open. Exit the Tivoli Console again, and this window closes.
  9. On the AIX operating system, the "working" cursor (the hourglass with an arrow) in the Tivoli Console is larger than the normal cursor.
  10. Occasionally, when you close certain types of windows in the Tivoli Console, the portfolio automatically slides open.
  11. Pressing the Esc key does not always cancel or close a task window. To close the task window, click either the Cancel button or the X in the upper right of the window.
  12. On Sun Solaris systems, accelerator keys do not always work on window buttons. To solve this, tab to the button and press Enter, or click the button directly using the mouse pointer.
  13. Context menus might not close when you change the focus from one task window to another. To close the context menu, click anywhere within the window that contains the context menu.
  14. On the taskbar, tooltips are shown to the left of the cursor position, and lengthy tooltips might appear offscreen to the left. You should reposition or resize the Tivoli Console until you can see the tooltips in their entirety.
  15. When you click a task in the portfolio, the cursor does not change to the wait state (the hourglass) or the working state (the hourglass with an arrow) until the mouse is moved slightly. To solve this, always move the mouse slightly after clicking a task in the portfolio.
  16. When you print a topic from the Tivoli Assistant, the printed pages might not precisely represent the content of the topic as it is displayed in the Tivoli Assistant.
  17. When you are working within tables, ensure that you click the filter buttons only once. Multiple clicks of the filter buttons might cause multiple windows to open. If multiple windows open, close them by pressing Alt + F4.
  18. The first time that the Tivoli Console is started after Tivoli Kernel Services has been installed from a CD-ROM, a user might see the message "Error loading help set." This indicates that the installation depot did not build the online help properly. To rebuild the online help, do the following:
    1. Stop the installation depot ORB.
    2. Start the installation depot ORB.
    3. After the installation depot ORB has initialized, issue the following command: 
      wcmd -u superadmin psmcr rebuildHelp

    The online help might not be available for awhile. You can tell when the online help is available by checking for the pf.hs or pf_<language>.hs file on the installation depot: 

    http://installation.depot.machine/help
  19. Shift + F10 does not currently open the context menu for the item that has focus.
  20. On Sun Solaris systems, ORBs run only in an English environment regardless of the LANG setting. Tivoli Presentation Services does not support other LANG settings.
  21. Multilingual database configurations using a UTF-8 codeset do not work. The UTF-8 codeset cannot be used for a mixed locale environment. It may cause data loss.

If you find a problem or have a issue related to the online help for the Tivoli Console, you need to package the contents of the following directory structure as a ZIP file for problem determination:

Windows
%TKS_BASEDIR%\ext\ibmhttpd\tksDocs\help
UNIX
$TKS_BASEDIR/ext/ibmhttpd/tksDocs/help

where TKS_BASEDIR is the directory where you installed the Tivoli Kernel Services installation depot.

Gateway SNMP Service Trace Data Written to Stderr

When tracing for the Gateway SNMP Service is enabled through either of the following commands:

<p>wcmd snmp trace start wcmd gatewaysnmpservice tracesnmp 1

the trace data is written to the Local ORB Creator and Killer (LOCK) error log instead of trace.log.

NelService Cannot Run on Same ORB as Tivoli Console

If you attempt to run the NelService on the same ORB where the Tivoli Console is running, the NelService will be unable to resolve endpoints. Do not run the NelService on a Tivoli Console bootprint ORB, or on the Tivoli Presentation Services ORB (orb.2) on the installation depot.

MQSeries Windows Left Open After Initial Install

After installing an MQSeries server, two command prompt windows are left open running MQSeries daemons. Do not close these windows; closing these windows will result in stopping the MQSeries server. When the machine running the MQSeries server is rebooted, the daemons are started as services in the background and these windows will not appear.

If you do accidentally close the MQSeries windows, either reboot the MQSeries server machine or restart the MQSeries server manually following the directions given in the Installing Tivoli Kernel Services document.

Do Not Use the Tivoli Console on Solaris to Upgrade Components

Do not use the Tivoli Console on Solaris systems to upgrade components on Tivoli Kernel Services. Instead, issue the appropriate wcmd cds upgrade commands from the command line. Upgrading components using the Tivoli Console on other platforms works as expected.

Messages and Exceptions Associated with Known Problems

During operation of Tivoli Kernel Services, there are several cases where an error message or exception is shown in the output log which represents a known problem that was not fixed in this version of the product. These include the following:

  1. The Messaging Service attempts to store a null value into configuration on occasion, resulting in a message similar to the following: 
    07:04:02.111 java.lang.NullPointerException: FNGCF0012E A null string was specified as the
    value parameter to a configuration API for key localServer in node /com/tivoli/tes.

The Messaging Service handles this exception and continues working as expected.
  2. If a NullPointerException is received from the MSManager component, restart either the Installation Depot ORB or the MSManager component.
  3. During ORB shutdown, you might see a message similar to this: 
    08:22:11.807 FNGOB3004E An error occurred accepting a CLI client connection:
    java.net.SocketException: socket closed.

This error is caused by the socket being closed as part of normal ORB shutdown and can be ignored.
  4. During ORB shutdown, you might see an exception similar to this: 
    13:06:22.605 java.lang.IllegalArgumentException: There is not a registered PropertyChangeListener to remove.
        at java.lang.IllegalArgumentException.(IllegalArgumentException.java:45)
        at com.tivoli.util.configuration.impl.BasePreferences.removePropertyChangeListener(BasePreferences.java:794)
        at com.tivoli.core.configuration.OrbMetadataPreferences.removePropertyChangeListener(OrbMetadataPreferences.java:834)
        at com.tivoli.core.mmcd.SJIComponentInstaller.shutdown(SJIComponentInstaller.java:149)
        at com.tivoli.core.component.ComponentManager$StopComponent$ShutdownComponentAction.run(ComponentManager.java:5465)
        at java.security.AccessController.doPrivileged(Native Method)
        at com.tivoli.core.component.ComponentManager$StopComponent.run(ComponentManager.java:5434)
        at java.lang.Thread.run(Thread.java:481)
13:06:22.745 FNGCP0042E An unexpected failure was encountered when shutting down the component SimpleJarComponentInstaller version 5.1.0-200102070256.

The SimpleJarComponentInstaller recovers from this exception and the ORB continues to shut down.
  5. During ORB start up, you might see a warning message similar to: 
    WARNING: File d:\Tivoli\orb.1\boot\SDSRemoteServiceInterface@5.1.1.jar does not exist

This warning can be ignored, the ORB uses the proper SDSRemoteServiceInterface file.

Prerequisites for Installing on AIX 4.3.3

Debugging Install Problems

If the installation program or the launch of an ORB fails, check the following logs for exceptions or unexpected messages:

File Microsoft Windows UNIX
Installation program output log NT: %TEMP%\tksOut.log
2000: \Documents and Settings\userid\Local Settings\Temp\tksOut.log		 /var/tmp/tksOut.log
Installation program error log NT: %TEMP%\tksErr.log
2000: \Documents and Settings\userid\Local Settings\Temp\tksErr.log		 /var/tmp/tksErr.log
MQSeries server installation log MQ_BASEDIR\ext\mqm\tksSi\tksInstall.log AIX: /usr/mqm/tksSi/tksInstall.log
Solaris: /opt/mqm/tksSi/tksInstall.log
Tivoli DAS server installation log DAS_BASEDIR\ext\das\server\tksSi\tksInstall.log DAS_BASEDIR/ext/das/server/tksSi/tksInstall.log
IBM HTTP Server installation log TKS_BASEDIR\ext\ibmhttpd\tksSi\tksInstall.log TKS_BASEDIR/ext/ibmhttpd/tksSi/tksInstall.log
Tivoli Presentation Services UABuildHS installation log TKS_BASEDIR\ext\ibmhttpd\tksDocs\help\uabuildhs.log TKS_BASEDIR/ext/ibmhttpd/tksDocs/help/uabuildhs.log
ORB message log TKS_BASEDIR\orb.1\log\message1.log TKS_BASEDIR/orb.1/log/message1.log
Local ORB Creator and Killer (LOCK) output log TKS_BASEDIR\orb.1\log\stdout.txt TKS_BASEDIR/orb.1/log/stdout
Local ORB Creator and Killer (LOCK) error log TKS_BASEDIR\orb.1\log\stderr.txt TKS_BASEDIR/orb.1/log/stderr

On UNIX systems, you can monitor these files as the installation is progressing by using tail. For example, to track changes to the installation program output log during install:

tail -f tksOut.log

Other common causes of install failures:

  1. The MQSeries server is not running or is not accessible.
  2. The database server is not running or is not accessible.
  3. The Tivoli Data Access Services (DAS) server is not running or is not accessible.
  4. The databases needed by Tivoli Kernel Services have not been properly defined and initialized prior to doing a multiple machine install of Tivoli Kernel Services.

Notices

(C) Copyright IBM Corporation 2000, 2001 All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement, an IBM Software License Agreement, or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of IBM Corporation. IBM Corporation grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the IBM Corporation copyright notice. No other rights under copyright are granted without prior written permission of IBM Corporation. The document is not intended for production and is furnished "as is" without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose.

U.S. Government Users Restricted Rights-Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corporation.

Trademarks

IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, NetView, RS/6000, and TME are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.

Notices

References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to valid intellectual property or other legally protectable right of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York 10504-1785, U.S.A.

OpenSSL License

Copyright (c) 1998-2000 The OpenSSL Project. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org.
  5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.
  6. Redistributions of any form whatsoever must retain the following acknowledgment: 
      "This product includes software developed by the OpenSSL Project
   for use in the OpenSSL Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).

Original SSLeay License

Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved.

This package is an SSL implementation written by Eric Young (eay@cryptsoft.com).

The implementation was written so as to conform with Netscape's SSL.

This library is free for commercial and non-commercial use as long as the following conditions are adhered to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft.com).

Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed.

If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. All advertising materials mentioning features or use of this software must display the following acknowledgement: 
         "This product includes cryptographic software written by
      Eric Young (eay@cryptsoft.com)"

    The word 'cryptographic' can be left out if the routines from the library being used are not cryptographic related :-).

  4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: 
       "This product includes software written by Tim Hudson
    (tjh@cryptsoft.com)"

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The license and distribution terms for any publicly available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution license [including the GNU Public License.]

Apache and Apache Tomcat Notices

This product includes software developed by The Apache Group for use in the Apache HTTP Server project (http://www.apache.org/).

This product includes software developed by Greg Stein for use in the mod_dav module for Apache (http://www.webdav.org/mod_dav/).

This product includes software derived from software developed by Henry Spencer.

This product includes software derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

Portions of certain components of the Program are copyrighted by MERANT, 1991-1999.

Tivoli Kernel Services Version 1.1.1 - 2001/02/15