pmfadm(1M) System Administration Commands 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 origi-
nal 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 direc-
tory, 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 inter-
est. 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 re-
direction, 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 envi-
ronment 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 sig-
nal 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 associ-
ated 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 |SUNWscu |
+-----------------------------+-----------------------------+
|Interface Stability |Evolving |
+-----------------------------+-----------------------------+
SEE ALSO
kill(1), truss(1), rpc.pmfd(1M), attributes(5)
NOTES
To avoid collisions with other controlling processes. The truss command does not allow tracing a process that it detects as being con-
trolled 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 13 Aug 2007 pmfadm(1M)