[Top] [Prev] [Next] [Bottom]

1. Preparing to Install the BEA TUXEDO System

Introduction

Congratulations on your new BEA TUXEDO System! You are about to embark on an exciting new project that will enhance the performance and reliability of your enterprise. This book will help you take the first step in that project: installing the BEA TUXEDO system on your platform of choice.

BEA TUXEDO system is a sophisticated software product; it should not be installed without proper planning. This chapter covers the following topics.

Checking Your Package

When you open your box from BEA, you will find three CD-ROMS:

If you have also licensed the BEA TUXEDO Web Administration GUI to administer your BEA TUXEDO system applications, the package will be enabled automatically when the license file is installed. Refer to Chapter 2 of this guide, "Installing the BEA TUXEDO System," for license installation instructions.

If you have purchased any of the following add-on packages, you will receive it on a separate CD-ROM:

For a list of the platforms supported for this release of the BEA TUXEDO system, see Appendix A, "Platform Data Sheets."

Hardware and Software Prerequisites

The BEA TUXEDO system software must be installed on each machine that will participate in a BEA TUXEDO system application.

Note: We advise against trying to share the BEA TUXEDO system executables across remote file systems; this practice has proven to be unreliable in the past.

The BEA TUXEDO system Web-based GUI for administration must be installed in a file system that supports long filenames (that is, those containing more than 14 characters).

Details about the hardware and software prerequisites for all platforms on which the BEA TUXEDO system is supported are given in Appendix A, "Platform Data Sheets." Please check the data sheet for each platform on which you plan to install the BEA TUXEDO system.

For UNIX Systems

You need the following information and resources before installing BEA TUXEDO on a UNIX system.

For Windows and Macintosh Systems

You need the following resources before installing the BEA TUXEDO/WS software on a Windows or Macintosh system:

Managing Files and Databases

This section explains how to assign ownership of the BEA TUXEDO system files to the responsible administrator, and how to set up your disk to accommodate those files.

Assigning File Ownership on UNIX Systems

If you are installing the BEA TUXEDO system on a UNIX system, we strongly recommend that you create a separate user account for the BEA TUXEDO system administrator and give ownership of the BEA TUXEDO system files to that account.

Allocating Space

A running BEA TUXEDO system application needs disk space for system files and for the application's database(s). You won't use this space until you begin to develop or run your BEA TUXEDO system application, but it is important to plan for it before installing the software. To help explain what is involved here, we need to describe how the BEA TUXEDO system handles files. The BEA TUXEDO System Disk Management Interface

The BEA TUXEDO system has a facility, the Disk Management Interface (DMI), which manages logical files within a single disk device or set of devices. Among other things, it stores binary configuration tables and the transaction log.

The BEA TUXEDO system disk management software supports the notion of a BEA TUXEDO system file system distinct from any operating system file system. (For the rest of this discussion, we're going to use the term OS file system to cover any operating system file system.)

Administrative access to the DMI to create, initialize, or destroy entries in the BEA TUXEDO system file system is through tmadmin administrative commands.

There are two ways the logical files managed by the DMI can be stored physically. Physical storage can be on an OS file system. Alternatively, disk space outside the control of all OS file systems can be set aside for BEA TUXEDO; files reside on device special files in that space and are managed directly by the DMI. Space outside the OS file system is usually referred to as raw disk space. Not only is I/O faster when done by system calls reading directly from and writing directly to device special files on raw disks, raw disk space is preferred when it is important to know for certain that a physical write() has been done. With the OS file system, the precise moment that a write() is done can not be relied on. In the BEA TUXEDO system, accurate control of the write operation is particularly important for entries in the transaction log. With multiple users, it is also an important element in assuring database consistency. Arranging for Raw Disk Space

If you decide to use raw disk space for your BEA TUXEDO system application, you may find that the hard disk devices on your system are fully allocated to file systems such as / (meaning root), /usr, and other UNIX file systems. If that is the case, it is necessary to repartition your hard disk device in order to set aside some partitions that are not for an OS file system. Information on how to do this can be found in the system administration documentation for your particular platform.

Note: On NT platforms, the default behavior is unbuffered I/O; no special arrangements are needed. How the BEA TUXEDO File System Is Organized

A BEA TUXEDO system file system has a Volume Table of Contents (VTOC) that lists files on a set of devices named in the Universal Device List (UDL). The UDL contains information about the location of the physical storage space for BEA TUXEDO system tables. All System Tables on the Same Device?

In a BEA TUXEDO system application, all of the system files might be stored together on the same raw disk slice or OS file system file. While it is possible to use regular OS file system files for the configuration tables, it is strongly recommended that the transaction log, TLOG, be stored on a raw disk device. Since the TLOG seldom needs to be larger than 100 blocks and since disk partitions are always substantially larger than that, it may make sense to use the same device for everything. The pathname of the device needs to be contained in both the TUXCONFIG and the FSCONFIG environment variables. Listing 1-1 shows approximately how the contents might appear.

Listing 1-1 VTOC and UDL Diagram 
Output based on setting FSCONFIG=$TUXCONFIG, and invoking tmadmin:

No bulletin board exists. Entering boot mode.

> livtoc
Volume Table of Contents on /usr2/bank/tuxconfig:
0: VTOC: Device 0 Offset 0 Pages 7
1: UDL: Device 0 Offset 7 Pages 28
2: _RESOURCE_SECT: Device 0 Offset 35 Pages 3
3: _MACHINES_SECT: Device 0 Offset 38 Pages 40
4: _GROUPS_SECT: Device 0 Offset 78 Pages 40
5: _SERVERS_SECT: Device 0 Offset 118 Pages 40
6: _SERVICES_SECT: Device 0 Offset 158 Pages 20
7: _ROUTING_SECT: Device 0 Offset 178 Pages 100
8: _NETWORK_SECT: Device 0 Offset 278 Pages 20
9: _MIBPERMS_SECT: Device 0 Offset 298 Pages 2

# If the TLOG is stored on the same device, there will be an
# entry something like:

9: TLOG1: Device 0 Offset 236 Pages 100
> q

The BEA TUXEDO system administrator must make sure raw disk slices are available as needed on each node participating in an application. The size of elements in the BEA TUXEDO system file system are shown in Table 1-1.

Table 1-1 Size of BEA TUXEDO System Tables
Entity 512-byte Pages

VTOC

1

TUXCONFIG

270

TLOG

100 (default)

UDL

28

TOTAL

399

The size for the TUXCONFIG file is larger if there are more entries in the configuration file, UBBCONFIG. The administrator is encouraged to allocate additional space for dynamic reconfiguration and for growth of the application. The default block size assumed by the crdl subcommand of tmadmin is 1000 blocks, which should be adequate for the initial installation. Space for Application Databases (If You Are Using /D)

If your BEA TUXEDO system application is using BEA TUXEDO System/D as a resource manager, your database tables can be listed in the same UDL and managed by the BEA TUXEDO system VTOC. If another resource manager is used, you should check the installation instructions for that product to see how its space requirements affect your BEA TUXEDO system planning. Space for Queue Spaces (If You Are Using /Q)

If your BEA TUXEDO system application is using /Q for store-and-forward queue management, your queue space can be listed in the same UDL and managed by the BEA TUXEDO system VTOC. Space for Application Servers

As you are calculating the space requirements for the BEA TUXEDO system, you should also consider the requirements of the servers that perform the work of the application. These requirements will be specified by the application, and they are over and above the requirements for BEA TUXEDO system itself (unless otherwise specified).

Selecting Directories for BEA TUXEDO System Files

During the installation process you will be prompted to make decisions about where, in your file system, a number of your BEA TUXEDO system directories and files will be installed. To help you plan for this part of the process, this section describes the directories and files about which you will be prompted to make a decision.

For All Platforms

You will be prompted for a pathname for the base directory of your BEA TUXEDO system software. There is no restriction on the location of this directory, as long as it meets the following requirements:

Throughout the BEA TUXEDO system documentation this directory is referred to as "TUXDIR" (formerly "ROOTDIR").

For All Server Platforms Supporting the Web GUI

If (a) you are installing BEA TUXEDO on a server platform, and (b) you have purchased the Web-based graphical user interface (GUI) for application administration, you will be prompted, during the installation process, to accept or replace the default pathnames and filenames used for the Web GUI components. These default pathnames and filenames are based on the value of TUXDIR that you specify.

If you are running a commercial web server, you may find the default settings inappropriate, especially if your server is handling requests from both the BEA TUXEDO system Web GUI and other Web programs on the same port. To accommodate this situation, BEA TUXEDO system lets you choose between accepting the defaults and assigning your own pathnames and filenames. The rest of this section describes the choices you will be given.

Selecting an Administrative Password

The BEA TUXEDO system uses an administrative password to protect the machine on which it is installed from administrative requests and operations (such as tmboot) that are not authorized. Whenever administrative communications arrive on this machine through the tlisten and wlisten gateway processes, the BEA TUXEDO system authenticates them by means of the password.

You assign an administrative password during the installation process (to the machine on which the BEA TUXEDO system is being installed) by entering the password of your choice after the appropriate prompt. The password must be a string of alphanumeric characters in clear-text format. It may contain no more than 80 characters.

A common password is required for two machines in a BEA TUXEDO system domain to communicate successfully. For this reason, you must use the same password whenever you install the BEA TUXEDO system on multiple machines for a single domain. As described above, you will be prompted to provide the password during the BEA TUXEDO installation process. If, however, for some reason, you use a different password for one machine, you must add that password to the tlisten.pw file on each existing machine with which you want that machine to communicate.

For these reasons, you may have more than one administrative password in your tlisten.pw file. A single password file may contain no more than 20 passwords, with one password per line.

The administrative password that you enter during installation is collected by the installation script and stored in: 

$TUXDIR/udataobj/tlisten.pw

Make sure the permissions on your tlisten.pw file are set such that the file is readable only by the BEA TUXEDO system administrator.

Configuring the UNIX Operating System for BEA TUXEDO

The BEA TUXEDO System uses the UNIX operating system Interprocess Communication (IPC) resources. Note: Equivalent services are available on operating systems other than the UNIX system. The BEA TUXEDO system provides an NT Service called the BEA TUXEDO IPC Helper, which facilitates inter-process communication. MVS/OpenEdition provides IPC mechanisms that are basically the same as those provided on a UNIX system, but that cannot be configured from within the OpenEdition environment. (See the MVS/OE documentation for instructions on administering these mechanisms.)

IPC resources are configured by three sets of tunable parameters that control the amount of shared memory (prefix SHM), number of semaphores (prefix SEM), and size of message queues and messages (prefix MSG).

The settings for these parameters are application dependent. Most UNIX systems, however, are shipped with default values that are too low for a BEA TUXEDO system application.

The following sections describe the IPC parameters and provide guidelines for configuring them. Because these parameters vary across different versions of the UNIX system the descriptions below are generic. Check Appendix A for the exact parameter names and defaults for each platform and for information on how to change the parameters. If you change a parameter, you will need to rebuild the kernel and reboot the operating system using the standard administrative tools. Consult your operating system administrator or the system administrator's guide for your platform for details.

If your BEA TUXEDO system application is distributed, the minimum IPC resources must be available on every UNIX platform participating in the application.

Semaphores

Every process that participates in a BEA TUXEDO system application requires a semaphore. When the application is booted the number of semaphores configured in the operating system is checked, and the boot will fail if the configured number is not high enough.

The following semaphore parameters may need to be adjusted:

SEMMNS
Maximum number of semaphores in the system. The minimum requirement for SEMMNS is 
MAXACCESSERS - MAXWSCLIENTS + 13

where MAXACCESSERS is the maximum number of BEA TUXEDO system processes on a particular machine (including servers and native clients) and MAXWSCLIENTS is the maximum number of workstation clients. Both of these parameters are specified in the application's UBBCONFIG file. For more information about UBBCONFIG, see the BEA TUXEDO Administrator's Guide or the ubbconfig(5) reference page.

SEMMNI
Maximum number of active semaphore sets. See SEMMSL.

SEMMSL
Maximum number of semaphores per semaphore set. SEMMNI and SEMMSL are commonly chosen so that their product equals SEMMNS. The BEA TUXEDO system does not perform semaphore operations on semaphore sets; however, it attempts to allocate as many semaphores per semaphore set as possible.

SEMMAP
Size of the control map used to manage semaphore sets. SEMMAP should be equal to SEMMNI.

SEMMNU
Number of undo structures in the system. Because an undo structure is needed for each process that can access the Bulletin Board, SEMMNU must be at least as large as SEMMNS.

SEMUME
Maximum number of undo entries per undo structure. The value 1 suffices.

Message Queues and Messages

The BEA TUXEDO system uses UNIX system messages and message queues for client/server communication. Examples of such messages are service requests, service replies, conversational messages, unsolicited notification messages, administrative messages, and transaction control messages.

Every MSSQ set (Multiple Servers, Single Queue) of servers and every individual server has a message queue for receiving requests. Every client has its own queue for receiving replies. Servers that specify the REPLYQ parameter also get individual reply queues.

The adjustment of kernel message parameters is important to the proper tuning of an application. Inappropriate values can lead to an inability to boot or severe performance degradation.

There are various message queue parameters. They limit various characteristics of the queue space including the total number of outstanding messages (MSGTQL), the total number of bytes that can be on one queue (MSGMNB), the size limit of an individual message (MSGMAX), the total number of message segments that can be outstanding at one time (MSGSEG), and the size of each segment (MSGSSZ).

Exceeding any of the above parameter limits results in what is known as a blocking condition. There is a special case for MSGMAX. Messages that exceed 3/4 of MSGMNB, or that are larger than MSGMAX, are placed in a UNIX file. A very small message with the filename in it is then sent to the recipient. This mode of operation is to be avoided, as it results in a severe reduction in performance.

An application deadlock can result if every process is blocked trying to send a message. For example, when clients fill up the message space with requests and servers are all blocked trying to send replies, since no server can read a message, there is a deadlock. Timeouts can break the deadlock sometimes, but no useful work will have been done.

Especially troublesome is a client that sends its requests with the TPNOREPLY flag. In no time, this practice can fill up either individual queues or the system message space, depending on the size of the messages. Such applications may have to implement their own flow control to limit the number of outstanding messages.

To summarize what has been said above, if clients or servers are blocking on their send operations (requesting services or sending replies), then there is potential for trouble. It is usually no problem, though, for a single server request queue to always be full, as long as there is space in the system for more messages on other queues.

There are performance implications to queue blocking conditions, both on the sending side and the receiving side. The UNIX operating system, when waking up blocked processes, wakes up all the processes blocked on a particular event, even if only one can proceed. The other processes just go back to sleep. This process scheduling overhead can be expensive.

For example, on an empty server request queue where there is more than one server (MSSQ), an arriving message wakes up all the idle (blocked) servers on that queue. In the case of a full server request queue, as each request is read by a server, the system wakes up all the blocked clients. Depending on the size of the messages, zero or more clients get to place their messages on the queue. The rest have to go back to sleep. Since there may be hundreds of clients in the system, the mass wakeup of all of these clients every time a service request is processed can severely degrade performance.

A properly tuned system rarely fills its queues. Enough slack should be left in the queues to handle the natural variability of the message flow. There are no magic answers. Tuning is very application dependent. The UNIX ipcs(1) command provides a snapshot of the queues so you can tell if they are full. You can try the TPNOBLOCK flag when sending requests. That way, clients can tell when queues are full, and they can slow down a bit. It might help to increase the scheduling priority of the servers whose request queues are full.

The following message parameters may need to be adjusted:

MSGMNI
Number of unique message queue identifiers. Each process participating in a BEA TUXEDO system application on a particular machine typically needs at least one message queue. This number is reduced if MSSQ sets are used, where multiple server processes share a single queue. For transaction processing, count an additional queue per server group for TMS processes. Thus, the minimum requirement for MSGMNI can be determined by this formula: 
MSGMNI = MAXACCESSERS + 7
 
+ (number of servers with REPLYQ)
 
+ (number of MSSQ sets)
 
- (number of servers in MSSQ sets)

MSGMAX
Maximum message size in bytes. MSGMAX must be big enough to handle any BEA TUXEDO system application running on this machine.

MSGMNB
Maximum message queue length in bytes. This number must accommodate the total size of all messages that are on a queue and have not been taken off by the associated process(es). The minimum value for MSGMNB is MSGMAX. Messages longer than 75% of MSGMNB are sent to a file instead of to a message queue-a situation that should be avoided because it severely degrades performance.

MSGMAP
Number of entries in the control map used to manage message segments. MSGMAP should be the same as the number of message segments (MSGSEG), which should be twice the size of MSGMNI.

MSGSSZ
Size of a message segment in bytes. A message can consist of several such segments. The value of MSGSSZ should be such that a multiple of MSGSSZ is equal to the size (including the BEA TUXEDO system header) of the most commonly sent message. This practice will avoid wasting space.

MSGSEG
Number of message segments in the system.

MSGTQL
Total number of outstanding messages that can be stored by the kernel. This is the maximum number of unread messages at any given time.

Shared Memory

In the BEA TUXEDO system environment shared memory is used for the Bulletin Board and for the control table of the workstation listener process (WSL). An application may also choose to use shared memory for its own purposes.

The following shared memory parameters may need to be adjusted:

SHMMAX
Maximum shared memory segment size in bytes. This number represents the largest shared memory segment that can be allocated. A process can, however, attach to more than one segment of size SHMMAX.

SHMSEG
Maximum number of shared memory segments per process. For a given configuration, the maximum amount of shared memory in bytes to which a process can attach is SHMMAX * SHMSEG. A value between 6 and 15 should be adequate.

SHMMNI
Maximum number of shared memory identifiers in the system. BEA TUXEDO requires one identifier per Bulletin Board and an additional identifier if the workstation listener (WSL) is running.

SHMMIN
Minimum shared memory segment size in bytes. This should always be set to 1.

Other Kernel Tunables

Experience with the BEA TUXEDO system has shown that some other UNIX system tunables may need to be set to higher values. These are very application dependent and do not apply to all applications. Appendix A includes information on the defaults and how to change them.

ULIMIT
Maximum file size. ULIMIT needs to be large enough so that you can install the BEA TUXEDO system and build servers. We recommend 4 megabytes.

NOFILES
Maximum number of open files per process. A BEA TUXEDO system server requires a minimum of four file descriptors.

MAXUP
Maximum number of processes per non-super user. The BEA TUXEDO system processes-servers and administrative processes-run with the UID specified in the application's UBBCONFIG file. MAXUP needs to be large enough to allow all of these processes to run.

NPROC
Maximum number of processes (system wide).

NREGION
Number of region table entries to allocate. Most processes have three regions: text, data, and stack. Additional regions are needed for each shared memory segment and shared library (text and data) attached. However, the region table entry for the text of a "shared text" program is shared by all processes executing that program. Each shared memory segment attached to one or more processes uses another region table entry.

NUMTIM
Maximum number of STREAMS modules that can be pushed by the Transport Layer Interface (TLI). A typical default value is 16; you should have it set to at least 256.

NUMTRW
The number of TLI read/write structures to allocate in kernel data space. A typical default value is 16; you should have it set to at least 256.

Calculating IPC Requirements

When the BEA TUXEDO system software has been installed and an application configuration file (UBBCONFIG file) is available, the tmloadcf command can be used to calculate the IPC resources needed to support the application. For more information, see the tmloadcf(1) reference page and Chapter 3, "Post-Installation Issues."


[Top] [Prev] [Next] [Bottom]