Boot, Shutdown and Config File Commands

Booting the System/T Application

This chapter covers several administrative responsibilities, including detailed descriptions of commands used to get a System/T application running. The major sections of the chapter are as follows:

Propagating Files

For a networked System/T application to work, certain files must be available on all nodes. Some files, notably TUXCONFIG, are propagated automatically by the TUXEDO System. Many more must be manually placed on each node by the administrator.

Here's a summary (in rough chronological order):

APPDIR
The application directory named in the APPDIR variable must be created on each node. It is helpful if this directory has the same pathname on all nodes.

a.out files
Application servers must be built once for each processor type and propagated manually. Store them in TUXDIR/bin or APPDIR, or they may be in a directory in the PATH contained in the ENVFILE specified in the *MACHINES section.

Field Tables
View Files
Depending on the requirements of application services, field tables and view description files must be manually propagated to nodes where they are used and recompiled.

tlisten
The tlisten process must be started on each node of a networked System/T application. The execution must take place before the application is booted.

TUXCONFIG
Is propagated automatically by tmboot(1) to all nodes in the configuration of the application.

The binary configuration file, TUXCONFIG, can be changed in three ways:

Commands for Loading and Unloading the Configuration File

This section describes tmloadcf(1), tmconfig(1) and tmunloadcf(1).

tmloadcf

The tmloadcf command must be invoked by the System/T administrator. It parses the UBBCONFIG file and loads the binary TUXCONFIG file on the master node. If the SECURITY parameter has been specified in the *RESOURCES section, tmloadcf prompts for the application password.

There are two options that cause tmloadcf to produce information without loading the TUXCONFIG file.

-c
causes the program to print the minimum IPC resources needed for the configuration, but does not load or update TUXCONFIG. This option is also available in tmboot and some pertinent information about message and queue sizes appears later in this chapter under the heading "Message Size and Queue Length".

-n
checks the syntax of the UBBCONFIG file, but does not load or update TUXCONFIG. If it finds a fatal error in syntax, it issues a warning message and quits.

If neither the -c or the -n option is specified, tmloadcf first parses the UBBCONFIG file. If that phase ends successfully, the program goes on to load the binary version into the device or file indicated in the TUXCONFIG environment variable. If no TUXCONFIG file exists at the target location, the program prompts as follows: 


Initialize TUXCONFIG file: path [y, q]?
If a TUXCONFIG file does exist at the target location, the program prompts as follows: 

Really overwrite TUXCONFIG file [y, q]?
A -y option on the command line suppresses the prompts; the program assumes a "yes" answer to either prompt.

tmloadcf provides a -b option that is used to specify the number of blocks tmloadcf should allocate when creating a new TUXCONFIG file. If the number of blocks specified is too small to hold the file, tmloadcf displays the minimum number of blocks required (additional space should be allocated for growth). This option is not recommended for normal UNIX files and should always be used for raw devices to specify the exact size of the device. If the -b option is not specified, tmloadcf creates a file large enough to hold TUXCONFIG.

If the TUXCONFIG file already exists when tmloadcf is invoked, the -b option is ignored. For an existing TUXCONFIG, tmloadcf manages the space requirements of each table (configuration section) and expands the size of a table as needed if the entries increase beyond the limits of the initial allocation.

These are the key things to remember:

tmconfig

The tmconfig command can be used by the System/T administrator to make changes to the TUXCONFIG file while the application is running. The command manages a buffer that contains fields to be added to or changed in TUXCONFIG; the buffer can be updated using any available text editor. Key fields can not be changed and some resources can be updated only when not active. See the tmconfig(1) manual page in the BEA TUXEDO Reference Manual: Section 1 for details.

A side effect of using tmconfig is that your binary configuration file, TUXCONFIG, can get out of synch with your ASCII configuration file, UBBCONFIG. You can prevent this by making it a rule always to unload TUXCONFIG with tmunloadcf after using tmconfig. When quitting from tmconfig, you are prompted whether or not to dump a backup copy of the configuration.

tmunloadcf

The tmunloadcf command is useful for getting a copy of the TUXCONFIG file in a form that can be edited, transported between unlike machines, or kept for backup. It can be run only by the administrator.

The tmunloadcf command translates the TUXCONFIG file to its ASCII format and writes the results to its standard output. It requires the TUXCONFIG environment variable to be set and exported.

About the only thing that can go wrong is if the TUXCONFIG environment variable does not point to an existing TUXCONFIG file or you are not the administrator.

To save the output, you must redirect it to a file. It is good practice to write-protect your original ASCII configuration file as a backup copy.

Creating the TLOG Device

As described in Chapter 5, "Distributed Transaction Processing," several parameters in the *MACHINES section are used to define a global transaction log (TLOG). The System/T administrator must manually create the device list entry for the TLOGDEVICE on each machine where a TLOG is needed. It can be done either before or after TUXCONFIG has been loaded, but must be done before the system is booted. Here is a procedure for creating an entry in the UDL for the TLOG device:

Step 1:
On the master node with the application inactive, invoke tmadmin -c.

Step 2:
Enter the command: 

crdl -z config -b blocks
where -z config specifies full pathname for the device where the UDL should be created (and where the TLOG will reside), and -b specifies the number of blocks to be allocated on the device. config should match the value of the TLOGDEVICE parameter in the *MACHINES section. If config is not specified, it defaults to the value of the TUXEDO System environment variable FSCONFIG.

Step 3:
Repeat Steps 1 and 2 on each node of your application that is involved with global transactions.

If the TLOGDEVICE is mirrored between two machines, Step 3 is not required on the paired machine.

The BBL initializes and opens the TLOG during the boot process.

You may wonder why the value of config defaults to the FSCONFIG value in the crdl command. Here's the explanation. To be recoverable, the TLOG needs to be on a device that can be mirrored. Since the TLOG is too small to warrant having a whole disk partition to itself, the expectation is that the TLOG will be stored on the same raw disk slice as the application's databases. FSCONFIG is the environment variable used by TUXEDO System/D to point to the UDL of the database. Therefore, the tmadmin crdl command defaults to FSCONFIG. If the TLOG and database co-exist on the same device, then the UDL entry will be created as part of creating the database and the above steps are not needed. If your application is set up differently, it is an easy matter to override the default and locate the log device explicitly.

TUXEDO System File System Maintenance

The simple procedure above described how to create a new System/T file system that can be used to hold the TLOG. It is sometimes necessary to add new devices or space to an existing configuration or the administrator may want to check on the space usage. These commands are available using tmadmin -c, whether or not the system is booted.

It is possible that the UDL exists on config but does not have sufficient space for the log. Space on a new device can be allocated to an existing System/T file system by using 


crdl -z config -b blocks new_device
where new_device specifies the full pathname for the new device where space is to be allocated. This creates a new entry on the UDL and the space is available for any tables that are created on config (for example, this procedure can be used for the TUXCONFIG when there is not enough space for a modified configuration, for allocating a new TLOG, or growing the size of the TLOG by deleting an old log and then creating a larger one). If you are doing several commands using the configuration, it is possible to set the default configuration using 

d -z config
so that you do not need to enter the -z option on each command.

Under rare circumstances, a device will not start at offset 0. This might happen if some space was allocated on a device (less than the entire device) to a System/T file system, and more space on the same device is available to be allocated. In this case, the second entry would be allocated by using 


crdl -z config -b blocks -o new_device_offset new_device
where new_device_offset specifies the offset of the new space being allocated on the device (note that the option is lower-case o). In this case, since the first entry on the UDL is allocated at offset 0, TLOGOFFSET and/or TUXOFFSET would be set to 0, not the offset of the new device (the System/T programs need to find the UDL and from there can determine the offset of other available space).

A second (more rare) reason that a device does not start at offset 0 is if a single raw device is shared, for example having a UNIX file system followed by a System/T file system on the same device (this is dangerous because the raw device must be writable by the System/T administrator and it is possible to over-write the UNIX file system). If the first entry on the UDL does not start at offset 0 (as in this example), then the device offset must be specified everywhere that the device is referenced. The entry would be allocated by using 


crdl -z config -b blocks -o offset -O offset new_device
where offset is the offset of the space to be allocated for the System/T file system (UDL and tables). Note that the -o (lower-case o) specifies the offset of the UDL and -O (upper-case O) specifies the offset of the new device space being allocated, which in this case are the same. Any devices that are created subsequently on this configuration must use both the -o option with the offset of the first entry, and the -O option with the offset of the new entry (the offset could be 0 if a new device is being specified). Since the first entry on the UDL is not allocated at offset 0, TLOGOFFSET and/or TUXOFFSET must be set to the offset of the first entry. This is the only case where TLOGOFFSET and TUXOFFSET would need to be set in the UBBCONFIG file, and the TUXOFFSET environment variable must be set when running all System/T application and administrative processes.

It is possible to list the current UDL using 


lidl -z config
where config was created using the above procedures. If the first entry was created with an offset other than 0, then ``-o offset'' must be specified in addition to the configuration device. In verbose mode, this command will list not only the space initially allocated for each device entry but also how much space is free.

It is also possible to list what tables exist on the configuration using 


livtoc -z config
where config was creating using the above procedures. If the first entry was created with an offset other than 0, then ``-o offset'' must be specified in addition to the configuration device. This command lists the table name, device number, offset within the device, and number of pages for each table. The first two tables will always be VTOC and UDL. TUXCONFIG table names are of the form _secname_SECT where secname is the name of the section in the UBBCONFIG file. The TLOG table name is based on the TLOG parameter in the UBBCONFIG file, and defaults to ``TLOG''. In the rare case where two applications share a single System/T file system for the TLOGDEVICE, the TLOG parameter must be different for each application. Note that since the table names for the TUXCONFIG are fixed, it is not possible for two applications to share the same System/T file system for TUXCONFIG.

Booting the system

The command tmboot starts a System/T application using the configuration in the TUXCONFIG file named in the TUXCONFIG environment variable. That's a simple enough statement, but the booting process can be considerably more complex. In this section we will cover tmboot from a number of angles to provide information on the following topics:

Most of the information in this section can be found on the tmboot manual page. The only command line options not discussed in detail in this chapter are -y, -q and -n, which do the following:

-y
suppresses a prompt about whether you want to boot or not
-q
suppresses warning messages
-n
prints the execution sequence without performing it

Booting can also be done from tmadmin, and the capabilities described in this section apply equally to booting from tmadmin using the boot command.

Who May Boot and Where

Apart from root, who can do pretty much anything, the only authorized user of tmboot is the System/T administrator; in other words, the owner of the UID specified in the configuration file.

The command must be invoked on the machine identified by the MASTER parameter in the configuration file. This is the machine where the TUXCONFIG file is located. (The BACKUP MASTER is also a valid location if the BACKUP is acting as the MASTER. There is more on the whole MASTER/BACKUP subject in Chapter 8.)

How to Boot the Entire Configuration

If the tmboot command is invoked with none of the options that limit the extent of the boot, then the entire configuration is booted.

tmboot uses the TUXCONFIG environment variable to find the configuration to be booted. It propagates the master TUXCONFIG to each node.

If MODEL is set to MP, a DBBL is started on the MASTER node and BBLs are started on each processor named in the *MACHINES section.

Administrative servers (BBLs and the DBBL) are booted first. If a BBL fails to boot, other servers on that machine are not booted. If the DBBL fails to boot, the entire boot process fails.

For each group in the *GROUPS section, TMS servers are booted according to the TMSCOUNT and TMSNAME parameters for the group. TMS servers are booted ahead of their associated application servers.

Application servers are booted in the order specified by their SEQUENCE parameter or, if sequence numbers are not specified, in the order in which they occur in the configuration file.

If a server can not be started, tmboot writes a diagnostic message to ULOG and continues. If a BBL cannot be started, application servers that depend on that BBL are ignored. A failure to start the DBBL scrubs the whole project.

If a server is configured with an alternate LMID and fails to start on its primary machine, tmboot automatically attempts to start the server on the alternate machine and, if successful, sends a message to the DBBL to update the server group section of TUXCONFIG.

How to Boot Portions of the Configuration

Several of the tmboot command line options (9 to be exact) have the effect of limiting the scope of the command. Here's a summary:

-l lmid
start servers in the *SERVERS section whose SRVGRP is associated with lmid.

-g grpname
start servers in the *SERVERS section whose SRVGRP is grpname

-i srvid
start servers in the *SERVERS section whose SRVID is srvid

-s aout
start servers in the *SERVERS section if their name is aout

-o sequence
start servers in the *SERVERS section if their sequence number is sequence

-S
start all servers in the *SERVERS section

-A
start all administrative servers, that is, the DBBL, BBLs and BRIDGE processes

-B lmid
start a BBL on the processor identified by lmid

-T grpname
start all TMS servers for group grpname

When combinations of the -l, -g, -i, -o and -s options are used together, only servers that satisfy all qualifications are booted.

No harm results from trying to boot a server that is already running.

Boot and Runtime Server Parameters

As noted in the discussion in Chapter 3 on the *SERVERS section of the configuration file, some parameters of an entry are used by tmboot, others are read from the bulletin board by the server itself after it has been started. The boot parameters are: 

CLOPT	SRVGRP	MIN
SEQUENCE	SRVID
and the rest are runtime parameters.

Servers are booted with the variables TUXDIR, APPDIR, TUXCONFIG and TUXOFFSET placed in their environment. Others variables may be put into the environment by putting them in the *MACHINES section ENVFILE and the *SERVERS section ENVFILE. Overriding the four variables listed above in either of the ENVFILE files has no effect.

The current directory for booted servers is APPDIR.

Search Path for Servers

When tmboot is trying to start a server, if the AOUT value for the server is not an absolute pathname, tmboot first looks for the executable in $APPDIR then in $TUXDIR/bin as those values are listed in the *MACHINES section, then in /bin, and then in PATH, if specified, in the *MACHINES section ENVFILE.

The -e Option

The -e option takes as an argument a command to be executed if any process fails to boot successfully. The command can be any program, script or sequence of commands understood by the shell command interpreter. You can use it, for example, to bail out of the boot procedure in the event something fails to boot. (Normal processing is to send a message to ULOG and continue to boot subsequent servers.)

Error Messages

If TUXCONFIG is set to a non-existent file, two fatal error messages are displayed: 


error processing configuration file
configuration file not found

If tmboot is run on a node that is not the ACTING MASTER, this error message is displayed: 


tmboot cannot run on a non-master node.
This is a fatal error. The program quits.

If tmboot is run on an active non-master node, the following error message is displayed: 


tmboot cannot run on a non acting-master node in an active application
This is a fatal error. The program quits.

There are other fatal errors caused by syntax errors not caught by tmloadcf. Here are the messages displayed. 


Multiple nodes not allowed in *MACHINES for non-LAN application
NLSADDR not specified for node node name.

The -c Option

The -c option can be used to produce a report on the minimum IPC resources needed for the configuration. This does not include IPC resources that may be needed by the data entry system or a resource manager.

Message Size and Queue Length

While many of the IPC parameters are critical to the operation of your System/T application, we particularly want to call your attention to the MSGMAX, MSGMNB and related UNIX system kernel parameters. When System/T is asked to send a message larger than 75% of the maximum message queue length (MSGMNB) it puts the message in a UNIX file, sends a very small message to the recipient and sends the file by file transfer. This produces a significant degradation in performance, and not coordinating the IPC settings can lead to this happening. For example, if you bump up MSGMAX to 16K (from the 8K default) and leave MSGMNB at its 16K default, a message within your maximum limit can be sent via file transfer because of hitting 75% of queue size.

On the other hand, if your application typically sends small messages and you set your parameters to allow for a lot of small messages on a queue, you can run into the file transfer degradation if you try to send a message that exceeds MSGMAX. The troublesome part of parameter setting is that the problem can be a sleeper; you can run without failure for a period of months and then begin to experience problems. We have two suggestions: be diligent in forecasting your application's requirements and keep checking on queue usage and message sizes as your application gets broken in.

The subject of setting IPC parameters is discussed at greater length in the BEA TUXEDO Installation Guide.

Servers Standard Files

The server's standard input file descriptor is closed when the server is booted. The standard output and standard error are sent to $APPDIR/stdout and $APPDIR/stderr, respectively. All input and output is under program control. Application shutdown can be done for the whole application, or for portions of it using the same option flags that were described above for tmboot.

There are some other options that are of special interest.

-P lmid
tmshutdown attaches to the bulletin board on the specified processor, checks to make sure it is partitioned (that is, has lost communication with the DBBL), and shuts down all administrative and application servers.

-R
shuts down servers on their original processors without deleting their bulletin board entries. This is done in preparation for migration to another processor. -l lmid and -g grpname options can be used to limit the scope of the -R to certain parts of the configuration; -R -s aout is illegal.

-c
shuts down BBLs even if clients are still attached.

-w delay
forces a shutdown after delay seconds without waiting for processes to end gracefully.

Configuration shutdown can also be done from tmadmin using shutdown.