9.5 workers.properties (Worker definition file)

Organization of this section
(1) Format
(2) File storage location
(3) Functionality
(4) Specifiable keys
(5) Examples of coding
(6) Precautions

(1) Format

Specify the key as follows:

key-name=value

Specification method
  • The string up to the linefeed is a value.
  • The line beginning with a hash mark (#) is a comment.
  • If you define a line without a value, the line is ignored. The parameters not defined as valid key names are also ignored even if defined in the action definition file.
  • Up to 1023 characters are valid as key-name=value. The part exceeding this number is truncated.
  • Single-byte alphanumeric characters, underscores (_), and hyphens (-) can be used in the worker name. The operations cannot be guaranteed if you specify other characters.

(2) File storage location

(3) Functionality

The worker definition file defines the workers, sets the parameters for each worker, and defines the actions of the redirector.

(4) Specifiable keys

The keys that you can specify in the worker definition file and the parameters defined for each worker are explained below:

(a) Keys specifiable in the worker definition file

These keys define workers, and the parameters for each worker. If an invalid value is specified for this key, the operations might not execute properly.

Key nameContentsDefault value
worker.listSpecify the list of worker names. In the case of multiple names, demarcate with a comma (,). You need to specify at least one worker name.
Specify the worker name specified in mod_jk.conf (redirector action definition file for HTTP Server), or uriworkermap.properties (mapping definition file for Microsoft IIS).
None
worker.worker-name.parameterSpecify the parameters defined for each worker. Set the parameters for each worker coded in worker.list.
For details on the defined parameters, see (b) Parameters defined for each worker.
None
(b) Parameters defined for each worker
Parameters that you can defineContentsDefault value
worker.worker-name.balanced_workersSpecify the list of workers for which load balancing is to be performed. In the case of multiple names, demarcate with a comma (,).None
worker.worker-name.cachesizeSpecify an integer value from 1 to 2147483647​ for the number of connections to the workers re-used in the redirector. Note that this parameter is used in Windows.
If the number of connections to the workers is within this set value, the connections are maintained in the redirector, re-used during the communication with the applicable worker, and are not released until the J2EE server or the Web container server that is connected is shut down. If the multiplicity of requests exceeds the set value, for only those requests that exceed the set value, establish and release connections to workers for each request.
This value uses up memory as per the following formula:
(Expression)
Memory used up = (worker.worker-name.cachesize value)[Figure] 10KB
64
worker.worker-name.default_workerSpecify worker name of the default worker. If you specify a worker same as the worker specified in the POST request transfer destination worker, the requests satisfying the distribution conditions as per the POST data size and requests satisfying the conditions for the default worker are transferred to the specified worker.
Note that if you specify a worker that is not specified in the POST request transfer destination worker in this parameter, and if worker.worker-name.post_data is specified in that worker, the definition of worker.worker-name.post_data is ignored.
The null characters (space, tab, or form feed) before and after the worker name are ignored.
If you omit this parameter or specify a null string, an error is returned for the request for which a worker satisfying the transfer conditions does not exist.
None
worker.worker-name.delegate_error_codeSpecify the error status code that uses the delegation functionality of the error page. # If you want to specify multiple worker names, demarcate with a comma (,).None
worker.worker-name.hostSpecify the host name or the IP address of the worker.None
worker.worker-name.lbfactorSpecifies the load balancing value of a request. Set a value greater than 0. You can also specify a decimal value.1
worker.worker-name.portSpecify an integer value from 1 to 65535 for the worker port number.
You cannot specify a port number that is already being used or secured for another application.
None
worker.worker-name.post_dataSpecify a value adding 1 to the maximum value of the Content-Length header value for the requests to be transferred to the worker specified in worker-name as follows:
  • An integer value from 1 to 2147483648​ (unit: bytes)
  • Value adding k or K to an integer value from 1 to 2097152​ (units: kilobytes)
  • Value adding m or M to an integer value from 1 to 2048 (units: megabytes)
The requests in which the value of the Content-Length header is lesser than the specified value is transferred to a worker specified in worker-name.
If multiple workers are specified in the worker.worker-name.post_size_workers parameter, the request is transferred to a worker in which the request Content-Length header value is lesser than the specified value, and in which the value is the smallest specified value.
If you specify the value in the worker.POST-request-distribution-worker's- worker-name.post_size_workers parameter, do not specify the same value as the other workers.
The null characters (space, tab, or form feed) before and after the value are ignored.
None
worker.worker-name.post_size_workersSpecify the list of worker names of the POST request transfer destination workers. If you want to specify multiple worker names, demarcate with a comma (,). You cannot specify the same worker name.
The null characters (space, tab, or form feed) before and after the worker name are ignored.
None
worker.worker-name.receive_timeoutSpecify the communication timeout value. Specify an integer value (units: seconds) from 0 to 3600 for the time period to await the response data. If you specify 0, the system continues to wait until a response is received and a communication timeout does not occur.3600
worker.worker-name.typeSpecify the worker type from the types shown below. For details on the parameters that you can set in each type, see (c) Parameters defined for each worker.worker-name.type. You need to specify these parameters for each worker.
ajp13:
This worker transfers requests to the Web container server running by an external process.
ajp12:
This worker maintains compatibility with older versions. This worker runs assuming that ajp13 is specified.
lb:
This worker has the load balancing functionality based on the round robin process.
post_size_lb:
This is a POST request distribution worker. You can use this worker only when you use Cosminexus HTTP Server.
None
#1
The specifiable codes are mentioned in comments. Remove the comments if required.
#2
You can also specify the host name and port number of the same Web container for multiple workers.

(c) Parameters defined for each worker.worker-name.type
Parameters that you can defineWorker types
ajp13lbpost_size_lb
worker.worker-name.balanced_workersNYN
worker.worker-name.cachesize#1ONN
worker.worker-name.default_workerNNO
worker.worker-name.delegate_error_codeONN
worker.worker-name.hostYNN
worker.worker-name.lbfactorONN
worker.worker-name.portYNN
worker. worker-name.post_dataN/Y#2NN
worker. worker-name.post_size_workersNNY
worker. worker-name.receive_timeoutONN
Legend:
Y: Always specify.
O: Specification is optional.
N: Cannot be specified.
Notes
The parameters that you can specify in ajp12 are same as in ajp13.
In UNIX, if you do not specify a value for the mandatory items or if the specified value is invalid, the Cosminexus HTTP Server does not start.
#1
Valid only in Windows. In UNIX, the parameter is ignored.
#2
Mandatory for the POST request transfer destination worker.

(5) Examples of coding

worker.list=worker1
worker.worker1.port=8007
worker.worker1.host=localhost
worker.worker1.type=ajp13
#worker.worker1.cachesize=64
#worker.worker1.receive_timeout=3600
#worker.worker1.delegate_error_code=400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,422,423,424,500,501,502,503,504,505,507,510
 
#----------------------------------------------------------------
# Example setting for Loadbalancer.
#----------------------------------------------------------------
#worker.list=loadbalancer1
#
#worker.loadbalancer1.type=lb
#worker.loadbalancer1.balanced_workers=worker1,worker2
#
#worker.worker1.port=8007
#worker.worker1.host=host1
#worker.worker1.type=ajp13
#worker.worker1.cachesize=64
#worker.worker1.lbfactor=1
#worker.worker1.receive_timeout=3600
#worker.worker1.delegate_error_code=400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,422,423,424,500,501,502,503,504,505,507,510

#
#worker.worker2.port=8007
#worker.worker2.host=host2
#worker.worker2.type=ajp13
#worker.worker2.cachesize=64
#worker.worker2.lbfactor=1
#worker.worker2.receive_timeout=3600
#worker.worker2.delegate_error_code=400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,422,423,424,500,501,502,503,504,505,507,510
#----------------------------------------------------------------
# Example setting for post data size based worker.
#----------------------------------------------------------------
#worker.list=postsizelb1#worker.postsizelb1.type=post_size_lb
#worker.postsizelb1.post_size_workers=worker1,worker2
#worker.postsizelb1.default_worker=worker1
#
#worker.worker1.port=8007
#worker.worker1.host=host1
#worker.worker1.type=ajp13
#worker.worker1.post_data=100m
#worker.worker1.receive_timeout=3600
#worker.worker1.delegate_error_code=400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,422,423,424,500,501,502,503,504,505,507,510
#
#worker.worker2.port=8007
#worker.worker2.host=host2
#worker.worker2.type=ajp13
#worker.worker2.post_data=2048m
#worker.worker2.receive_timeout=3600
#worker.worker2.delegate_error_code=400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,422,423,424,500,501,502,503,504,505,507,510

(6) Precautions

If you change the user definition of the redirector by editing this file, you will need to restart the Web server. The changed definition will be applied after the Web server is restarted.