idsldaptrace, ldaptrace

Description

The ldaptrace command is an administration trace utility. You can use the idsldaptrace command to dynamically start or stop trace against a directory server. You can also use this command to set the message level and to specify the file name to which you want to redirect the output. If you want to use the LDAP trace facility, ldtrc, options, you must use (--) before the ldtrc options. The ldaptrace command is used in conjunction with IBM® support to solve specific problems.

To see syntax help for idsldaptrace, type idsldaptrace -?.

Synopsis

idsldaptrace | ldaptrace [-a port -l [on|off|clr|chg|info|dump] --[ldtrc options] 
             -d debuglevel -D adminDn -E token_pw -h hostname [-I] -K keyfile 
             -m debugLevel -N key_name -o debugFile -p port -P key_pw 
             -S token_label -t [start|stop] -v -w adminPW|? -x -X lib_path 
             -Z -1 sec:usec] -? 

Options

-a port

Specifies a port number for the administration server, idsdiradm, to listen. The default port is 3538. If this port number is not specified and -Z is specified, the default administration server secure port, 3539, is used.

-d debuglevel

Specifies to debug the program.

-D adminDN

Specifies the DN to bind to an LDAP directory server. The adminDN variable is a string-represented value.

-E token_pw

Specifies the token password to access a crypto device.

-h ldaphost

Specifies the host name of the system where an LDAP server and the administration server are running.

-I

Specifies a crypto device with key storage by using PKCS11.

-K keyfile

Specifies the name of the SSL or TLS key database file with the default extension of kdb. If the key database file is not in the current directory, specify the fully qualified key database file name. If a key database file name is not specified, this utility first looks for the presence of the SSL_KEYRING environment variable with an associated file name. If the SSL_KEYRING environment variable is not defined, the default keyring file is used, if present.

A default keyring file, ldapkey.kdb, and the associated password stash file, ldapkey.sth, are installed in the etc directory in IDS_LDAP_HOME. Where, IDS_LDAP_HOME is the installation path of IBM Security Verify Directory. The value of the IDS_LDAP_HOME variable varies depending on the operating system. The default path on various operating system is listed.

• AIX® operating systems: /opt/IBM/ldap/V10.0.2/
• Linux™ operating systems: /opt/ibm/ldap/V10.0.2/
• Windows™ operating systems: C:\Program Files\IBM\ldap\V10.0.2\
  Note: The C:\Program Files\IBM\ldap\V10.0.2\ path is the default installation location. The actual IDS_LDAP_HOME is determined during the installation.

For information about the default key database files and default certificate authorities (CAs), see IBM Security Verify Directory Version 10.0.2 Programming Reference.

If a keyring database file cannot be located, a hard coded set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of CAs that are trusted by the client. These types of X.509 certificates are known as trusted roots. For information about managing an SSL or TLS key database, see Administering section in the IBM Security Verify Directory documentation. Also, see the Security functions section.

This parameter effectively enables the -Z switch.

-l [on|off|clr|chg|info|dump] --[ldtrc options]

on

Activates the tracing facility. You can specify any of the following ldtrc options preceded by (--) symbol.

• [-m <mask>] where, <mask> = <products>.<events>.<components>.<classes>.<functions>
• [-p <pid>[.<tid>]]: traces only the specified process or thread
• [-c <cpid>]: traces only the specified companion process
• [-e <maxSeverErrors>]: stops tracing after the maximum number of server errors, maxSevereErrors, is reached
• [-s | -f <fileName>]: sends the output to shared memory or a file
• [-l [<bufferSize>] | -i [<bufferSize>]]: specifies to retain the last or the initial records, the default buffer size is 1M
• [-this <thisPointer>]: traces only the specified object
• [-perf]: traces only performance records

Remember: The tracing facility must be on, to trace the server data.

off

Deactivates the tracing facility.

clr

Clears the existing trace buffer.

chg

Changes the values for the following ldtrc options. The trace must be active before you can use the chg option.

• [-m <mask>] where, <mask> = <products>.<events>.<components>.<classes>.<functions>
• [-p <pid>[.<tid>]]: traces only the specified process or thread
• [-c <cpid>]: traces only the specified companion process
• [-e <maxSeverErrors>]: stops tracing after the maximum number of server errors, maxSevereErrors, is reached
• [-this <thisPointer>]: traces only the specified object

info

Gets information about the trace. You must specify the source file, which can be either a binary trace file or trace buffer and a destination file. The following example shows the information that the info parameter contains:

C:\>ldtrc info
Trace Version:1.00
Op. System:NT
Op. Sys. Version:4.0
H/W Platform:80x86

Mask: *.*.*.*.*.*
pid.tid to trace: all
cpidto trace: all
this pointer to trace: all
Treat this rc as sys err: none
Max severe errors: 1
Max record size: 32768 bytes
Trace destination: shared memory
Records to keep: last
Trace buffer size: 1048576 bytes
Trace data pointer check: no

dump

Dumps the trace information to a file. The trace information includes process flow data and server debug messages. You can specify the name of the destination file where you want to dump the trace. The default destination file and location of the file is as provided.

On AIX and Linux systems:

/var/ldap/ibmslapd.trace.dump

On Windows systems:

installationpath\var\ibmslapd.trace.dump

Note: The trace dump file contains binary ldtrc data that must be formatted with the ldtrc format command.

-m debuglevel

Sets the LDAP debug level to debuglevel in LDAP library. This option causes the utility to generate debug output to stdout. The debuglevel is a bit mask that controls which output is generated with values from 1 to 65535. For information about debug levels, see Debugging levels.

-N certificatename

Specifies the label associated with the client certificate in the key database file. If an LDAP server is configured to use server authentication only, a client certificate is not required. If the LDAP server is configured to use client and server authentication, a client certificate might be required. This parameter is not required if a default certificate / private key pair is assigned as the default. Similarly, certificatename is not required if there is a single certificate / private key pair in the designated key database file. This parameter is ignored if -Z or -K parameter is not specified.

-o debugfile

Specifies the output file name for the server debug messages.

-p port

Specifies a port for the LDAP server to listen. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP secure port, 636, is used.

-P keyfilepw

Specifies the key database password. Password is required to access the encrypted information in the key database file, which might include one or more private keys. If a password stash file is associated with the key database file, then the password is obtained from the password stash file. In this case, the -P parameter is not required. This parameter is ignored if -Z or -K is not specified.

-Q operation

Specifies the crypto device operation with PKCS11. The operation variable must be assigned one of the following values:

0: No accelerator mode
1: Symmetric 
2: Digest
3: Digest and Symmetric 
4: Random 
5: Random and Symmetric
6: Random and Digest
7: Random, Digest and Symmetric

-S token_label

Specifies the token label of the crypto device.

-t [start | stop]

Specifies to start or stop server tracing.

• start: Starts server trace data collection.
• stop: Stops server trace data collection.

-v

Indicates to run in verbose mode.

-w passwd | ?

Specifies the password for authentication. Use the ? prompt to generate a non-echoed password prompt. In UNIX™, use backslash \? to avoid matching single character file names. If you use the password prompt, it prevents your password from being visible through the ps command.

-x

Specifies to use FIPS mode processing. This mode is applicable with SSL or TLS only.

-X lib_path

Specifies the library path of the crypto device.

-Y

Specifies to use a secure LDAP connection by using Transport Layer Security (TLS). The -Y option is only supported when GSKit is installed.

-Z

Specifies to use a secure LDAP connection by using Secure Sockets Layer (SSL) and Transport Layer Security (TLS). The -Z option is only supported for SSL component entry, and only when GSKit is installed.

-1 sec:usec

Specifies the timeout for the connect() function in seconds and microseconds. The values provided for seconds and microseconds must be positive integers.

-?

Specifies to show the syntax format.

Security functions

See also