Support

Table Of Contents

Process Control

Introduction

Process Agents

Processes

Services

Process Control System Configuration

Co-existence with Previous Versions of Process Control

For the Complete Configuration

Creating User Groups

For Each Process Control Host

Assign a Name

Add Host Names to the Interfaces File

Start the Process Control Agent

Permanent Installations

Solaris 2.x

Process Control Service and Process Configuration

Defining Processes

Defining Services

Specifying Process Dependencies

Defining Agent Hosts

An Example Configuration File

Expansion Keywords

Alert/Restart Syslog Messages

Converting a Process Control Configuration

Process Control Management

Service Status

Syntax

Command Line Parameters

Starting a Service or Process

Syntax

Command Line Parameters

Stopping a Service or Process

Syntax

Command Line Parameters

Shutting Down a Process Control Agent

Syntax

Command Line Parameters

Process Control Agent Daemon Command Line Options

Syntax

Command Line Parameters

Process Control

---

This chapter provides details on the concepts and tools associated with the Cisco Info Center Process Control system. It includes the following sections:

•"Introduction"

•"Process Control System Configuration"

•"Process Control Service and Process Configuration"

•"Process Control Management"

•"Process Control Agent Daemon Command Line Options"

Introduction

The Cisco Info Center Process Control system allows you to configure remote UNIX processes. The process control system is designed to simplify the configuration and management of Cisco Info Center components such as Cisco Info Servers, Cisco Info Mediators, and Cisco Info Gateways. The Process Control system contains the following elements:

•Process Control Agents, which are programs installed on each host with the responsibility of managing processes.

•A set of command line utilities to provide an interface to process management.

The Process Control agents cooperate automatically and have memory for their configuration. Process Control agents start remote processes and are capable of keeping those processes running. Processes can be defined to be dependent on the starting of a previous process or have timed threshold dependencies. When a managed host is restarted, the Process Control agent restarts local components automatically.

The command line utilities are provided to:

•retrieve and display the status of any service in the configuration

•start a service or process located anywhere within the configuration

•stop a service or process located anywhere within the configuration

•shutdown a Process Control agent

•convert a previous version of a Process Control configuration

Process Control is also responsible for the execution of Cisco Info Center Automation system external effects. Automation does not execute programs; however, it sends a request to a Process Control agent which forwards the request to the Process Control agent running on the specified host. That Process Control agent then executes the requested program.

Process Agents

Any Cisco Info Center participating host must be configured with the Process Control agent daemon. Once this is in place, you can connect the host into the Process Control system. Figure 2-1 shows a basic Cisco Info Center configuration comprising three hosts running Process Control agents.

Figure 2-1 Basic Cisco Info Center Configuration

Processes

Processes are programs that are executed by a Process Control agent. Processes can also be configured to be dependent upon one another.

Two types of manageable processes exist, as shown in Table 2-1.

Table 2-1 Types of Processes

Process Type	Description
pa aware process	A process that uses the Process Control API and is part of the configuration and managed by Process Control. This type of process allows the full functionality of the Process Control system to be utilized, such as process dependencies.
not pa aware process	A process that does not use the Process Control API and is not aware of the Process Control system.

Services

The main functions of the Process Control system are to configure and manage local and remote processes and to provide a level of automatic management of those processes. To make the management of groups of processes easier, the concept of a service is used. Once a service is correctly configured, it is managed by Process Control.

A service is made up of several processes, which are executed by Process Control agents. A service may be configured to start up automatically when the Process Control agent starts or to wait until the service is started manually. Two grades of service exist: master and non-master. These grades are used when services are automatically started. A master service has its processes started before a non-master service.

Any number of Process Control agents can exist. Agents can manage any number of Cisco Info Center processes.

Process Control System Configuration

You must consider a number of issues before the implementation of Process Control. The steps you take also vary when you are already using a previous version of Cisco Info Center Process Control. The factors described here assume you are performing a new Process Control configuration. Before you begin, you should consider the following:

•Determine which Cisco Info Center components are installed and where they are located. Ensure you have taken into account all components and any fail over or backup systems. The Cisco Info Center desktops are not classed as a service, and therefore, can not be managed by Process Control.

•When you are upgrading to the new version of Process Control, see the "Co-existence with Previous Versions of Process Control" section.

Once you determine the complete Cisco Info Center configuration requirements, continue to follow the information described in this section.

Co-existence with Previous Versions of Process Control

This version of Process Control can co-exist with previous versions of Process Control. No known technical issues exist indicating the systems will conflict, however, there is no integration provided between different versions.

For the Complete Configuration

Creating User Groups

The Process Control system uses UNIX user names and passwords to grant access to the Process Control system. To control who can log in, any user that needs access to the Process Control system should be made a member of a group called ncoadmin. If this group does not exist, create it, and add Process Control users to this group. If you run NIS, NIS+, or some other global information service, this process must be performed by the administrator of that service.

For Each Process Control Host

For each process control host, you must:

•assign a unique server name

•add the host name to the interfaces file

•start the process control agent

Assign a Name

Assign a unique server name to the Process Control agent for each host. The name must end with "_PA" to identify the server as a Process Control server. For example, when you install the Process Control agent on a host named jfksys1, the Process Control agent is named JFKSYS1_PA. By default, the first Process Control agent installed in a configuration is named NCO_PA.

Add Host Names to the Interfaces File

For each host, add an entry to the Cisco Info Center interfaces file using the Server Editor window. See the Cisco Info Center Installation and Configuration guide for information on how to add the entry.

Next, distribute the updated interfaces file to all hosts in the configuration. See the Cisco Info Center Installation and Configuration guide for information on how to generate interfaces files for Solaris2 platforms.

Once the interfaces information is in place, all Process Control agents can connect and operate as expected.

Start the Process Control Agent

You manually start the Process Control agent from the command line as follows:

host% $OMNIHOME/bin/nco_pad -name <name_of_pa>

Where <name_of_pa> is the name of the Process Control agent.

Permanent Installations

The nco_pad command can be installed in the system start-up scripts allowing the Process Control agent to start whenever the host machine boots up.

Solaris 2.x

If you respond "yes" when the Cisco Info Center installation script issues the prompt "Do you wish to configure automatic startup upon system boot," a start-up script called nco is installed in the /etc/init.d directory.

Process Control Service and Process Configuration

Process Control stores system configuration information in the $OMNIHOME/etc/nco_pa.conf file.

This file is referenced at start-up time to establish the configuration information. It contains a number of records, each of which contain various attributes and associated values.

You must edit this file to add any new processes or to modify configuration information. You must maintain Process Control configuration information to ensure host configuration information stays synchronized amongst all of the agents in the configuration.

Defining Processes

You must define the list of processes in the configuration file. Process definitions have the following format:

nco_process `Cisco Info Server'

{

   Command `$OMNIHOME/bin/nco_objserv -name INFOSERVER -pa DARKSTAR_PA' run    as 0

   Host=darkstar'

   Managed=True

   RestartMsg=`The Cisco Info Server has been restarted'

   AlertMsg=`The Cisco Info Server has gone down'

   RetryCount=0

   ProcessType=PaPA_AWARE

}

nco_process `Cisco Info Server' defines the name of the process. The above example is for the Cisco Info Server. Note, the names for the processes must be unique within the complete Process Control network.

Command is the command string that starts the process as it would be entered on the command line. Note, you must use the full path for the command. For example, to configure an Cisco Info Server named INFOSERVER, specify:

host% `$OMNIHOME/bin/nco_objserv -name INFOSERVER -pa DARKSTAR' run as 0

The run as option allows the definition of which user to run the process under. Typically this is set to root (UID 0). Note, information about the command line options for the Cisco Info Server is available in Chapter 1, "Cisco Info Server".

Host is the name of the host on which the process should be executed. Process Control automatically resolves the name of the Process Control agent when required.

Managed allows the selection between Yes (process is automatically restarted when it exits) and No (process is not automatically restarted when it exits).

RestartMsg contains the message to be sent to syslog when the process is restarted. For example:

The Cisco Info Server has been restarted.

AlertMsg contains the message to be sent to syslog when the process exits. For example:

The Cisco Info Server has gone down.

RetryCount specifies the number of restart attempts to be made when the process exits. When this is set to 0, the process attempts to start indefinitely. Do not modify this parameter.

---

Note Do not modify the default value for the RetryCount parameter (RetryCount=0). Changing this parameter will result in unpredictable consequences.

---

ProcessType allows the selection between PaPA_AWARE, for PA aware processes, and PaNOT_PA_AWARE, for processes that are not PA aware.

Defining Services

To group together the functional elements of the system, you must define the services. A service lists a group of processes that must be running together to provide that service. The processes must have already been defined in the list of processes. Service definitions have the following format:

nco_service `Omnibus'

{

   ServiceType=Master

   ServiceStart=Non-Auto

   process `Cisco Info Server' NONE

   process `Proxy' `Cisco Info Server'

   process `Mediator' `Proxy'

   process `Mediator-1' `Cisco Info Server'

   process `Sleep' 5

}

nco_service `Omnibus' defines the name of the service, for example, Omnibus. Note, the names for the services must be unique within the complete Process Control network.

ServiceType defines whether this service should be started before all other services and handled as the master service, upon which other services depend. This can be set as either Master or Non-Master.

ServiceStart allows the selection between Auto, to start the service as soon as nco_pa has started, and Non-Auto, where the service must be started manually with the nco_start command.

process defines a PA aware process that must be run as part of the service.

Specifying Process Dependencies

The process attribute allows you to define the process that should be run as part of the service. You can, however, add dependencies on each of the processes within the service. The format of the process attribute is as follows:

process <processname> <dependency>

Where <processname> is the name of the process defined in the list of processes and <dependency> can be either:

•numeric—allows you to specify a time dependency, in seconds, for starting the dependent process. For example, when you specify 5, the process starts five seconds after the service has started.

•string—allows you to specify another process within the same service.

•NONE—specifies no dependency.

In the above example, Omnibus is the first process the Cisco Info Server starts, as it has no dependencies. Five seconds after the Cisco Info Server is running, the process Sleep starts. Once the Cisco Info Server is running successfully, Proxy and Mediator-1 start. When the Proxy Cisco Info Server is running, the process Mediator starts.

Defining Agent Hosts

To specify the available hosts to contact, you must define the agent host names. Host definitions have the following format:

nco_routing

{

   host `darkstar' `DARKSTAR_PA'

   host `penelope' `PENELOPE_PA'

   host `moose' `MOOSE_PA'

   host `ferrari' `FERRARI_PA'

}

host defines the name of the host, for example, darkstar, and the name of the process agent to be used in the Process Control system, for example, DARKSTAR_PA.

An Example Configuration File

The following example shows the settings for a simple configuration file.

#NCO_PA3

#

# Process Agent Daemon Configuration File 1.1

#

#

# List of processes

#

nco_process `Cisco Info Server'

{

Command `$OMNIHOME/bin/nco_objserv -name INFOSERVER -pa DARKSTAR_PA' run as 0

Host=`darkstar'

Managed=True

RestartMsg=`The Cisco Info Server has been restarted'

AlertMsg=`The Cisco Info Server has gone down'

RetryCount=0

ProcessType=PaPA_AWARE

}

nco_process `Proxy'

{

Command `$OMNIHOME/bin/nco_proxyserv -name SCNCOMS -server INFOSERVER -debug' run as 0

Host=`darkstar'

Managed=True

RestartMsg=` '

AlertMsg=` '

RetryCount=0

ProcessType=PaPA_AWARE

}

nco_process `Mediator'

{

Command `$OMNIHOME/probes/solaris2/nco_p_simnet -server INFOSERVER' run as 0

Host=`darkstar'

Managed=True

RestartMsg=` `

AlertMsg=` `

RetryCount=0

ProcessType=PaNOT_PA_AWARE

}

nco_process `Mediator-1'

{

Command `$OMNIHOME/probes/solaris2/nco_p_simnet -server INFOSERVER' run as 0

Host=`darkstar'

Managed=True

RestartMsg=` `

AlertMsg=` `

RetryCount=0

ProcessType=PaNOT_PA_AWARE

}

nco_process `Sleep'

{

Command `/usr/bin/sleep 500' run as 60003

Host=`darkstar'

Managed=True

RestartMsg=`STARTED'

AlertMsg=`STOPPED'

RetryCount=0

ProcessType=PaNOT_PA_AWARE

}

nco_process `Sleep-1'

{

Command `/usr/bin/sleep 500' run as 305

Host=`penelope'

Managed=True

RestartMsg=` `

AlertMsg=` `

RetryCount=0

ProcessType=PaNOT_PA_AWARE

}

nco_process `Sleep-2'

{

Command `/usr/bin/sleep 500' run as 305

Host=`penelope'

Managed=True

RestartMsg=` `

AlertMsg=` `

RetryCount=0

ProcessType=PaNOT_PA_AWARE

}

nco_process `Sleep-3'

{

Command `/usr/bin/sleep 500' run as 305

Host=`ferrari'

Managed=True

RestartMsg=` `

AlertMsg=` `

RetryCount=0

ProcessType=PaNOT_PA_AWARE

}

nco_process `Master Object Server'

{

Command `$OMNIHOME/bin/nco_objserv' run as 0

Host=`darkstar'

Managed=True

RestartMsg=`Master Object Server running as ${EUID} has been restored on ${HOST}.'

AlertMsg=`Master Object Server running as ${EUID} has died on ${HOST}.'

RetryCount=0

ProcessType=PaPA_AWARE

}

#

# List of Services

#

nco_service `Omnibus'

{

ServiceType=Master

ServiceStart=Non-Auto

process `Cisco Info Server' NONE

process `Proxy' `Cisco Info Server'

process `Mediator' `Proxy'

process `Mediator-1' `Cisco Info Server'

process `Sleep' 5

}

nco_service `Penelope Service'

{

ServiceType=Non-Master

ServiceStart=Non-Auto

process `Sleep-1' 5

process `Sleep-2' 10

process `Sleep-3' 15

}

nco_service `Core'

{

ServiceType=Master

ServiceStart=Auto

process `Master Object Server' NONE

}

# ROUTING TABLE

#

nco_routing

{

host `darkstar' `DARKSTAR_PA'

host `penelope' `PENELOPE_PA'

host `moose' `MOOSE_PA'

host `ferrari' `FERRARI_PA'

}

Expansion Keywords

You can include expansion keywords in the Restartmsg entry in the configuration file. These act as variables and ensure that the restart message contains the correct information about the process that has restarted.

Table 2-2 lists the expansion keywords.

Table 2-2 Expansion Keywords

Expansion Keyword	Description
${NAME}	The name of the process.
${HOST}	The name of the host running the process.
${EUID}	The Effective User ID that the process is running under.
${COMMAND}	The command that defines the process.

Displaying the Service Status

To display the status of each process control service enter the following command:

$OMNIHOME/bin/nco_pa_status -name string

where string is the process agent name. For more information on the command line option syntax and parameters see the"Service Status" section.

An example status output is shown below:

--------------------------------------------------------------------------

Service Name       Process Name         Hostname  User     Status    PID

--------------------------------------------------------------------------

Master Service     ObjectServer         SFOSYS1   root     RUNNING   16751

                   Proxy                SFOSYS1   root     RUNNING   16752

                   Sleep                SFOSYS1   root     RUNNING   16753

                   Probe                SFOSYS1   root     RUNNING   16754

--------------------------------------------------------------------------

Table 2-3 describes each of the status levels:

Table 2-3 Service Status Descriptions

Status Level	Description
RUNNING	The service is running.
STARTING	A start request has been issued.
PENDING	The service is waiting for a dependency to start.
WAITING	The service is waiting for a time dependency to complete.
DEAD	The service is not running.
ERROR	It was not possible to retrieve the value from the process agent.

Alert/Restart Syslog Messages

When an alert or restart message is generated by nco_pad, it is passed to the syslog system. Cisco Info Center has a syslog Cisco Info Mediator available which can monitor these messages and convert them into Cisco Info Server alerts. See the Cisco Info Center Mediator and Gateway Reference guide for more information. The alert and restore messages are sent to syslog as warnings.

A typical message is formatted as:

<HOSTNAME> : ALERT_MSG : <MSG>

or:

<HOSTNAME> : RESTORE_MSG : <MSG>

Where <HOSTNAME> is the name of the host which has reported the problem, ALERT_MSG or RESTORE_MSG describes which kind of message it is and <MSG> is the text defined in the configuration file for that process or host.

Converting a Process Control Configuration

You can convert a configuration file from a previous version into the new format using the nco_pa_convert command.

To convert a configuration file, specify the following command:

$OMNIHOME/bin/nco_pa_convert -configfile <old.conf> -outfile <new.conf>

Where <old.conf> is the name of the configuration file from a previous version of Process Control, and <new.conf> is a name for the converted file.

Process Control Management

The Process Control system provides various functions to manage and change the configuration.

The following sections describe the management functions available from the command line. Each of the commands issues a prompt for your UNIX password.

Service Status

Retrieves the status of any service in the configuration. The command returns a list of defined processes, the status of each process, and the UNIX process identifier.

Syntax

nco_pa_status -server <string> -user <string> -password <string> -help -version

Command Line Parameters

Table 2-4 nco_pa_status Command Line Parameters

Option	Parameter	Description
-server	<string>	Name of Process Control agent to contact.
-user	<string>	User name to issue the command as.
-password	<string>	User name password.
-help		Displays Help on the command line options and exits.
-version		Displays software version information and exits.

Starting a Service or Process

Starts a service or process at any location in the configuration. You can only specify a single service or process. When the service or process has already been started, the command is ignored.

Syntax

nco_pa_start -server <string> -user <string> -password <string> -service <string>
-process <string> -help -version

Command Line Parameters

Table 2-5 nco_pa_start Command Line Parameters 

Option	Parameter	Description
-server	<string>	Name of Process Control agent to contact.
-user	<string>	User name to issue the command as.
-password	<string>	User name password.
-service	<string>	Name of the service to start.
-process	<string>	Name of the process to start.
-help		Displays Help on the command line options and exits.
-version		Displays software version information and exits.

Stopping a Service or Process

Stops a service or process at any location in the configuration. You can only specify a single service or process. When the service or process has already been stopped, the command is ignored.

Syntax

nco_pa_stop -server <string> -user <string> -password <string> -service <string>
-process <string> -help -version

Command Line Parameters

Table 2-6 nco_pa_stop Command Line Parameters

Option	Parameter	Description
-server	<string>	Name of Process Control agent to contact.
-user	<string>	User name to issue the command as.
-password	<string>	User name password.
-service	<string>	Name of the service to start.
-process	<string>	Name of the process to start
-help		Displays Help on the command line options and exits.
-version		Displays software version information and exits.

Shutting Down a Process Control Agent

Shuts down a complete Process Control agent and stops associated services and processes.

---

Note This method of stopping processes is not recommended. Instead, use the following command to stop the Info Server and any other Cisco Info Center components installed on the host:

/etc/init.d/nco stop

---

Syntax

nco_pa_shutdown -server <string> -user <string> -password <string>
-option <string> -help -version

Command Line Parameters

Table 2-7 nco_pa_shutdown Command Line Parameters

Option	Parameter	Description
-server	<string>	Name of Process Control agent to contact.
-user	<string>	User name to issue command as.
-password	<string>	User name password.
-help		Displays Help on the command line options and exits.
-option	<string>	Specifies how the shutdown is completed. Can be STOP to shutdown the Process Control agent completely, or LEAVE to leave the managed processes running after the shutdown.
-version		Displays software version information and exits.

Process Control Agent Daemon Command Line Options

This section describes the command line syntax and options available for the Process Control agent daemon.

Syntax

nco_pad -name <string> -configfile <string> -noconfig -logfile <string> -newlog
-nodaemon -apicheck -trace -noauto -retrytime <string> -stacksize <numeric>
-help -version

Command Line Parameters

Table 2-8 nco_pad Command Line Parameters 

Option	Parameter	Description
-name	<string>	Use the string as the name of the server for this Process Control agent. When not specified, defaults to NCO_PA for the process controller name.
-configfile	<string>	Use string as the configuration file rather than $OMNIHOME/etc/nco_pa.conf (the default).
-noconfig		Do not read the configuration file. Forces Process Control to start with no configuration information.
-logfile	<string>	Use string as the log file rather than $OMNIHOME/log/paname.log (the default, where paname is the name of the Process Control agent specified with -name).
-newlog		Start a new log file. Without this option, Process Control appends to the end of any existing log file. With this option, the log is cleared first.
-nodaemon		By default, Process Control forks into the background to run as a daemon process. With the -nodaemon option, the process runs in foreground.
-apicheck		Enables Sybase API checking.
-trace		Enables the net library tracing.
-noauto		Does not start the automatic start services.
-retrytime	<string>	Failed process start retry time out.
-stacksize	<numeric>	The size of the thread stack.
-help		Displays Help information on the Process Control agent and exits.
-version		Displays version information on the Process Control agent and exits.