eLink Business Process Option Daemon Manager

 

The following sections describe how to use the Business Process Option Daemon Manager, its capabilities, and its parameters:

• About the Daemon Manager

• Restarting Failed Applications

• Setting Up the Daemon Manager Configuration File

• Setting Up an Application Under the Daemon Manager

About the Daemon Manager

The Daemon Manager (IcCliMgr) is an eLink Business Process Option Tuxedo server that allows you to start, stop, and restart registered daemon client applications that are running as Tuxedo Client Programs. You can use the Daemon Manager to start up and monitor vital daemons, such as the IcEvtSched, and restart them if they fail. It also provides the ability to configure and control how such applications will be restarted.

The Daemon Manager has its own configuration file, IcCliMgr.cfg, a text file that defines the applications to be supervised by the Daemon Manager and defines how the applications will behave during system runtime. IcCliMgr.cfg is located in $IC_HOME/config.

The Daemon Manager is booted when the Tuxedo domain and eLink Business Process Option are started up, and it is shut down as part of the shutdown process for the domain and eLink Business Process Option.

Restarting Failed Applications

Once the Daemon Manager is running, it monitors the daemon applications under its jurisdiction, and supervises the restarting of any applications that fail. Restart behavior is configured on a per-application basis. Each daemon application can run multiple concurrent instances (if the BOOT and NCONC parameters in the IcCliMgr.cfg file are each set to a value greater than 1).

Whenever a daemon process instance dies or whenever the domain is booted, the Daemon Manager attempts to start as many instances of the daemon application as necessary. It continues to start instances of the daemon application until either the number of active process instances matches the BOOT count, or the number of concurrent process instances equals the NCONC parameter. The number of concurrent instances of the daemon application cannot exceed the NCONC value.

Each daemon application managed by the Daemon Manager has a grace period associated with it (set by the GRACE parameter). If no value is assigned to the GRACE parameter in the IcCliMgr.cfg file, its default value is one hour (3600 seconds). When the Daemon Manager is booted for the first time, or when a process dies after a period of successful operation, the Daemon Manager begins measuring the elapsed time.

If a process instance dies before the GRACE period has elapsed, and the total number of retries is less than the RETRY parameter value, the Daemon Manager will attempt a retry. It continues to retry starting the process instance until it reaches the maximum number of retries during a GRACE period, which is set by the FLUX parameter. If the Daemon Manager cannot start the daemon application in FLUX number of attempts, it stops and waits the duration of the GRACE period before taking any further action.

When the GRACE period expires, the Daemon Manager will retry starting a process instance until the number of attempts exceeds the FLUX parameter, or the total number of retry attempts exceeds the RETRY parameter, or the daemon application is successfully started.

If a process instance dies after its GRACE period (which started when the process instance was last booted or restarted) expires, an attempt to launch a process instance is considered a restart rather than a retry. The RSTRT parameter sets the maximum number of restart attempts for the daemon application. By default, the NCONC, MAXST, RSTRT, and RETRY parameters are set to -1, which represents an unlimited value.

Setting Up the Daemon Manager Configuration File

The Daemon Manager configuration file, IcCliMgr.cfg, defines each Tuxedo daemon application to be controlled by the Daemon Manger by storing its name, current directory, the location of the daemon's executable, any arguments required by the daemon, the daemon application's environment variables, and information used to configure auto-restarting the daemon in case of failure.

The only mandatory configuration parameter assignment for a daemon application is PROGRAM. We recommend using at least the NAME and DIR parameters as well, for ease of maintenance

Note: For each daemon application in the Daemon Manager configuration file, eLink Business Process Option will assign a default value to any configuration parameter that does not have an explicit parameter assignment, except for the PROGRAM parameter.

Tuxedo Security and the Daemon Manager

The programs managed by the Daemon Manager are Tuxedo clients. By default, they perform tpinit authentication using the libiccustom shared library. Since these daemon applications are not interactive, the IC_TUXEDO_APPLICATION_PASSWORD, IC_TUXEDO_USER_NAME, and IC_TUXEDO_USER_PASSWORD environment variables must be specified either in the environment file or the environment parameters list in the IcCliMgr.cfg file.

Configuration File Syntax

For environment variables or parameter lists, you can use single quotation marks ('), double quotation marks ("), or curly braces ({}) in configuration statements. Curly braces can be nested to arbitrary levels. The pound sign (#) is the comment delimiter. White space is ignored.

Each daemon application section in the configuration file is separated from the other sections by a line that contains only dash characters, and which must contain at least two dashes (--).

Configuration File Syntax for Parameters

Use the following syntax to assign values to parameters:

PARAMETER=value

PARAMETERLIST: value1  value2  
		value3
					value4
					value5

Use either a single space or a newline followed by an indent on the next line as the delimiter between values in a parameter list.

Configuration File Syntax for Environment Variables

Use the following syntax for environment variable assignments, which include the ENVS entry in IcCliMgr.cfg, and the contents of the environment variables file pointed to by the ENVFILE parameter. Note that the Daemon Manager configuration file syntax is similar, but not identical, to the Tuxedo environment file syntax.

VAR=value	Assigns the given value to the named variable.
VAR:=value	Prepends the given value to any existing value for the named variable. The new value will be listed before any previously defined value. If necessary, separate this new value from the existing one by a colon.
VAR=:value	Appends the given value to any existing value for the named variable. The new value will be listed after any previously defined value. If necessary, separate this new value from the existing one by a colon.
VAR=-value	Assign the given value to the named variable only if the variable is not currently defined (does nothave a value assigned). If the named variable has already been defined, use the current value.
VAR@	Remove any current definitions (values) for the named variable.

Mandatory Client Application Entries

You must include an entry for the IcEvtSched daemon in the Daemon Manager configuration file. You must include an entry for the IcRepDaemon in the Daemon Manager configuration file.

Note: Make sure the owner of the IcRepDaemon process and the repository directory is icadmin.

Daemon Manager Configuration Parameters

The following sections list all possible configuration parameters for a daemon application running under the Daemon Manager. They are grouped by the functionality affected by the parameter.

Basic Parameters

The basic parameters for any client application to be managed by the Daemon Manager are listed in Table 2-1.

Table 2-1 Basic IcCliMgr.cfg Parameters

Parameter	Default Value	Description
ARGS:	None.	Lists any input arguments used by the client application. Note that the list is preceded by a colon and that the list may be continued on subsequent lines, providing those lines are indented.
DIR	$IC_HOME/tuxapp	Specifies the daemon application's current working directory, as well as the path used for other parameters with relative path name values. This parameter can be used with the PROGRAM parameter to provide the complete path name to the executable and to provide the ENVFILE, INPUT, OUTPUT, and ERROR parameters.
ENVFILE	None.	Specifies the path name of the environment file used by this client application. You can specify the full path or you can specify it relative to the path from DIR.
NAME	Final value in the PROGRAM path	Specifies a logical name for the daemon application. This value must be unique.
PROGRAM	None.	Specifies the name of the daemon application's executable. This value must be unique. Mandatory line for each client application.

You can use the parameters listed in Table 2-2 to control additional aspects of a daemon application:

Table 2-2 Additional IcCliMgrParameters

Parameter	Default	Description
ENVS:	None.	Defines and sets environment variables for the specified daemon application. This can be used when only one or two values are needed or when an ENVFILE is not desired. Note that the list is preceded by a colon and that the list may be continued on subsequent lines, providing those lines are indented. Environment variables assigned by the ENVS entry override any values set in the ENVFILE.
ERROR	Same as OUTPUT.	Specifies the full path name of an error file used by the specified daemon application.
GROUP	Value of NAME.	Groups related daemon applications. This allows you to start and stop multiple daemon with a single shutdown command. For example, you could create a group of polling agents.
ID	Next available number in sequence, starting with first ID value given in this file.	Assigns a unique ID number to a daemon application, which can be used to control the daemon's startup and shutdown.
INPUT	/dev/null	Specifies the full path name of an input file used by the specified daemon application.
OUTPUT	/dev/null	Specifies the full path name of an output file used by the specified daemon application.

Restart Parameters

Use the parameters listed in Table 2-3 to specify how and when the client application will be restarted, and when additional instances of the client application are spawned:

Table 2-3 Client Application Restart Parameters

Parameter	Default	Description
BOOT	1	Specifies the number of instances of the daemon application to keep active. This is the number of application instances booted when the Daemon Manager is first started, and the number of active application instances that the Daemon Manager will maintain by starting new instances if any instances die.
FLUX	3	The number of retries permitted within a single GRACE period. If the Daemon Manager cannot start the daemon application in FLUX number of attempts, it stops and waits the duration of the GRACE period. After the GRACE period expires, the Daemon Manager will retry starting the daemon application again, providing that the RETRY value has not been exceeded.
GRACE	3600 seconds (1 hour)	Specifies the time period (in seconds) during which the death of a daemon application instance will trigger a retry attempt rather than a restart.
HIST	20	Specifies the number of process history entries for the daemon application that the Daemon Manager should maintain. Note that the process history is stored in dynamic memory, and therefore it is purged whenever the Daemon Manager is terminated.
MAXST	Unlimited.	Specifies the maximum number of times the daemon application can be started for any reason, including system boot, restarting, retrying, and manual control from the system command-line. This prevents the Daemon Manager from endlessly restarting a daemon application which continuously fails after restarting due to some larger problem.
NCONC	Unlimited.	Specifies the maximum number of active instances of the specified daemon application that can exist at any given time.
RETRY	Unlimited.	Specifies the maximum number of times the Daemon Manager tries to immediately start a failing daemon application, including retries after the GRACE period expires.
RSTRT	Unlimited.	Specifies the maximum number of times the daemon application can be restarted. This prevents situations where the daemon application has a problem that makes it fail after restarting, and yet the Daemon Manager continues to restart it.

Setting Up an Application Under the Daemon Manager

The Daemon Manager can only control daemon applications that act as Tuxedo clients.

Note: Before editing the Daemon Manager configuration file, shut down the Daemon Manager by entering:

tmshutdown -g SVRGRP -i SRVID

where SVRGRP and SRVID are the group name and server ID assigned to the Daemon Manager in the UBBCONFIG file.

To add a client application:

1. Edit the IcCliMgr.cfg file and add the following statements:

   NAME=appname

   DIR=path_of_executable

   PROGRAM=name_of_executable

Only the PROGRAM statement is mandatory, but we recommend using either comments or the NAME and DIR statements for ease of maintenance.

1. Add any of the following statements, as appropriate for your daemon application:

   GROUP=groupname

   ENVFILE=envfile

   ARGS: arg1 arg2 arg3

   INPUT=input

   OUTPUT=output

   ERROR=error

   ENVS: envar1=value envar2=value envar3=value

2. Add any of the following restart configuration parameters, as appropriate for your daemon application:

   BOOT

   FLUX

   GRACE

   HIST

   MAXST

   NCONC

   RETRY

   RSTRT

3. Make sure that each region of configuration statements pertaining to a specific daemon application is separated from the adjacent regions by a line solely consisting of at least two dashes (--). Make sure that no characters other than dashes are used on this line.

4. Save your changes. When you reboot the domain, the Daemon Manager will run the specified daemon application.

5. Alternatively, if you had shut down only the Daemon Manager and not the entire domain, you can enter the following to reboot the Daemon Manager:

   tmboot -g SVRGRP -i SRVID 

   where SVRGRP and SRVID are the group name and server ID assigned to the Daemon Manager in the UBBCONFIG file.

   Use the tmadmin utility to verify the number of active process instances.