Apache Module mod_zos_cmds

Description:	Allows the server to respond to STOP and MODIFY z/OS console commands.
Status:	Extension
Module Identifier:	zos_cmds_module
Source File:	mod_zos_cmds.c

Summary

The mod_zos_cmds module is available in IBM HTTP Server 8.5.5 and later.

This module provides support for stopping and modifying the server via the z/OS operator commands STOP and MODIFY, respectively. The STOP command is an alternative to running apachectl or the IBM HTTP Server proc with ACTION=STOP.

Directives

ZosConsoleOptions

STOP Command

The STOP command will cause the IBM HTTP Server to shutdown. The default shutdown behavior is to immediately attempt to kill all child processes even if requests are being processed. The STOP command can do a graceful shutdown instead if ZosConsoleOptions UseGracefulStop is set.

MODIFY Command

mod_zos_cmds will process the inputs below when passed via the MODIFY z/OS command.

restart: The parent kills off its children, but the parent doesn't exit. It re-reads its configuration files, and re-opens any log files. Then it spawns a new set of children and continues serving hits.

Restarting after Modifying the Configuration
Making changes to server configuration file while the server is started can cause the server to not start up again during a restart issued from the MODIFY command. This can happen if the configuration changes has an error since the configuration is not revalidated before the restart. If changes are made to a configuration while the server is started, the configuration should be validated using apachectl -t before issuing a restart from the MODIFY command.
graceful: The parent will advise its children to exit after their current request (or to exit immediately if they're not serving anything). The parent re-reads its configuration files and re-opens its log files. As each child dies off, the parent replaces it with a child from the new generation of the configuration, which begins serving requests immediately.
graceful-stop: The parent will advise its children to exit after their current request (or to exit immediately if they're not serving anything).
stats: Causes information about the IBM HTTP Server processing threads are written to the error log.
restats: Causes the stat information to be reset. This has the same behavior as resetstats.
resetstats: Causes the stat information to be reset. This has the same behavior as restats.

Stats Information

The stats MODIFY command will print information about the IBM HTTP Server's processing threads.

Example Output

0090 BPXM023I (WASUSR1) 905
0090 IHS stats: hostname: 127.0.0.1 ppid: 33621090
0090 Interval: 6m Requests: 0 bytes: 0
0090 %busy: 0 (0,25,600)
0090 rdy 25 bsy 0 rd 0 wr 0 log 0 dns 0 cls 0 ka na

Description of fields

hostname: Hostname of the server
ppid: PID of the parent process
Interval: The interval since the stats have been reseted.
Requests: The number of requests since the stats have been reseted.
bytes: The number of bytes sent since the stats have been reseted.
rdy: The number of idle threads
bsy: The number of total threads in any non-idle state
rd: The number of threads reading client requests
wr: The number of threads in "write" state, which includes all Apache phases after a request has been read, including mapping to a file, access control, and the handler responsible for handling the response.
log: threads in logging state
dns: threads looking up a hostname
cls: threads in (lingering) close state
ka: connections (not threads) in keepalive state
Limitation: ka will always report as "na" (not available).

Note: Resetting the Stats Table

The stats table is reseted under these conditions: Server start, restart, restats request, or resetstats request.

ZosConsoleOptions Directive

Description:	Sets some special options for the zos_cmds module.
Syntax:	`ZosConsoleOptions Options`
Context:	server config, virtual host, directory, .htaccess
Override:	FileInfo
Status:	Extension
Module:	mod_zos_cmds

The ZosConsoleOptions directive sets some special options. The Options string can be any of the following:

DisableOldStartupMessage: This suppresses older legacy messages that the server prints out during server startup and shutdown. These legacy messages do not have a message ID.
DisableNewStartupMessage: This suppresses the newer server startup and shutdown messages. These messages contain a message ID and includes more additional information than the legacy messages.
ServerID=s: This option allows you to modify the server ID that is printed out in the new server startup and shutdown messages. The default value for the server ID is the server's hostname if a ServerID is not specified.
UseGracefulStop: Issuing a z/OS STOP command will cause the server to abruptly stop by default. This option allows the server to perform a graceful shutdown instead when a STOP command is received.