pmfadm(1M) (Sun Cluster Reference Manual for Solaris OS)

Sun Cluster Reference Manual for Solaris OS

pmfadm(1M)

NAME

pmfadm – process monitor facility administration

Synopsis

/usr/cluster/bin/pmfadm -c nametag [-a action] [
 [-e ENV_VAR=env.var…] | -E] [-n retries] [-t period]
 [-C level#] command [args-to-command…]

/usr/cluster/bin/pmfadm -k nametag [-w timeout] [signal]

/usr/cluster/bin/pmfadm -L [-h host]

/usr/cluster/bin/pmfadm -l nametag [-h host]

/usr/cluster/bin/pmfadm -m nametag [-n retries] [-t period]

/usr/cluster/bin/pmfadm -q nametag [-h host]

/usr/cluster/bin/pmfadm -s nametag [-w timeout] [signal]

Description

The pmfadm utility provides the administrative, command-line interface to the process monitor facility.

The process monitor facility provides a means of monitoring processes, and their descendents, and restarting them if they fail to remain alive. The total number of failures allowed can be specified, and limited to a specific time period. After the maximum number of failures has occurred within the specified time period, a message is logged to the console, and the process is no longer restarted.

If an action program has been specified, it is called when the number of failures allowed has been reached. If the action program exits with non-zero status, the process nametag is removed from the process monitor facility. Otherwise, the process is restarted with the original parameters passed into pmfadm.

Processes that are started under control of the process monitor are run as the effective user ID (euid) and effective group ID (egid) of the user that initiated the request. Only the original user, or root, can manipulate the nametag associated with those processes. Status information, however, is available to any caller, local or remote.

All spawned processes, and their descendent spawned processes, of the process that initially started are monitored. Only when the last process or sub-process exits does the process monitor attempt to restart the process.

You can run this command in the global zone or in a non-global zone. The command affects only the global or non-global zone in which you issue the command.

Options

The following options are supported:

-a action

The action program to be called when the process fails to stay alive. This program must be specified in a single argument to the -a option, but can be a quoted string that contains multiple components. In either case, the string is executed as specified, with two additional arguments, the event that occurred (currently only failed), and the nametag associated with the process. The current directory, and PATH environment variable, are reinstantiated before the command is executed. No other environment variables are, or should be assumed to be, preserved.

If the action program exits with status 0, the process is started over again with the original arguments that were given to pmfadm. Any other exit status causes the nametag to cease to exist within the scope of the process monitor.

If no -a option is specified, the result is the same as if there were an action script specified which always exits non-zero.

-C level#

When starting a process, monitor it and its children up to and including level level#. The value of level# must be an integer greater than or equal to zero. The original process executed is at level 0, its children are executed at level 1, their children are executed at level 2, and so on. Any new fork operation produces a new level of children.

This option provides more control over which processes get monitored. It is useful for monitoring servers that fork new processes.

When this option is not specified, all children are monitored, and the original process is not restarted until it and all its children have died.

If a server forks new processes to handle client requests, it might be desirable to monitor only the server. The server needs to be restarted if it dies even if some client processes are still running. The appropriate monitoring level is -C 0.

If, after forking a child, the parent exits, then it is the child that needs monitoring. The level to use to monitor the child is -C 1. When both processes die, the server is restarted.

-c nametag

Start a process, with nametag as an identifier. All arguments that follow the command-line flags are executed as the process of interest. The current directory, and PATH environment variable, are reinstantiated by the process monitor facility before the command is executed. No other environment variables are, or should be assumed to be, preserved.

If nametag already exists, pmfadm exits with exit status 1, with no side effects.

I/O redirection is not supported in the command-line arguments. If this is necessary, a script should be created that performs this redirection, and used as the command that pmfadm executes.

-E

Pass the whole pmfadm environment to the new process. The default is not to use this option, in which case the rpc.pmfd environment plus the path of the pmfadm environment are passed.

The -e and -E options are mutually exclusive, that is, both cannot be used in the same command.

-e ENV_VAR=env.value

An environment variable in the form ENV_VAR=env.value which is passed to the execution environment of the new process. This option can be repeated, so multiple environment variables can be passed. The default is not to use this option, in which case the rpc.pmfd environment plus the path of the pmfadm environment are passed.

-h host

The name of the host to contact. Defaults to localhost.

-k nametag

Send the specified signal to the processes associated with nametag, including any processes associated with the action program if it is currently running. The default signal, SIGKILL, is sent if none is specified. If the process and its descendants exit, and there are remaining retries available, the process monitor restarts the process. The signal specified is the same set of names recognized by the kill command.

-L

Return a list of all tags running that belong to the user that issued the command, or if the user is root, all tags running on the server are shown.

-l nametag

Print out status information about nametag. The output from this command is useful mainly for diagnostics and might be subject to change.

-m nametag

Modify the number of retries, or time period over which to observe retries, for nametag. Once these parameters have been changed, the history of earlier failures is cleared.

-n retries

Number of retries allowed within the specified time period. The default value for this field is 0, which means that the process is not restarted once it exits. The maximum value allowed is 100. A value of -1 indicates that the number of retries is infinite.

-q nametag

Indicate whether nametag is registered and running under the process monitor. Returns 0 if it is, 1 if it is not. Other return values indicate an error.

-s nametag

Stop restarting the command associated with nametag. The signal, if specified, is sent to all processes, including the action script and its processes if they are currently executing. If a signal is not specified, none is sent. Stopping the monitoring of processes does not imply that they no longer exist. The processes remain running until they, and all of their descendents, have exited. The signal specified is the same set of names recognized by the kill command.

-t period

Minutes over which to count failures. The default value for this flag is -1, which equates to infinity. If this parameter is specified, process failures that have occurred outside of the specified period are not counted.

-w timeout

When used in conjunction with the -s nametag or -k nametag flags, wait up to the specified number of seconds for the processes associated with nametag to exit. If the timeout expires, pmfadm exits with exit status 2. The default value for this flag is 0, meaning that the command returns immediately without waiting for any process to exit.

If a value of -1 is given, pmfadm waits indefinitely for the processes associated with the tag to exit. The pmfadm process does not release the RPC server thread that it uses until the RPC timeout period is reached. Therefore, avoid setting the -w timeout value to -1 unnecessarily.

Examples

Example 1 Starting a Sleep Process That Will Not be Restarted

The following example starts a sleep process named sleep.once that will not be restarted once it exits:

example% pmfadm -c sleep.once /bin/sleep 5

Example 2 Starting a Sleep Process and Restarting It

The following example starts a sleep process and restarts it, at most, one time:

example% pmfadm -c sleep.twice –n 1 /bin/sleep 5

Example 3 Starting a Sleep Process and Restarting It

The following examples start a sleep process and restarts it, at most, twice per minute. It calls /bin/true when it fails to remain running beyond the acceptable number of failures:

example% pmfadm -c sleep.forever –n 2 –t 1 –a /bin/true /bin/sleep 60

Example 4 Listing the Current Status of the `sleep.forever` Nametag

The following command lists the current status of the sleep.forever nametag:

example% pmfadm -l sleep.forever

Example 5 Sending a `SIGHUP` to All Processes

The following command sends a SIGHUP to all processes associated with sleep.forever, waiting up to five seconds for all processes to exit.

example% pmfadm -w 5 -k sleep.forever HUP

Example 6 Stopping the Monitoring of Processes and Sending a `SIGHUP`

The following command stops monitoring (restarting) processes associated with sleep.forever, and sends a SIGHUP to any processes related to it. This command returns as soon as the signals have been delivered, but possibly before all processes have exited.

example% pmfadm -s sleep.forever HUP

Example 7 Listing All Tags Running That Belong to the User

If a user issues the following commands:

example% pmfadm -c sleep.once /bin/sleep 30
example% pmfadm -c sleep.twice /bin/sleep 60
example% pmfadm -c sleep.forever /bin/sleep 90

the output of the following command:

example% pmfadm -L

sleep.once sleep.twice sleep.forever

Exit Status

The following exit values are returned:

0: Successful completion.
1: nametag doesn't exist, or there was an attempt to create a nametag that already exists.
2: The command timed out.
other nonzero: An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWscu
Interface Stability	Evolving

Notes

To avoid collisions with other controlling processes. The truss command does not allow tracing a process that it detects as being controlled by another process by way of the /proc interface. Because the rpc.pmfd daemon prior to Solaris 10 OS uses the /proc interface to monitor processes and their descendants, those processes that are submitted to rpc.pmfd by way of the pmfadm command cannot be traced or debugged. As of the Solaris 10 OS release, this restriction no longer applies.

Sun Cluster 3.2 Last Revised 13 Aug 2007