Module mod_ha

Module mod_ha supports directives for the IBM® HTTP Server for i Web server.

Summary

The module mod_ha contains directives that define support for the highly available HTTP Server function.

Directives

HACGI

Module: mod_ha
Syntax: HACGI on | off
Default: HACGI off
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: HACGI on

The HACGI directive specifies if CGI programs in a directory can be highly available. The CGI programs in the specified directory must use the highly available HTTP Server APIs.

Parameter: on | off
  • The on parameter value specifies CGI programs in a directory can be highly available.
  • The off parameter value specifies CGI programs in a directory are not high available.

HAModel

Module: mod_ha
Syntax: HAModel model
Default: none
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: HAModel PrimaryBackupWithIpTakeover
Example: HAModel PrimaryBackupWithDispatcher
Example: HAModel PurePeer

The HAModel directive establishes which highly available model is to be used (PrimaryBackupWithIpTakeover, PrimaryBackupWithDispatcher, or PurePeer).

Parameter: model
  • The PrimaryBackupWithIpTakeover parameter value specifies that the highly available Web server runs on the primary and all backup nodes. The backup node or nodes are in a idle state, ready to become the primary Web server should the primary Web server fail (failover), or a switchover takes place.
  • The PrimaryBackupWithDispatcher parameter value specifies that the highly available Web server runs on the primary and all backup nodes. The backup nodes are in an idle state and all client requests are served by the primary node. A network dispatcher (for example the IBM WebSphere® Edge Server) sends client requests to the Web server.
  • The PurePeer parameter value specifies that all highly available nodes are in an active state and serve client requests. A network dispatcher (for example the IBM WebSphere Edge Server) evenly distributes requests to different cluster nodes. This guarantees distribution of resources in case of heavy load. Linear scalability is not guaranteed beyond a small number of nodes. After some number of nodes are added, scalability can disappear, and the cluster performance can deteriorate.

See Highly available HTTP Server for more information regarding highly available Web server models.

Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel PrimaryBackupWithIPTakeover
LmUrlCheck http://hostname/web/docs/spec/wscheck.html 
LmIntervalTime 100
LmMaxReactivation 5
LmResponseTime 300
Note: When a server is configured as highly available (HAModel directive is specified), HotBackup behaves as if it is set to 'off' and can not be overwritten.

LmExitProgram

Module: mod_ha
Syntax: LmExitProgram libraryname programname [userprofile]
Default: none
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: LmExitProgram httptest exitpgm joeuser

The LmExitProgram directive is used to specify a user-defined program in the QSYS file system that is started by the Liveness Monitor whenever it initiates a change in the HA model of a server instance from the primary model or to the primary model. When the server instance is going to become the primary HA server instance, then this program is called with a parameter of '1'. When the current HA primary server instance is no longer going to be the primary instance, then this program is called with a parameter of '0'. For example a program can be created which will start or end a job, depending on the role of the server.

Parameter One: libraryname
  • The libraryname parameter value specifies the name of the library to be used. The parameter value can be up to 10 characters and must follow the rules for IBM i library names.
Parameter Two: programname
  • The programname parameter value specifies the name of the program to be used. The parameter value can be up to 10 characters and must follow the IBM i rules for program names in a library.
Parameter Three: userprofile
  • The userprofile parameter value is optional and specifies which user profile the named program should run under. If the userprofile parameter is not specified, user profile QTMHHTTP is used.

LmIntervalTime

Module: mod_ha
Syntax: LmIntervalTime interval
Default: LmIntervalTime 15
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: LmIntervalTime 30

The LmIntervalTime directive is used by the Liveness Monitor to specify how often (in seconds, between performing Web server Liveness checks (HEAD or GET)) a liveness check should be performed on the server. The LmResponseTime and LmIntervalTime directives are independent. One sends out checks (LmIntervalTime), while the other tests for responses (LmResponseTime). The LmResponseTime value should always be larger than the LmIntervalTime value. It is recommended that LmResponseTime be at least 3 times larger than LmIntervalTime.

Parameter: integer
  • The interval parameter value specifies how often (in seconds, between performing Web server Liveness checks (HEAD or GET)) a liveness check should be performed on the server. Valid values include integers between 0 and 4,294,967,295.
Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel PrimaryBackupWithIPTakeover
LmUrlCheck http://hostname/web/docs/spec/wscheck.html 
LmIntervalTime 100
LmMaxReactivation 5
LmResponseTime 300

LmMaxReactivation

Module: mod_ha
Syntax: LmMaxReactivation integer
Default: LmMaxReactivation 3
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: LmMaxReactivation 5

The LmMaxReactivation directive specifies how many times the Liveness Monitor should attempt to reactivate the Web server after a detected failure.

Parameter: integer
  • The integer parameter value specifies how many times the Liveness Monitor should attempt to reactivate the Web server after a detected failure. Valid values include integers between 0 and 2,147,483,647
Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel PrimaryBackupWithIPTakeover
LmUrlCheck http://hostname/web/docs/spec/wscheck.html
LmIntervalTime 100
LmMaxReactivation 5
LmResponseTime 300

LmResponseTime

Module: mod_ha
Syntax: LmResponseTime interval
Default: LmResponseTime 120
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: LmResponseTime 60

The LmResponseTime directive specifies how long the Liveness Monitor should wait for a response from the Web server before taking appropriate action (based on the other Liveness Monitor directive settings). The LmResponseTime and LmIntervalTime directives are independent. One sends out checks (LmIntervalTime), while the other tests for responses (LmResponseTime). The LmResponseTime value should always be larger than the LmIntervalTime value. It is recommended that LmResponseTime be at least 3 times larger than LmIntervalTime.

Parameter: interval
  • The interval parameter value specifies how long the Liveness Monitor should wait for a response from the Web server before taking appropriate action (based on the other Liveness Monitor directive settings).
Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel PrimaryBackupWithIPTakeover
LmUrlCheck http://hostname/web/docs/spec/wscheck.html
LmIntervalTime 100
LmMaxReactivation 5
LmResponseTime 300

LmUrlCheck

Module: mod_ha
Syntax: LmUrlCheck URL
Default: LmUrlCheck http://
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: LmUrlCheck http://194.170.2.5:8000/web/docs/spec/wscheck.html

The LmUrlCheck directive specifies a fully qualified URL that is used by the Liveness Monitor to perform liveness checks on HTTP Server. Specifying a domain name is not valid for this directive. Only one IP address can be specified in a highly available HTTP Server configuration.

Note: This is a required directive for highly available and must exist in the global server configuration context and not in a container. See HAModel and Highly available HTTP Server for additional details.
Parameter: URL
  • The URL parameter value specifies a fully qualified URL that is used by the Liveness Monitor to perform liveness checks on the server. Only one IP address can be specified in a highly available server configuration. Specifying a domain name is not valid for this parameter. The IP Address must be the same address as specified with the Listen directive. The default port number is 80
Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel PrimaryBackupWithIPTakeover
LmUrlCheck http://194.170.2.5:8000/web/docs/spec/wscheck.html 
LmIntervalTime 20
LmMaxReactivation 3
LmResponseTime 60

Specify https when the HTTP Server instance is configured to receive client requests using only secure sockets. The IP address must be the same as the IP address that was specified in the virtual host container for the SSL application. The default port number for SSL is 443.

Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel PrimaryBackupWithIPTakeover
LmUrlCheck https://194.170.2.5:8008/web/docs/spec/wscheck.html
LmIntervalTime 20
LmMaxReactivation 3
LmResponseTime 60

LmUrlCheckBackup

Module: mod_ha
Syntax: LmUrlCheckBackup URL
Default: none
Context: server config
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: LmUrlCheckBackup http://194.170.2.5:8008/web/docs/spec/wscheck.html

The LmUrlCheckBackup directive specifies a fully qualified URL that is used by the Liveness Monitor to perform liveness checks on the HA backup server instance. If this directive is not configured, then the URL passed is the URL parameter value specified on the LmUrlCheck directive.

For example, if the server is configured to run Payment Manager, only one instance of Payment Manager can be active in the cluster at any given time. If the URL on the LmUrlCheck directive specifies a URL for the Payment Manager, then this same URL will not work for the HA backup server instance, so the LmUrlCheckBackup directive needs to be configured to use a non-Payment Manager URL.

Note: This directive is ignored when HAModel PurePeer is configured.
Parameter: URL
  • The URL parameter value specifies a fully qualified URL that is used by the Liveness Monitor to perform liveness checks on the HTTP Server when the server is currently the HA backup server. The use of a domain name is not a valid parameter with this directive. Only one IP address can be specified in a High Availability server configuration (i.e. Listen 194.170.2.5:xxxxxx <virtual host 194.170.2.5:yyyyyy>). The IP Address must be the same address as specified with the Listen directive. The default port number is 80.
Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel Primary/BackupWithIPTakeover
LmUrlCheck http://194.170.2.5:8008/web/docs/spec/wscheck.html
LmUrlCheckBackup http://194.170.2.5:8008/web/docs/spec/wscheckbackup.html
LmIntervalTime 20
LmMaxReactivation 3
LmResponseTime 60

Specify https when the HTTP Server instance is configured to receive client requests using only secure sockets. The IP address must be the same as the IP address that was specified in the virtual host container for the SSL application. The default port number for SSL is 443.

Example
LoadModule ha_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
HAModel Primary/BackupWithIPTakeover
LmUrlCheck http://194.170.2.5:8008/web/docs/spec/wscheck.html
LmUrlCheckBackup https://194.170.2.5:8008/web/docs/spec/wscheckbackup.html
LmIntervalTime 20
LmMaxReactivation 3
LmResponseTime 60
Note: This directive is ignored when HAModel PurePeer is configured.