Section 1 - Commands

Command Reference

tlisten(1)

Name

tlisten—Generic listener process.

Synopsis

tlisten [-d device] -l nlsaddr [-u {uid-# | uid-name}] [-z bits] [-Z bits ]

Description

tlisten is a network-independent listener process that runs as a daemon process on BEA Tuxedo ATMI application processors and provides remote service connections for other BEA Tuxedo ATMI processes, for example, tmboot(1). The following command line options are used by tlisten.

-d device

Full pathname of the network device. This parameter is optional. For releases prior to version 6.4, it should be used if the underlying network provider requires it.

-l nlsaddr

Network address at which the process listens for connections. TCP/IP addresses may be specified in either of the following forms:

"//hostname:port_number"

"//#.#.#.#:port_number"

In the first format, tlisten finds an address for hostname using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

In the second example, the string #.#.#.# is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine. In both of the above formats, port_number is the TCP port number at which the tlisten process listens for incoming requests. The value of port_number can be either a name or a number between 0 and 65535.

Note: Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system.

If port_number is a name, it must be found in the network services database on your local machine. The address can also be specified in hexadecimal format when preceded by the characters "0x". Each character after the initial "0x" is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX or TCP/IP. The address can also be specified as an arbitrary string. The value should be the same as that specified for the NLSADDR parameter in the NETWORK section of the configuration file.

-u {uid-# | uid-name}

tlisten will run as the indicated user. This option supports the start up of tlisten as part of system initialization by root. This option is required if the user running tlisten is root. The tlisten process can therefore be started by root, but will not run as root. Non-root users of the tlisten command do not need to use the -u option. Non-root users can set the -u option, but it can only be set to their own user ID and is effectively a no-op. Each instantiation of a tlisten process on a processor is capable of supporting all BEA Tuxedo ATMI applications that use the same application administrator user ID.

-z [0 | 40 | 56 | 128]

Specifies the minimum level of encryption required when a network link is being established between a BEA Tuxedo administrative process and tlisten. 0 means no encryption, while 40, 56, and 128 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, link establishment fails. The default value is 0. This option is available only if a license for BEA Tuxedo Security (either International, or U.S. and Canada) is installed.

Note: The link-level encryption value of 40 bits is provided for backward compatibility.

-Z [0 | 40 | 56 | 128]

Specifies the maximum level of encryption allowed when a network link is being established between a BEA Tuxedo administrative process and tlisten. 0 means no encryption, while 40, 56, and 128 specify the length (in bits) of the encryption key. The default value is 128. This option is available only if a license for BEA Tuxedo Security (either International, or U.S. and Canada) is installed.

Note: The link-level encryption value of 40 bits is provided for backward compatibility.

The tlisten process authenticates most service requests. tlisten reads a file with a list of passwords, and any process requesting a service must present at least one of the passwords found in the file. If the APPDIR environment variable is set, passwords will be obtained from a file named APPDIR/.adm/tlisten.pw. If this file is not found, the system will look for TUXDIR/udataobj/tlisten.pw, which is created when the BEA Tuxedo ATMI system is installed. A zero-length or missing password file disables password checking. When running in this insecure mode, the tlisten and any process connecting to tlisten will generate a userlog warning message.

Processes that request services from tlisten, such as tmboot, find the passwords to be used during authentication in files on their own machines. They use the same methods as the tlisten to find their password files.

Environment Variables

TUXDIR must be set and exported before the tlisten command is invoked.
LD_LIBRARY_PATH must be set for SVR4 applications that use shared objects. It must be set to TUXDIR/lib prior to starting the tlisten process. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.
APPDIR is set to provide the location of the tlisten password file.
ULOGPFX can be used to direct the file in which log messages are placed.

Note: During the installation process, an administrative password file is created. When necessary, the BEA Tuxedo ATMI system searches for this file in the following directories (in the order shown):

APPDIR/.adm/tlisten.pw
TUXDIR/udataobj/tlisten.pw

To ensure that your administrative password file will be found, make sure you have set the APPDIR and/or the TUXDIR environment variables.

Link-level Encryption

If the link-level encryption feature is in operation between tlisten and a requesting process such as tmboot, link-level encryption will be negotiated and activated before authentication occurs.

Termination

The only way to stop a tlisten process with normal termination is by sending it a SIGTERM signal.

Recommended Use

We recommend that you start one tlisten process for each application upon system startup. Remember to set the TUXDIR and APPDIR environment variables before invoking tlisten.

One alternative method for starting the tlisten process is to start it manually. The -u option can be omitted if the tlisten process is started by the application administrator. Duplicate tlisten command invocations using the same network address will terminate automatically and gracefully log an appropriate message.

Network Addresses

Suppose the local machine on which the tlisten is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the tlisten should accept requests is 2334. Assume that port number 2334 has been added to the network services database under the name bankapp-nlsaddr. The address specified by the -l option can be represented in the following ways:

//155.2.193.18:bankapp-nlsaddr
//155.2.193.18:2334
//backus.company.com:bankapp-nlsaddr
//backus.company.com:2334
0x0002091E9B02C112

The last of these representations is hexadecimal format. The 0002 is the first part of a TCP/IP address. The 091E is the port number 2334 translated into a hexadecimal number. After that each element of the IP address 155.2.193.12 is translated into a hexadecimal number. Thus the 155 becomes 9B, 2 becomes 02, and so on.

For a STARLAN network, a recommended address of uname.tlisten usually yields a unique name.

Windows Control Panel Applet

Administrative privileges on a remote Windows machine are required in order to start a tlisten process on that machine through the Control Panel Applet.