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)