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.
Introduction
When you open your box from BEA, you will find three CD-ROMS:
Checking Your Package
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."
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.
You need the following information and resources before installing BEA TUXEDO on a UNIX system.
Hardware and Software Prerequisites
For UNIX Systems
You need the following resources before installing the BEA TUXEDO/WS software on a Windows or Macintosh system:
For Windows and Macintosh Systems
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.
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.
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 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 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
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
Note:
On NT platforms, the default behavior is unbuffered I/O; no special arrangements are needed.
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.
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 Managing Files and Databases
Assigning File Ownership on UNIX Systems
Allocating Space
tmadmin
administrative commands.
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.
/
(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.
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.
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).
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.
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:
For All Platforms
Throughout the BEA TUXEDO system documentation this directory is referred to as " 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 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.
TUXDIR
" (formerly "ROOTDIR
").
For All Server Platforms Supporting the Web GUI
TUXDIR
that you specify.
$TUXDIR/udataobj/webgui
. You are prompted to supply your own paths for these files if you prefer to have them installed elsewhere.
webgui.html
) that is used by tuxadm
as the basis for many screens displayed during a Web GUI session.
$TUXDIR/doc
.
EXCEPTION: If you are installing BEA TUXEDO on an NT platform and the installation program detects an existing Web server, then a default directory appropriate for that Web server is used, instead.
$TUXDIR/udataobj/webgui/java
, or
tuxadm
)-Specify one of the following (unless the exception described below applies):
$TUXDIR/udataobj/webgui/cgi-bin
EXCEPTION: If the installation program detects Microsoft's Internet Information Server (IIS) in a standard directory, then tuxadm
is installed in a sub-directory called "scripts
" in the directory you specified, above, as the pathname for HTML files.
Note:
Do not specify $TUXDIR/bin
as your CGI directory. If you do, you risk having some other BEA TUXEDO system programs executed accidentally by an uninformed user of the Web browser. You may also introduce a security risk.
tuxadm
. This is the path for the directory in which Web clients will expect to find tuxadm
. The default is either /cgi-bin
or /scripts
.
$TUXDIR/doc
.
The BEA TUXEDO system uses an administrative password to protect the machine on which it is installed from administrative requests and operations (such as 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 For these reasons, you may have more than one administrative password in your The administrative password that you enter during installation is collected by the installation script and stored in:
Make sure the permissions on your The BEA TUXEDO System uses the UNIX operating system Interprocess Communication (IPC) resources.
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.
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:
Selecting an Administrative Password
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.
tlisten.pw
file on each existing machine with which you want that machine to communicate.
tlisten.pw
file. A single password file may contain no more than 20 passwords, with one password per line.
$TUXDIR/udataobj/tlisten.pw
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
Semaphores
SEMMNS
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
SEMMSL
.
SEMMSL
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
SEMMAP
should be equal to SEMMNI
.
SEMMNU
SEMMNU
must be at least as large as SEMMNS
.
SEMUME
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
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
MSGMAX
must be big enough to handle any BEA TUXEDO system application running on this machine.
MSGMNB
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
MSGMAP
should be the same as the number of message segments (MSGSEG
), which should be twice the size of MSGMNI
.
MSGSSZ
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
MSGTQL
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
SHMMAX
.
SHMSEG
SHMMAX * SHMSEG
. A value between 6 and 15 should be adequate.
SHMMNI
WSL
) is running.
SHMMIN
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
ULIMIT
needs to be large enough so that you can install the BEA TUXEDO system and build servers. We recommend 4 megabytes.
NOFILES
MAXUP
UID
specified in the application's UBBCONFIG
file. MAXUP
needs to be large enough to allow all of these processes to run.
NPROC
NREGION
NUMTIM
NUMTRW
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."