tmshutdown(1)

Name

tmshutdownShuts down a set of BEA Tuxedo servers.

Synopsis

tmshutdown [options]

Description

tmshutdown stops the execution of a set of servers or removes the advertisements of a set of services listed in a configuration file. Only the administrator of the bulletin board (as indicated by the UID parameter in the configuration file) or root can invoke the tmshutdown command. tmshutdown can be invoked only on the machine identified as MASTER in the RESOURCES section of the configuration file, or the backup acting as the MASTER, that is, with the DBBL already running (via the master command in tmadmin(1)). An exception to this is the -P option which is used on partitioned processors (see below).

With no options, tmshutdown stops all administrative, TMS, and gateway servers, and servers listed in the SERVERS section of the configuration file named by the TUXCONFIG environment variable, and removes the IPC resources associated with them. For each group, all servers in the SERVERS section, if any, are shut down, followed by any associated gateway servers (for foreign groups) and TMS servers. Administrative servers are shut down last.

Application servers without SEQUENCE parameters are shut down first in reverse order of the server entries in the configuration file, followed by servers with SEQUENCE parameters that are shut down from high to low sequence number. If two or more servers in the SERVERS section of the configuration file have the same SEQUENCE parameter, then tmshutdown may shut down these servers in parallel. Each entry in the SERVERS section may have an optional MIN and MAX parameter. tmshutdown shuts down all occurrences of a server (up to MAX occurrences) for each server entry, unless the -i option is specified; using the -i option causes individual occurrences to be shut down.

If it is not possible to shut down a server, or remove a service advertisement, a diagnostic is written on the central event log (see userlog(3c)). The following is a description of all options:

-l lmid

For each group whose associated LMID parameter is lmid, all servers in the SERVERS section associated with the group are shut down, followed by any TMS and gateway servers associated with the group.

-g grpname

All servers in the SERVERS section associated with the specified group (that is, for which the SRVGRP parameter is set to grpname) are shut down, followed by all TMS and gateway servers for the group. TMS servers are shut down based on the TMSNAME and TMSCOUNT parameters for the group entry. For a foreign group, the gateway servers for the associated entry in the HOST section are shut down based on GATENAME and GATECOUNT. Shutting down a gateway implies not only that the process itself is stopped; it also implies that the administrative service for the gateway and all advertised foreign services are unadvertised.

-i srvid

All servers in the SERVERS section for which the SRVID parameter is set to srvid are shut down. Do not enter a value for SRVID greater than 30,000; this indicates system processes (that is, TMSs or gateway servers) that should only be shut down via the -l or -g option.

-s aout

All servers listed in the SERVERS section with the name aout are shut down. This option can also be used to shut down TMS and gateway servers.

-o sequence

All servers in the SERVERS section for which the SEQUENCE parameter is set to sequence are shut down.

-S

All servers listed in the SERVERS section are shut down.

-A

All administrative servers are shut down.

-M

This option shuts down administrative servers on the master machine. The BBL is shut down on the MASTER machine, and the BRIDGE is shut down if the LAN option and a NETWORK entry are specified in the configuration file. If the MODEL is MP, the DBBL administrative server is shut down.

-B lmid

The BBL on the processor with the logical name lmid is shut down.

-T grpname

All TMS servers for the server group for which the SRVGRP parameter is set to grpname are shut down (based on the TMSNAME and TMSCOUNT parameters associated with the server group entry).

-w delay

Tells tmshutdown to suspend all selected servers immediately and waits for shutdown confirmation for only delay seconds before forcing the server to shut down by sending a SIGTERM and then a SIGKILL signal to the server.

Because the SIGKILL signal cannot be trapped, any process that receives it is terminated immediately, regardless of the code being executed by the process at that time. Such behavior may cause structural damage to the bulletin board if the process being stopped was updating the bulletin board when it was terminated.

Note: Servers to which the -w option may be applied should not catch the UNIX signal SIGTERM.

Note: When a server is shut down based on receipt of a SIGKILL signal, entries may remain in the bulletin board. When the bulletin board liaison (BBL) is due to shut down, these entries are detected and the BBL does not shut down. A second tmshutdown command may be required to complete system shutdown.

-k {TERM | KILL}

tmshutdown suspends all selected servers immediately and forces them to shut down in an orderly fashion (TERM) or preemptively (KILL).

Because the SIGKILL signal cannot be trapped, any process that receives it is terminated immediately, regardless of the code being executed by the process at that time. Such behavior may cause structural damage to the bulletin board if the process being stopped was updating the bulletin board when it was terminated.

Note: This option maps to the UNIX signals SIGTERM and SIGKILL on platforms that support them. By default, a SIGTERM initiates an orderly shutdown in a BEA Tuxedo server. If SIGTERM is reset by an application, the BEA Tuxedo system may be unable to shut down the server.

Note: When a server is shut down based on receipt of a SIGKILL signal, entries may remain in the bulletin board. When the bulletin board liaison (BBL) is due to shut down, these entries are detected and the BBL does not shut down. A second tmshutdown command may be required to complete system shutdown.

-y

Assumes a yes answer to a prompt that asks whether all administrative and server processes should be shut down. (The prompt appears only when the command is entered with none of the limiting options.)

When the -y option is specified, all services are unadvertised immediately from the bulletin board and any subsequent service calls fail.

-q

Suppresses the printing of the execution sequence on standard output. It implies -y.

-n

The execution sequence is printed, but not performed.

-R

For migration operations only, shuts down a server on the original processor without deleting its bulletin board entry in preparation for migration to another processor. The -R option must be used with either the -l or -g option (for example, tmshutdown -l lmid -R). The MIGRATE option must be specified in the RESOURCES section of the configuration file.

-c

Shuts down BBLs even if clients are still attached.

-H lmid

On a uniprocessor, all administrative and applications servers on the node associated with the specified lmid are shut down. On a multiprocessor (for example, 3B4000), all PEs are shut down, even if only one PE is specified.

-P lmid

With this option, tmshutdown attaches to the bulletin board on the specified lmid, ensures that this lmid is partitioned from the rest of the application (that is, that it does not have access to the DBBL), and shuts down all administrative and application servers. It must be run on the processor associated with the lmid in the MACHINES section of the configuration file.

The -l, -g, -s, and -T options cause TMS servers to be shut down; the -l, -g, and -s options cause gateway servers to be shut down; the -l, -g, -i, -s, -o, and -S options apply to application servers; the -A, -M, and -B options apply only to administrative processes. When the -l, -g, -i, -o, and -s options are used in combination, only servers that satisfy all the qualifications specified are shut down.

If the distributed transaction processing feature is being used such that global transactions are in progress when servers are shut down, transactions that have not yet reached the point at which a commit is logged after a precommit are aborted; transactions that have reached the commit point are completed when the servers (for example, TMS) are booted again.

Interoperability

tmshutdown must run on the master node. In an interoperating application the master node must be running the highest release available. tmshutdown detects and reports configuration file conditions that would lead to the shutting down of Release 4.2 administrative servers on Release 4.1 sites.

Portability

tmshutdown is supported on any platform on which the BEA Tuxedo server environment is supported.

Diagnostics

If tmshutdown fails to shut down a server or if a fatal error occurs, tmshutdown exits with exit code 1 and the user log should be examined for further details; otherwise it exits with exit code 0.

If tmshutdown is run on an active node that is not the acting master node, a fatal error message is displayed:

tmshutdown cannot run on a non acting-master node in an active application.

If shutting down a process would partition active processes from the DBBL, a fatal error message is displayed:

cannot shutdown, causes partitioning.

If a server has died, the following somewhat ambiguous message is produced.

CMDTUX_CAT:947 Cannot shutdown server GRPID

Examples

To shut down the entire system and remove all BEA Tuxedo IPC resources (force it if confirmation is not received in 30 seconds), run the following command:

tmshutdown -w 30

To shut down only those servers located on the machine for which the value of lmid is CS1, enter the following command:

tmshutdown -l CS1

Because the -l option restricts the action to servers listed in the SERVERS section, the BBL on CS1 is not shut down.

Notices

The tmshutdown command ignores the hangup signal (SIGHUP). If a signal is detected during shutdown, the process continues.

See Also

tmadmin(1), tmboot(1), UBBCONFIG(5)

Administering BEA Tuxedo Applications at Run Time