Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### 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 subprocess exits does the process monitor attempt to restart the process.

You can run this command in the global zone. The command affects only the 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 re-instantiated 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 re-instantiated 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

is

    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 | ha-cluster/system/core
Interface Stability | Evolving

## See Also

`kill`(1), `rpc.pmfd`(1M), `attributes`(5)

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |