8.2.19 Logical user server definition file
- Organization of this subsection
(1) Format
xml file format.
(2) File storage location
Any storage location and file name is possible.
(3) Functionality
You create this file when adding a logical user server by the mngsvrutil command.
(4) Contents that you can define
The following table describes the contents that you can code in the logical user server definition file:
Element name |
Description |
Default value |
|||
---|---|---|---|---|---|
user-server-definition |
Specify the following path as namespace: http://www.cosminexus.com/mngsvr/schema/UserServerDefinition-1.1 |
-- |
|||
Service |
-- |
-- |
|||
Type |
Specify whether to start directly or indirectly.
|
direct |
|||
startup-order |
Specify an integer from -1 to 999 for the startup order. When -1 is specified, the element is ignored. |
900 |
|||
start-watch-time |
Choose a start watch time from the following numeric values (units: seconds). When 0 is specified, monitoring is not performed. 0, 60, 300, 600, 3600 |
60 |
|||
stop-watch-time |
Choose a stop watch time from the following numeric values (units: seconds). When 0 is specified, monitoring is not performed. 0, 60, 300, 600, 3600, 1800 |
60 |
|||
force-watch-time |
Choose a force stop watch time in the following numeric value (unit: seconds). When 0 is specified, monitoring is not performed. 0, 60, 300, 600, 1800 |
60 |
|||
retry-count |
Specify the auto restart frequency, choose one from the following numeric values: 0, 1, 5, 10, 1000 |
1 |
|||
retry-interval |
Specify the auto restart retry interval, choose one from the following numeric values (units: seconds). When 0 is specified, performs immediate retry. 0, 60, 300, 600, 3600,1800 |
60 |
|||
watch-interval |
Specify an integer from 1 to 86400 (units: seconds) for the monitoring interval. Note that if you specify the monitoring interval along with the adminagent.userserver.watch.interval key of the Administration Agent property file, the value specified in this tag is valid. |
1 |
|||
start-time-watch-interval |
Specify the start time monitoring interval, as an integer between 1 and 86400 (units: seconds). |
1 |
|||
env |
Define the environment variable. You can specify multiple name-value pairs. |
-- |
|||
name |
Specify an environment variable name. Specify this value without fail. |
-- |
|||
value |
Specify an environment variable name. Specify this value without fail. If the string ${cosminexus.home} exists in the value specified for environment variables, that value is replaced with Cosminexus-installation-directory. |
-- |
|||
working-dir |
Specify the working directory, as an absolute path. |
Cosminexus-installation-directory/manager/bin |
|||
user-id |
Specify the user ID at command runtime. This element is used for UNIX. |
-- |
|||
group-id |
Specify the group ID at command runtime. This element is used for UNIX. |
-- |
|||
command |
Define the command. Specification is mandatory. You can specify multiple commands. |
-- |
|||
type |
Specify the command type#1. You can specify the following values:
Specification is mandatory. |
-- |
|||
timeout |
Specify an integer (units: bytes) from 1 to 86400 for the timeout time. It is valid only when the command type is getProcessID or isAlive. |
180 |
|||
arg |
Specify the command arguments.#2 Specification is mandatory. To add arguments and argument values for a command, specify multiple <arg> tags. An example of specifying the <arg> tag is as follows: <arg>Command</arg> <arg>Argument-1</arg> <arg>Value-specified-in-Argument-1</arg> <arg>Argument-2-(No-value-is-specified)</arg> <arg>Argument-3</arg> <arg>Value-specified-in-Argument-3</arg> |
-- |
|||
server |
Define the logical user server. Specification is mandatory. You can specify multiple servers. |
-- |
|||
logical-server-name |
Specify logical server name in less than 128 characters. You can use single byte alphanumeric characters (A to Z, a to z, 0 to 9), under scores (_), and hyphens (-). Specification is mandatory. |
-- |
|||
display-name |
Specifies the display name of the logical server within 128 characters. |
-- |
|||
description |
Specify the explanation about the logical server in less than 1024 characters. |
-- |
|||
host-ref |
Specify the host name defined beforehand in less than 255 characters. You can use single byte alphanumeric characters (A to Z, a to z, 0 to 9), under scores (_), hyphens (-), and periods(.). Specification is mandatory. |
-- |
- #1
-
Depending on the type of startup, the various command types have different conditions of specification. The following table describes the specification conditions and command type requirements based on the type of startup:
Startup type |
Command type |
Specification condition |
Requirements |
Remarks |
---|---|---|---|---|
Direct start |
start |
Required |
Server startup commands are included in the scope of monitoring. |
-- |
stop |
Optional |
The monitored process is already stopped when the server stop command terminates normally. |
When you do not specify a stop type of command, the following operations are performed:
|
|
forceStop |
Optional |
|
When you do not specify a stop type of command, the following operations are performed:
|
|
getProcessID |
Cannot be specified |
-- |
If specified, it results in error. |
|
isAlive |
Optional |
The command should return a termination code of 0 if the service is running and a termination code other than 0, if the service is not running. |
When specified, the service is monitored. |
|
Indirect start |
start |
Required |
|
-- |
stop |
Optional |
The monitored process is already stopped when the server stop command terminates normally. |
When you do not specify a stop type of command, the following operations are performed:
|
|
forceStop |
Optional |
|
When you do not specify a stop type of command, the following operations are performed:
|
|
getProcessID |
Required |
|
-- |
|
isAlive |
Optional |
The command should return a termination code of 0 if the service is running and a termination code other than 0, if the service is not running. |
When specified, the service is monitored. |
- #2
-
If you use any of the following character strings when specifying the value of a command argument, it is replaced with the corresponding value of that string:
Character string before replacement |
Character string after replacement |
Remarks |
---|---|---|
${cosminexus.home} |
Cosminexus-installation-directory |
-- |
%{XXX} |
Environment variable XXX value |
When the environment variable XXX does not exist, it is replaced with a null character string. |
${server.name} |
logical-server-name |
-- |
(5) Sample definition
<?xml version="1.0" encoding="UTF-8" ?> <user-server-definition xmlns="http://www.cosminexus.com/mngsvr/schema/UserServerDefinition-1.1"> <!--Service definition --> <service> <!--Start type --> <type>direct</type> <!--Startup order --> <startup-order>900</startup-order> <!--Start monitoring time --> <start-watch-time>60</start-watch-time> <!--Stop monitoring time --> <stop-watch-time>60</stop-watch-time> <!--Forced stop monitoring time --> <force-watch-time>60</force-watch-time> <!--Retry count --> <retry-count>1</retry-count> <!--Retry interval --> <retry-interval>60</retry-interval> <!--Monitoring interval --> <watch-interval>1</watch-interval> <!--Start time monitoring interval --> <start-time-watch-interval>1</start-time-watch-interval> <!--Environment variable --> <env name="USERSERVER_HOME" value="C:\UserServer"/> <!--Working directory --> <working-dir>C:\UserServer</working-dir> <!--User ID --> <!-- <user-id>userserver</user-id> --> <!--Group ID --> <!-- <group-id>userserver</group-id> --> <!--Server startup command --> <command type="start"> <arg>C:\UserServer\start.exe</arg> </command> <!--Server stop command --> <command type="stop"> <arg>C:\UserServer\stop.exe</arg> </command> <!--Command for forced termination of server --> <command type="forceStop"> <arg>C:\UserServer\forceStop.exe</arg> </command> <!--Command to get process ID --> <!-- <command type="getProcessID" timeout="180"> <arg>C:\UserServer\getProcessID.exe</arg> </command> --> <!--Command for service monitoring --> <command type="isAlive" timeout="180"> <arg>C:\UserServer\isAlive.exe</arg> </command> </service> <!--Logical user server definition --> <server> <logical-server-name>UserServer01</logical-server-name> <display-name>Logical user server</display-name> <description>This is a logical user server</description> <host-ref>192.168.1.1</host-ref> </server> </user-server-definition>
(6) Precautions
-
When the stop and forceStop commands are not specified, do not specify batch files or the shell scripts that invoke other processes in the start command. If you specify the batch files or shell scripts, after restarting the Administration Agent, you cannot stop the processes invoked by the batch files or shell scripts by extending the stop operation or forced stop operation.
-
When you specify batch files or shell scripts that invoke other processes, in the start command during direct start, specify the stop command and the forceStop command also.
-
When you specify batch files or shell scripts that invoke other processes, in the start command during indirect start, follow the below steps:
-
Specify the stop command and the forceStop command.
-
Specify the getProcessID command to fetch the process ID of all the processes invoked by the batch files or shell scripts.
-
-
Specify settings for the isAlive command used with the start processing of the logical user server such that instead of waiting until the starting of the logical user server can be confirmed, the command must terminate with a non-zero exit code as soon as the confirmation fails.
If the isAlive command does not terminate immediately and if the logical user server hangs up during the start processing, the auto-stop processing of the logical user server might not be executed when the exceeding of the start monitoring time of the logical user server is detected.
Also, implement the isAlive and getProcessID commands with confirmation methods that are as simple as possible, so that a response is returned immediately even if the machine load is high.