Softpanorama (slightly skeptical) Open Source Software Educational Society

May the source be with you, but remember the KISS principle ;-)

ODADMIN command

Manages object dispatchers.

Syntax

odadmin [option [suboption]]

Description

The odadmin command provides a command line interface to many oserv run-time configuration settings and management operations. The list of supported functions includes options for the following:

• Allowing or disallowing client installations
• Synchronizing object databases
• Getting or setting object dispatcher environments
• Listing information about object dispatchers
• Reexecuting object dispatchers
• Performing remote region operations
• Setting encryption levels and passwords
• Setting network security
• Setting downed-host checking options
• Starting and shutting down object dispatchers
• Enabling or disabling Kerberos authentication
• Adding or changing platform and application license keys

It is recommended that you back up all object databases before you use the odadmin command to change the low-level configuration of a Tivoli management region. There may be better methods (using the Tivoli desktop or Tivoli commands other than the odadmin command) to perform some of the operations that the odadmin command allows you to perform. If you are not explicitly familiar with the implications of the odadmin command, call your Customer Support provider before attempting to perform any odadmin operations.

Options

allow_client_install TRUE | FALSE

Sets an installation flag to permit or disallow adding additional object dispatchers to the local region. You must have the super or senior role to run this option.

 

allow_dynamic_ipaddr TRUE | FALSE

Enables or disables dynamic Internet Protocol (IP) address assignment support (Dynamic Host Configuration Protocol [DHCP]) within the local Tivoli management region. The default value is FALSE.

 

db_sync [od... | clients | all]

Flushes the object database state to disk. You can flush the specified object databases (od), all client object databases (clients), or all object databases (all) to disk. You must have the super or senior role to run this option.

 

environ

Gets or sets the method environment for specific object dispatchers. The method environment is the environment variables that are set inside the process of the method when the method executes. Default environment variables are set in addition to the user-specified variables displayed when using this option. You must have the super or senior role to run this option.

The following suboptions are available with the environ option:

 

get [od... | clients | all]

Gets the method environment for one or more specific object dispatchers (od...), all client object dispatchers (clients), or all object dispatchers (all).

 

set [od... | clients | all]

Sets the method environment for one or more specific object dispatchers (od...), all client object dispatchers (clients), or all object dispatchers (all). The method environment is read from standard input.

 

get_allow_NAT

Displays the value of the set_allow_NAT option, which enables or disables network address translation (NAT) support.

 

get_platform_license

Gets the current platform license key. You must have the super or senior role to run this option.

 

get_port_range

Gets the port range setting for Inter-Object Messaging (IOM) channel communication ports and Tivoli communication between managed nodes. To set the port range, use the set_port_range option.

 

get_rpc_max_threads

Retrieves the maximum number of concurrent remote procedure call threads handled by the dispatcher. You can reset this number with the set_rpc_max_threads option.

 

help [suboption]

When invoked with no option, gives top-level help about the available options for the odadmin command. If an option is specified, gives help for the specified option. If no help is available for the specified option, the top-level help menu is displayed. You can run this option with any role.

 

odinfo [od... | clients | all]

Provides information about specific object dispatchers (od...), all client object dispatchers (clients), or all object dispatchers (all) in an installation. odinfo is the default option if you invoke the odadmin command without specifying any options. If you do not specify any object dispatcher numbers or the clients or all option, the odinfo option returns information about the local object dispatcher. You must have the super, senior, admin, or user role to run this option.

The odinfo option provides the following object dispatcher information:

 

Copyright information

Indicates the IBM copyright information.

 

Region

Indicates the Tivoli management region number, which is a unique number encoded within the license key.

 

Dispatcher

Indicates the server or dispatcher number within the Tivoli management region. Dispatcher number 1 indicates a Tivoli management region server. The Tivoli dispatcher number is based on the client's installation order.

 

Interpreter Type

Indicates the machine interpreter type.

 

Database directory

Indicates the path for the local Tivoli object database.

 

Install directory

Indicates the path for the object dispatcher's installation directory and the location of the binaries.

 

Inter-dispatcher encryption level

Indicates the encryption type used when clients pass messages between themselves.

 

Kerberos in use

Indicates whether Kerberos authentication is being used within the Tivoli management region.

 

Remote client login allowed

Enables you to make a remote desktop connection using Tivoli Desktop for Windows.

 

Force socket bind to a single address

Indicates whether to force socket bind to a single address. For example, if this statement is FALSE and you have multiple network interface cards (NICs), the oserv opens port 94 and binds to all IP addresses, one for each NIC. (TCP/IP lets the oserv listen on port 94on all IP addresses.) If this statement is TRUE, it indicates that the oserv binds to only port 94 on one IP address.

 

Perform local hostname lookup for IOM connections

Indicates that Inter-Orb Messaging (IOM) will use the IP address passed to make a connection back to the initiator of the IOM request. It will not use the host name passed to look up the IP address.

 

Use Single Port BDT

Indicates whether single-port Bulk Data Transfer (BDT) is enabled (TRUE) or disabled (FALSE) for this node.

 

oserv version string

Indicates the object dispatcher's version information.

 

Port range

Identifies the range of ports that the Tivoli environment is allowed to use.

 

Single Port BDT service port number

Indicates the port that the BDT service uses on this node.

 

Network Security

Indicates the network security level of a managed node. none specifies that Secure Sockets Layer (SSL) is not used by the managed node, except when it is SSL-capable and is communicating with a FORCE_SSL managed node. SSL specifies that the managed node uses SSL when communicating with other SSL managed nodes. FORCE_SSL specifies that the managed node only communicates using SSL.

 

SSL Ciphers

Indicates the cipher list (in order of preference) used with SSL network security. The keyword default indicates the default Tivoli cipher list of 05040A030609.

 

ALLOW_NAT

Indicates whether network address translation (NAT) support is enabled (TRUE) or disabled (FALSE).

 

Note:

On UNIX systems, the odadmin command also displays the library path in effect for Tivoli operations. On Windows NT systems, the dynamically linked libraries (DLLs) are stored in the binary directory instead of a separate library directory.

For a Tivoli management region server, the following information is also provided:

 

State flags in use

Indicates whether the oserv ping cache is consulted. For more information about communicating between managed nodes, see the Tivoli Management Framework Maintenance and Troubleshooting Guide.

 

State checking in use

Indicates whether the host state information is kept up-to-date with polling (TRUE) or collected implicitly (FALSE).

 

State checking every x seconds

Indicates the interval at which state checking is performed.

 

Dynamic IP addressing allowed

Indicates whether Dynamic Host Configuration Protocol (DHCP) support on managed nodes is enabled.

 

Transaction manager will retry messages x times

Indicates the number of inter-ORB retries for communicating with another oserv.

 

odlist [suboption]

Lists or edits information about the dispatchers in an installation. You must have the super or senior role to run this option. Note that the odlist information is cached and the flags column output might not accurately reflect the most recent connection or communication state of the managed node. To force a new polling of the state, invoke a command that actually contacts the managed node in question (such as the wping command), and then reinvoke the odadmin odlist command. If you specify the odlist option without any suboptions, the following information is provided in a columnar format about each currently attached object dispatcher:

 

Disp

The object dispatcher number.

 

Flags xyz

There are three flags. If the first flag (x) is c, it indicates that the object dispatcher is connected to the remote dispatcher listed in the display.

If the first flag is ?, it indicates that the cached state is out-of-date, and the state of the connection to the remote dispatcher is unknown. The state is updated only in certain circumstances. (See the Tivoli Management Framework Maintenance and Troubleshooting Guide for details.)

If the first flag is -, it indicates that the remote dispatcher is down.

The second flag (y) is always t. The t flag indicates that the object dispatcher is trusted.

The third flag (z) is always -. The - flag indicates that the dispatcher is not a special dispatcher.

 

Hostname(s)

The host name and aliases of the client on which the object dispatcher is located.

 

IPaddr

The IP addresses of the client on which the object dispatcher is located.

 

Port

The listening port for the object dispatcher.

 

Region

The number identifying the installation in which the object dispatcher is located.

 

The following suboptions are available with the odlist option:

 

list_od

Lists members of the region.

 

add_ip_alias od IP_address | host_name

Adds an IP address alias for an object dispatcher. The request fails if the new IP address and object dispatcher port number match another object dispatcher IP address and port number. This suboption must be invoked from the Tivoli management region server.

 

delete_ip_alias od IP_address

Deletes an IP address alias for an object dispatcher. This suboption must be invoked from the Tivoli management region server.

 

add_hostname_alias od IP_address host_name

Adds a host name alias to an IP address associated with an object dispatcher. This suboption must be invoked from the Tivoli management region server.

 

delete_hostname_alias od IP_address host_name

Deletes a host name alias for an IP address associated with an object dispatcher. This suboption must be invoked from the Tivoli management region server.

 

change_ip od IP_address [TRUE | FALSE]

Changes the primary IP address associated with an object dispatcher. The request fails if the new IP address and object dispatcher port number match another object dispatcher IP address and port number. This suboption must be invoked from the Tivoli management region server.

 

rm_od od

Removes an object dispatcher from the installation. The specified object dispatcher must be shut down before it is removed. A list of object IDs for objects that the dispatcher owned is displayed. The objects are removed, but references to the objects remain. This suboption must be invoked from the Tivoli management region server.

The rm_od option should only be run at the direction of Customer Support when a client installation has failed and it is impossible to recover. The usual method of deleting a client is with the wrmnode command.

 

set_kerberos_instance 1 kerberos_name

Changes the instance name of the Kerberos service used by the Tivoli management region server. The object dispatcher number is always 1.

 

objects od

Displays a list of the object IDs of objects owned by the object dispatcher.

 

reexec [od... | clients | all]

Reexecutes the local object dispatcher. You can reexecute specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). The Tivoli management region server's object dispatcher cannot be reexecuted from another system. You must have the super or senior role to run this option.

 

region [suboption]

Provides remote region operations. You must have the super or senior role to run this option. The following suboptions are available for odadmin region. These suboptions should only be run at the direction of Customer Support to resolve low-level problems that cannot be handled from the Tivoli desktop or by the interregion commands.

 

add_alias region IP_address [host_name...]

Adds a host name or IP alias for a remote Tivoli management region server.

 

add_group_map region remote_group local_group

Adds an object group map between regions.

 

add_group_id_map region remote_name local_name

Adds mapping from user group names in the remote region to group names in the local region.

 

add_region region host port [crypt]

Integrates an additional region. The password is read from standard input. You are prompted for the password if you run this command from a terminal device (tty).

 

add_role_map region remote_group remote_role localrole

Adds a role map within a group map.

 

add_user_id_map region remote_name local_name

Adds mapping from user login names in the remote region to login names in the local region.

 

change_region region host port [crypt]

Changes configuration information for a remote region. The password is read from standard input. You are prompted for the password if you run this command from a terminal device (tty). An empty password indicates that the password should not be changed.

 

delete_alias region IP_address [name...]

Deletes a host name or IP alias for a remote Tivoli management region server.

 

delete_group_map region remote_group

Deletes an object group map between regions.

 

delete_group_id_map region remote_name

Deletes user-group name mapping.

 

delete_region region

Disconnects a remote region.

 

delete_role_map region remote_group remote_role

Deletes a role map within a group map.

 

delete_user_id_map region remote_name

Deletes login name mapping.

 

list_group_id_map region

Displays mapping from user group names in the remote region to group names in the local region.

 

list_map region

Lists object group and role maps between regions.

 

list_region [region]

Lists connected regions. If the region option is not specified, lists regions that are connected to the local region.

 

list_user_id_map region

Displays mapping from user login names in the remote region to login names in the local region.

 

set_region_crypt_level crypt

Sets encryption level used by other Tivoli management region servers to connect to this region. The crypt option can be one of none, simple, or DES.

 

set_region_pw

Sets encryption password for other Tivoli management region servers to connect to this region. The old password and the new password are read from standard input. You are prompted for the old and new passwords if you run this command from a terminal device (tty).

 

set_allow_rconnect {TRUE | FALSE}

Enables Tivoli Desktop for Windows to connect to a Tivoli management region server or client.

 

set_allow_NAT {TRUE | FALSE}

Enables network address translation (NAT) support. You must restart the endpoint manager and gateways for changes to take effect. The default value is FALSE. For more information about NAT support, see the Tivoli Management Framework Planning for Deployment Guide.

 

set_bdt_port {port_value} [od... | clients | all]

Sets the port that the Bulk Data Transfer (BDT) service uses. The port value must be greater than 1023. You can set the port that the service uses for object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). You must have the super or senior role to run this option.

Note:

You can use this option only if the odadmin single_port_bdt option is set to TRUE. If single_port_bdt is set to FALSE (the default), this BDT port is not used and does not apply to any other node operations.

 

set_crypt_level {crypt}

Sets encryption level for communication between object dispatchers within the local region. Typically, you need to use the following procedure to set the encryption level:

1. Enter odadmin shutdown clients.
2. Enter odadmin set_crypt_level crypt where crypt specifies the encryption level and can be none, simple, or DES.
3. Enter odadmin start clients.

 

You must have the super or senior role to run the set_crypt_level option.

 

set_force_bind TRUE | FALSE {od... | clients | all}

Forces Tivoli communication connections to bind to a single IP address. This option is used in certain high availability or failover configurations where multiple object dispatchers reside at different IP addresses on a single physical system.

 

set_install_pw

Sets the installation password for future client installations. The old password and the new password are read from standard input. You are prompted for the old and new passwords if you run this command from a terminal device (tty). You must have the super or senior role to run this option.

 

set_iom_by_name TRUE | FALSE {od... | clients | all}

Enables or disables communications to rely on the host name rather than the IP address of a Tivoli management region server when interpreting an IOM key and making a connection. Use this option for multihomed servers that are known by different IP addresses on different subnets.

 

set_keep_alive {on | off | poll | nopoll | time...}

Sets options for checking for hosts that are down. The default is off, that is, check every 180 seconds to see if a host is still down. See the value referenced in the odadmin command output in the line that reads "State checking every 180 seconds". You must have the super or senior role to run this option. The suboptions are as follows:

 

on | off

Specifies whether to trust cached downed-host information (on) or to try the host each time (off).

 

poll | nopoll

Specifies whether to poll dispatchers (poll) or collect information implicitly (nopoll). The polling algorithm minimizes network traffic.

 

time

Specifies the minimum poll interval time in seconds. Most dispatchers are not polled every interval.

 

The current keep_alive options can be read by running odadmin odinfo 1.

 

set_network_security {none | SSL | FORCE_SSL}

[od... | clients | all] Sets the network security level of a managed node. You can set the network security level on specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). Options are as follows:

 

none

Specifies that Secure Sockets Layer (SSL) is not used by the managed node, except when it is SSL-capable and is communicating with a FORCE_SSL managed node. This is the default setting.

 

SSL

Specifies that the managed node uses SSL when communicating with other SSL managed nodes. SSL is not used when communicating to a node with a setting of none.

 

FORCE_SSL

Specifies that the managed node only communicates using SSL. Non-SSL connections are not accepted by the managed node.

 

Note:

Restart the managed node for changes to take effect. For more information about SSL, see the Tivoli Management Framework Planning for Deployment Guide.

 

set_ORB_pw od

Sets the password for communication between a Tivoli management region server's object dispatcher and the specified client's object dispatcher. The password is read from standard input. You are prompted for the password if you run this command from a terminal device (tty). You must have the super or senior role; you must also have root privileges on the Tivoli server and the specified object dispatcher.

Typically, when a client is added to the Tivoli management region server, the password used by the Tivoli client to communicate with the Tivoli server is set by the Tivoli server. This password is never stored in a file or transmitted over the network in plain text. However, there is a slight possibility that an intruder could get a copy of this password in its obscured form and decode it if your network is compromised during the installation process or if your database is compromised at a later date.

To change a client's Tivoli password, do the following:

1. Shut down the affected client.
2. Run odadmin set_ORB_pw od on the Tivoli management region server.
3. Copy the file host_name-od-odb.adj from the Tivoli database directory to a file named odb.adj in the client database directory. Use a secure copying mechanism to copy this file. Set the file permissions on odb.adj to user-read/write, group-none, and other-none, and set the file ownership to root.
4. Restart the client's object dispatcher.

 

set_platform_license license_key

Adds or changes a platform license key. You must have the super or senior role to run this option.

 

set_port_range [range]

Restricts the IOM channel communication ports and Tivoli Management Framework communication between managed nodes to the specified port range. This option is especially helpful for firewall administrators who need to regulate the availability of ports. The oserv and gateway default ports are not affected by this option. Port ranges must be greater than 1023. To set the port range to null, use the following syntax:

odadmin set_port_range ""

 

set_rpc_max_threads num_threads

Sets the concurrent remote procedure call thread limit for the dispatcher or the number of concurrent object call threads. The default is 250.

 

set_ssl_ciphers cipher... [od... | clients | all ]

Sets ciphers for managed nodes to protect the channel. You can set ciphers on specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). cipher options are as follows:

 

default

Specifies the default Tivoli list of 05040A030609. A node can be set to the default regardless of its SSL capabilities.

 

cipher

Specifies the cipher list, in order of preference (for example, 0A09). The node must be SSL-capable before you can change a user-defined cipher list. For cipher values and information about how to enable SSL on a managed node, see the Tivoli Management Framework Planning for Deployment Guide.

 

Note:

Restart the managed node for changes to take effect.

 

set_tmgr_retries

Adjusts the transaction manager's default timeout value. The transaction manager retries messages once per minute, so that the number of retries is equal to the number of minutes that it should wait before aborting a transaction.

Note:

This value is adjusted on a per Tivoli management region basis; every dispatcher in the region gets the same value. The new value takes effect the next time a dispatcher is restarted.

 

shutdown [od... | clients | all]

Shuts down the local object dispatcher. You can shut down specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). You must have the super or senior role to run this option. You cannot shut down the Tivoli management region server from a remote system. This option is not available to NetWare clients. NetWare clients must be stopped with the oservend command.

 

single_port_bdt {TRUE | FALSE} {od... | clients | all}

Enables or disables single-port Bulk Data Transfer (BDT)--the underlying support for Inter-Object Messaging (IOM) and other large-scale data transfers. If TRUE is specified, the port usage is consolidated to the selected port. The default is FALSE. You can enable or disable the service for object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). You must have the super or senior role to run this option.

Notes:

 

1. After you enable BDT service, use the odadmin reexec command to reexecute the dispatchers.

    

2. If you enable single_port_bdt, you can change the default port (9401) to another port by using the odadmin set_bdt_port command.

 

start [od... | clients | all]

Starts the local object dispatcher. You can start specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). You must have the super or senior role to run this option. This option is not available to NetWare clients. NetWare clients must be started with the oservrun command.

 

trace {objcalls | services | errors | off [od... | clients | all]}

Starts or stops debug tracing. You can specify that object calls, services, or errors be traced, or you can turn off debug tracing. If you want to trace object calls, services, and errors, you must turn first on the tracing of errors by using the odadmin trace errors command. Note that turning error tracing on also turns off the tracing of object calls and services. Therefore, ensure that you turn object call and services traces on after the error trace invocation.

You can start or stop tracing for specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). If you do not specify specific clients or the clients or all option, debug tracing is started or stopped on the local object dispatcher. The trace information is collected in the odtrace.log file in the database directory. You can use the wtrace command to view this trace information. You must have the super or senior role to run odadmin trace.

Tivoli recommends that you do not enable error tracing by default. Tracing all object calls and services impacts the performance of your dispatcher. Use tracing of all object calls and services only when diagnosing specific problems.

 

use_kerberos {TRUE | FALSE [od... | clients | all]}

Enables or disables Kerberos authentication. You can enable or disable Kerberos authentication for specified object dispatchers (od), all client object dispatchers (clients), or all object dispatchers (all). If you do not specify specific clients or the clients or all option, Kerberos authentication is enabled or disabled for the local object dispatcher. You must have the super or senior role to run this option.

Examples

1. The following example gets the status of the Tivoli management region server:

   odadmin odinfo 1
   
   

   Output similar to the following is displayed:

   Tivoli Management Framework (mb) #1 Fri Feb 16 17:19:20  2001
   
   (c) Copyright IBM Corp. 1990, 2001.  All Rights Reserved.
   
    
   
   Region = 1000142803
   
   Dispatcher = 1
   
   Interpreter type = w32-ix86
   
   Database directory = C:\Tivoli\mbarber2.db
   
   Install directory = C:\Tivoli\bin
   
   Inter-dispatcher encryption level = simple
   
   Kerberos in use = FALSE
   
   Remote client login allowed = TRUE
   
   Force socket bind to a single address = FALSE
   
   Perform local hostname lookup for IOM connections = FALSE
   
   Use Single Port BDT = TRUE
   
   Port range = (not restricted)
   
   Single Port BDT service port number = default (9401)
   
   Network Security = SSL
   
   SSL Ciphers = default
   
   ALLOW_NAT = FALSE
   
   State flags in use = TRUE
   
   State checking in use = TRUE
   
   State checking every 180 seconds
   
   Dynamic IP addressing allowed = FALSE
   
   Transaction manager will retry messages 4 times.
   
   

2. The following example gets help on the shutdown option:

   odadmin help shutdown
   
   

   Output similar to the following is displayed:

   shutdown [od... |clients|all]
   
   Stop object dispatcher(s)
   
   

3. The following example flushes the database files for all dispatchers:

   odadmin db_sync all 
   
   

4. The following example specifies that all managed nodes use port range 60000 through 60100.

   odadmin set_port_range 60000-60100
   
   

5. The following example lists information about the dispatchers (managed nodes) in a Tivoli environment:

   odadmin odlist
   
   

   Output similar to the following is displayed:

   Region     Disp  Flags  Port  IPaddr     Hostname(s)
   
   1248901349  1    ct-    94    10.69.9.42 la.tivoli.com,la   
   
               2    ct-    94    10.69.9.73 ten.tivoli.com 
   
   

See Also

odbls, odstat, oserv, wconnect, wdisconn, wlsconn, wrmnode, wtrace, wupdate

Tivoli Management Framework provides commands to help you in troubleshooting systems. The most commonly used commands are as follows:

odadmin

Lists the managed nodes in a Tivoli region and configures different aspects of how the object dispatcher communicates, such as defining IP addresses and interconnected regions.

odstat

Lists currently running methods and method histories.

wtrace

Parses the odtrace.log file, which is created when tracing object calls, services, or errors (tracing is invoked with odadmin trace options).

Also described in this chapter are the commands to review and modify transaction status:

tmcmd

Forces a specified transaction or subtransaction to a particular state.

tmstat

Displays the status of current transactions and locks.

Managing the Object Dispatcher

The odadmin command is the object dispatcher administration interface. This command provides configuration information about the server and allows you to change this information.

The following table provides the context and authorization roles required for this command:

For information about how to use the odadmin command to start and stop the object dispatcher, see Stopping and starting the object dispatcher. For more information about the odadmin command, see the Tivoli Management Framework Reference Manual.

If you enter the odadmin command without options, output similar to the following is displayed for the local object dispatcher:

Region = 1264987995
Dispatcher = 1
Interpreter type = w32-ix86
Database directory = C:\Tivoli\db\aliburdi.db
Install directory = C:\Tivoli\bin
Inter-dispatcher encryption level = simple
Kerberos in use = FALSE
Remote client login allowed = TRUE
Force socket bind to a single address = FALSE
Perform local hostname lookup for IOM connections = FALSE
Use Single Port BDT = FALSE
Use communication channel check = FALSE
Communication check timeout = default (180 secs) 
Communication check response timeout = default (180 secs) 
Oserv connection validation timeout = 0
Port range = (not restricted)
State flags in use = TRUE
State checking in use = TRUE
State checking every 180 seconds
Dynamic IP addressing allowed = FALSE
Transaction manager will retry messages 4 times.

For a description of odadmin output, see Viewing data for a Tivoli region.

For obtaining information about connected managed nodes, you can use the odadmin odlist command. This command shows you the status of the managed node, its IP address, the port, and the host name alias. The odadmin odlist command also includes values indicating the status of its Tivoli region connection. For more information about the odadmin command and odlist option, see Listing active managed nodes.

Listing the Status of Current and Recent Object Calls

Tivoli Management Framework provides the odstat command, which displays the currently running operations and the previous 200 operations for a specific managed node. Your support provider might ask you to run this command and send its output to assist in problem diagnosis. You can use the wtrace command to retrieve all data contained within an odstat output. Using the odstat command, however, is a much more explicit way to view this data. Use the wtrace output when you understand what is going on through examining the odstat output.

The following is an example output of the odstat command:

The output contains the following information:

tid

Specifies the thread ID. When you start an object call, two threads are generated: one for the object call itself and one for the method being invoked.

type

Lists the thread type. The thread type flags include the following:

O

Object call thread (attached to an object request), indicating that the method was invoked here but is running elsewhere.

M

Method thread. The object call occurred on a different system, but the object is located on the local system.

O+

Object call and method threads are the same, indicating that the caller and method are both local.

Method type flags include the following:

a

Asynchronous object call

q

Queueing method

o

Per-object method

b

One-way object call

h

Helperless method

d

Daemon method

ptid

Lists the parent thread ID or the thread ID of the object call whose method made the current object call. If this field is blank, the object call is external. The number before the dash (-) is the dispatcher number where the parent thread resides. The number after the dash is the thread ID in the parent object dispatcher.

state

Lists the following states of the object call thread:

init

The thread has been initialized.

ali

The thread is performing a lookup on the Tivoli server object database.

mwait

The thread is waiting for the associated method thread to complete.

rwait

The thread is waiting for the caller to collect the results of an asynchronous object call.

done

The object call is complete.

coord

The method is serving as a transaction coordinator.

err

An internal error terminated the thread.

Method thread states include the following:

init

The thread has been initialized.

gmeth

The thread is obtaining the method code from another object dispatcher.

hdwt

The thread is waiting for the daemon-method process (the nonqueueing daemon) to be ready to accept another request.

run

The method is running.

serv

The thread is performing an object services call.

done

The method is complete.

twait

The method is waiting on transaction status to commit or abort.

std O

Lists the number of bytes written to standard output.

std E

Lists the number of bytes written to standard error by the method. Most threads do not write to standard error.

start

Lists the time that the thread started. Entries can be one of the following depending on the age of the thread:

• Time-The thread started on this day.
• Day and Time-The thread started before this day, but within in the current week.
• Month and day (UNIX operating systems only)-The thread started before the current week.
• Month (Windows operating systems only)-The thread started before the current week.

err

Lists the error status of the thread. If this field is blank, no error occurred.

Error types include the following:

e=n

The method returned n as its exit code. Error codes 0 through 21 are reserved for system-defined errors. Tivoli error codes start with 22.

s=n

The method failed due to signal n.

S=n

The method failed due to signal n and produced a core file. Contact your support provider if you want to debug using this core file.

XXX

An uppercase word indicates an error in the object dispatcher.

Exit codes (e=) can come from the system on which the Tivoli desktop is running, Tivoli Management Framework, or an application. It might be necessary to look at different sets of error documentation to find out which is the most likely source. You might be able to use system documentation to obtain help regarding system-produced errors. Most UNIX operating systems include an error file that lists the system error codes and often a short description. On OS/2 operating systems, enter help n, where n is the number of the error message (for example, help 5). On Windows operating systems, enter the net helpmsg n command (for example, net helpmsg 5).

method

Lists the text of the method invocation. The first value is the object ID of the object in which context the method was invoked. The format is either three numbers separated by periods or three numbers separated by periods followed by a pound sign (#), the class name, and another pound sign. The next entry is the name of the method followed by its options.

The following is an example of a method listed in the odstat output.

1242184237.1.516#TMF_SysAdmin::InstanceManager# _get_interfaces 

Any action that you perform can generate several methods. Use the thread and parent thread ID relationship to determine the order in which the methods started. This is important because the Tivoli environment is multitasking and several administrators might be performing tasks from several different locations. Looking at the thread IDs helps you determine which processes are yours and where an error occurred. When tracking errors, read the odstat file from the bottom to the top and use the thread and parent thread IDs to determine which action caused the problem.

The odstat output is listed by order of time and thread. Only the first 80 characters of the method invocation are displayed. IDL-generated method options are not viewable with odstat. For more information about IDL-generated methods, see the wtrace command in the Tivoli Management Framework Reference Manual.

Retrieving Information to Debug Methods

Tivoli Management Framework supports an object tracing mode that records in a log file either all operations or only those that fail. You can use this file later to diagnose problems. This file provides very detailed information and should be used in conjunction with an odstat listing. You can find an error in an odstat listing and use the thread ID associated with it to find additional information in a wtrace file.

The wtrace command reads the file in the database directory, called odtrace.log, that was generated by the object dispatcher. This file is static and 1 MB in size. It resides in the Tivoli database directory $DBDIR (%DBDIR% for Windows or OS/2). You can use the -t option on the oserv command to change the trace file size. However, you must manually start the object dispatcher to specify this option.

Information is written to the odtrace.log file and parsed with the wtrace command. This is important to remember because, unlike the odstat command, the wtrace command can provide debugging information if the object dispatcher is down or has been recycled.

Use the wtrace command to interpret trace log records and print the interpreted information in a user-friendly format. The trace log is a circular buffer that contains (by default) the last 512 trace records. A trace record can be either an operation request or an error from an operation request. Your support provider might ask you to enable tracing or print the trace output and send it to assist in problem diagnosis.

The wtrace output contains everything that is also found in odstat output; however, it is quite detailed and can be hard to read. Having corresponding odstat output can make reading the wtrace output much easier. For more information, see Listing the Status of Current and Recent Object Calls.

By default, only errors are saved in the odtrace.log file. If you want to save more tracing information, use the odadmin trace command with either the objcalls or services option. Tracing all object operations and services reduces the performance of the Tivoli service. Only enable such tracing for limited periods of time as you troubleshoot systems.

The rate at which odadmin data is written to the file depends on the the trace level of the object dispatcher. Various types of methods can be tracked by the object dispatcher in the trace set with the odadmin trace command:

errors

Records errors in the oservlog file. This is the default setting.

objcalls

Usual setting to use for problem determination. Traces object method invocation.

services

Tracks authentication, location, and inheritance (ALI) services requested of the Tivoli server. This tracking quickly fills a trace file.

How to Use Tracing

If you are having problems that are not easily resolved by the messages Tivoli Management Framework provides, follow these steps:

1. To set the tracing option, use the following options (in the following order):
   1. odadmin trace errors: Turns on error tracing (recommended).
   2. odadmin trace objcalls: Turns on object call tracing (recommended).
   3. odadmin trace services: Turns on service tracing (optional).
2. Run the odstat command. This helps separate the methods that are involved in the problem by inserting two object calls into the trace (as shown). After you are familiar with reviewing traces, you might want to skip this step and rely solely on finding process IDs or some other method.

   355 O+  done   15   0 23:53:56    0.0.0 get_oserv
   356 O+  done   2103  0 23:53:58    1480943038.1.2 query odstat

3. Re-create the problem.
4. Enter the following command, where odstat_output is the name of the file containing output from the odstat command:

   odstat -v> /path/odstat_output

5. Enter one of the following commands:

   wtrace -jk $DBDIR > /path/wtrace_output
   wtrace -jk $DBDIR >> odstat_output

   Optionally, use -jHk if the trace mentions binary hex data to get the hex data output with an attempted ASCII translation.

6. If needed, refer to the oservlog file.
7. Turn off the trace with the following command:

   odadmin trace off

8. Turn on the default tracing with the following command:

   odadmin trace errors

9. Review the odstat_output file you created in step 4 and begin analyzing the output starting with the query odstat line, as illustrated in step 2.

The following scenario shows odstat and wtrace examples of a managed node subscription to a profile manager. For each record in the wtrace output, the first line contains the method thread ID, the thread and method flags, the parent thread ID, if one exists, and any error codes. Subsequent lines are similar to the rest of the data in an odstat output as shown. Also provided in the trace data is the name of the Tivoli principal that effectively called the method and the path of the method executable.

The odstat output includes the following:

347 O+ahdoq  1-342  done     9     0 23:53:50 \
     1480943038.1.348#TMF_ManagedNode::Managed_Node# add_subscription

The wtrace output includes the following:

loc-ic  347  M-hdoq    1-342      153
      Time run:    [Thu 01-Jun 23:53:50]
      Object ID:   1480943038.1.348#TMF_ManagedNode::Managed_Node#
      Method:      add_subscription
      Principal:   root@spot (0/60001)
      Path:        /solaris2/TAS/CCMS/profile_organizer
       Trans Id:
         {
           1480943038:1,1480943038:1,4:190
         },
         {
           1480943038:1,1480943038:1,4:192
         }
         #3
  Input Data: (encoded):
         {
           {
             {
               "1480943038.1.580#TMF_CCMS::ProfileManager#" "SwPacks"
             }
             "OBJECT_NIL" "" ""
           }
           0 false
           {
             0
           }
         }

In the wtrace output, you can find the type of data block being viewed. The loc line element refers to a local method. The rem line element refers to a remote method. These elements include the following type codes:

ic

Input object call

is

Input service call

oc

Output object call

os

Output service call

After you have set up tracing and generated the output, you might need to investigate a method listed in the output. To find a method, follow these steps:

1. From the odstat output, identify the thread ID (tid) where the error occurred. For more information about thread IDs, see Listing the Status of Current and Recent Object Calls.
2. Find the same thread ID in the wtrace output.
3. Identify the method, input data, and results for that method.
4. You can then identify the principal that ran the method, for example:

   Principal:   root@spot (0/60001)

   The first part is the user that ran the method, and the numbers in the parentheses are the user ID and group ID actually used to run the method.
   Note
   For HP-UX systems, when the numbers in parentheses are less than 0, the method is run as nobody.
5. After you gain experience running this test, you can manually run the method by using the objcall or idlcall commands to reproduce the problem and run tests.
   Note
   Typically, you should use the objcall and idlcall commands only under the guidance of authorized support personnel. If you are going to invoke any methods manually, be sure to review the Tivoli Management Framework Planning for Deployment Guide and the Tivoli Management Framework Reference Manual.

Debugging the Transaction Manager

Use the tmcmd command to force a specified transaction or subtransaction to a particular state. Your support provider might ask you to run the tmcmd command to assist in problem diagnosis. The tmcmd command is primarily useful when testing and debugging the transaction manager, which is linked inside the object dispatcher. Support might ask you to run this command to recover from a severe or unusual problem.

If you are using Application Development Environment to create your own transactions, use the tmcmd command to force a specified transaction or subtransaction to a particular state.

Displaying the Status of Current Transactions and Locks

You can examine current pending transactions, locks, and their states by using the tmstat command. Your support provider might ask you to run the tmstat command and send its output to assist in diagnosing problems.

Locks are used to ensure data consistency on a given resource. To determine if you have a process lock problem, you can monitor the odb.log file. If this file stays at a constant size or more importantly, consistently grows in size for no obvious reason, you could have a lock problem.

Last modified: March 15, 2008