10.21 Logical user server definition file

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

(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 nameDescriptionDefault value
user-server-definitionSpecify 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-refSpecify 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 typeCommand typeSpecification conditionRequirementsRemarks
Direct startstartRequiredServer startup commands are included in the scope of monitoring.--
stopOptionalThe 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.
forceStopOptional
  • 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.
getProcessIDCannot be specified--If specified, it results in error.
isAliveOptionalThe 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 startstartRequired
  • 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.
--
stopOptionalThe 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.
forceStopOptional
  • 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.
getProcessIDRequired
  • 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

--
isAliveOptionalThe 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 replacementCharacter string after replacementRemarks
${cosminexus.home}Cosminexus-installation-directory--
%{XXX}Environment variable XXX valueWhen the environment variable XXX does not exist, it is replaced with a blank 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