Appendix D. Workers.properties file for mod_jk
If you want to use the mod_jk
connector, you must create a JBCS_HOME/httpd/conf/workers.properties
file on the Apache HTTP Server host to define the back-end worker nodes. The worker nodes are servlet containers that you can map to the mod_jk
load balancer. The workers.properties
file specifies the location of the servlet containers and how to load-balance calls across these servlet containers.
This appendix describes the layout and content of the workers.properties
file.
Depending on the Apache HTTP Server distribution that you are using, the location of the workers.properties
file varies:
-
If you are using the JBCS Apache HTTP Server, the
workers.properties
file is in theJBCS_HOME/httpd/conf.d
directory. If you are using the RHEL Apache HTTP Server, the
workers.properties
file is in the/etc/httpd/conf.d
directory.NoteThe RHEL Apache HTTP Server supports the use of
mod_jk
on RHEL 9 only.
D.1. Workers.properties
overview
The workers.properties
file contains a global properties section and a worker properties section.
- Global Properties
- This section contains directives that apply to all workers.
- Worker Properties
- This section contains directives that apply to each individual worker.
Each node is defined using the worker properties naming convention. The worker name can only contain lowercase letters, uppercase letters, numbers, and specific special characters (_
, /
).
The structure of a worker property is worker.WORKER_NAME.DIRECTIVE
.
worker
- The constant prefix for all worker properties.
WORKER_NAME
-
The arbitrary name given to the worker. For example:
node1
,node_01
,Node_1
. DIRECTIVE
- The specific directive required.
D.2. Workers.properties
directives
The workers.properties
file directives are divided into global, mandatory, connection, and load-balancing classifications.
Global directives for workers.properties
- worker.list
Specifies the list of worker names that
mod_jk
uses. The workers in this list are available to map requests to.NoteA single node configuration which is not managed by a load balancer must be set to
worker.list=WORKER_NAME
.
Mandatory directives for workers.properties
- type
Specifies the type of worker, which determines the directives applicable to the worker. The default value is
ajp13
, which is the preferred worker type to select for communication between the web server and Apache HTTP Server.Other values include
lb
andstatus
.For detailed information about AJPv13, see the Apache Tomcat Connector - AJP Protocol Reference.
Connection directives for workers.properties
- host
The hostname or IP address of the worker. The worker node must support the ajp13 protocol stack. The default value is
localhost
.You can specify the
port
directive as part of the host directive by appending the port number after the host name or IP address. For example:worker.node1.host=192.168.2.1:8009
orworker.node1.host=node1.example.com:8009
.- port
-
The port number of the remote server instance listening for the defined protocol requests. The default value is
8009
, which is the default listen port for AJPv13 workers. - ping_mode
Specifies the conditions under which connections are probed for their current network health.
The probe uses an empty AJPv13 packet for the
CPing
, and expects aCPong
in return, within a specified timeout.You specify the conditions by using a combination of the directive flags. The flags are not comma-separated. For example, a correct directive flag set is
worker.node1.ping_mode=CI
.- C (connect)
-
Specifies the connection is probed once after connecting to the server. You specify the timeout using the
connect_timeout
directive, otherwise the value forping_timeout
is used. - P (prepost)
-
Specifies that the connection is probed before sending each request to the server. You specify the timeout using the
prepost_timeout
directive, otherwise the value forping_timeout
is used. - I (interval)
-
Specifies that the connection is probed during regular internal maintenance cycles. You specify the idle time between each interval using the
connection_ping_interval
directive, otherwise the value forping_timeout
is used. - A (all)
-
The most common setting, which specifies that all directive flags are applied. For information about the
\*_timeout
advanced directives, see the Apache Tomcat Connector - Reference Guide.
- ping_timeout
-
Specifies the time to wait for
CPong
answers to aCPing
connection probe (seeping_mode
). The default value is10000
(milliseconds).
Load balancing directives for workers.properties
- lbfactor
Specifies the load-balancing factor for an individual worker, and is only specified for a member worker of a load balancer.
This directive defines the relative amount of HTTP request load distributed to the worker compared to other workers in the cluster.
A common example where this directive applies is where you want to differentiate servers with greater processing power than others in the cluster. For example, if you require a worker to take three times the load than other workers, specify
worker.WORKER_NAME.lbfactor=3
.- balance_workers
-
Specifies the worker nodes that the load balancer must manage. The directive can be used multiple times for the same load balancer, and consists of a comma-separated list of worker names as specified in the
workers.properties
file. - sticky_session
Specifies whether requests for workers with SESSION IDs are routed back to the same worker. The default is
0
(false). When set to1
(true), load balancer persistence is enabled.For example, if you specify
worker.loadbalancer.sticky_session=0
, each request is load balanced between each node in the cluster. In other words, different requests for the same session can go to different servers based on server load.If you specify
worker.loadbalancer.sticky_session=1
, each session is persisted (locked) to one server until the session is terminated, providing that server is available.
Additional resources