8.2.19 Logical user server definition file

Organization of this subsection

(1) Format
(2) File storage location
(3) Functionality
(4) Contents that you can define
(5) Sample definition
(6) Precautions

(1) Format

xml file format.

To Page Top

(2) File storage location

Any storage location and file name is possible.

To Page Top

(3) Functionality

You create this file when adding a logical user server by the mngsvrutil command.

To Page Top

(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. When you specify `direct`: Starts up directly. When you specify `indirect`: Starts up 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: Start: Command for starting the server Stop: Command for stopping the server ForceStop: Command for forced termination of the server GetProcessID: Command for acquiring process ID IsAlive: Command for service monitoring 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: In Windows A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed. In UNIX A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
	forceStop	Optional	The monitored process is already stopped when the forceStop type of command terminates. After issuing a forceStop type of command, the server startup commands are in an executable status.	When you do not specify a stop type of command, the following operations are performed: In Windows A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed. In UNIX A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
	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	All the monitored processes are started when the process startup command terminates normally. When the process startup command terminates normally, the process stop commands are in an executable state. The command returns the termination code as 0 in case of normal termination, and 1 in case of abnormal termination.	--
	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: In Windows A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed. In UNIX A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
	forceStop	Optional	The monitored process is already stopped when the forceStop type of command terminates. After issuing a forceStop type of command, the server startup commands are in an executable status.	When you do not specify a stop type of command, the following operations are performed: In Windows A Ctrl-C event is issued to the corresponding process. If the process does not stop, TerminateProcess () is executed. In UNIX A SIGTERM signal is sent to the corresponding process. If the process does not terminate within 1 second after that, a SIGKILL signal is sent.
	getProcessID	Required	The command outputs the process ID of the process started by the server startup command, to the standard output. When multiple processes are started, the command outputs the process IDs of all the processes. The command returns the termination code as 0 in case of normal termination, and 1 in case of abnormal termination. The output format is as follows: `9 9 9 6 \n` `1 0 0 2 3 \n` `1 0 2 5 7 \n`	--
	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`	--

To Page Top

(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>

To Page Top

(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.

To Page Top