Start a pbs batch execution mini-server.
pbs_mom [-a alarm] [-A alias] [-C chkdirectory] [-c config] [-d directory] [-f] [-F] [-h help] [-H hostname] [-L logfile] [-M MOMport] [-R RMPport] [-p|-r] [-P purge] [-w] [-x]
The pbs_mom command is located within the TORQUE_HOME directory and starts the operation of a batch Machine Oriented Mini-server (MOM) on the execution host. To ensure that the pbs_mom command is not runnable by the general user community, the server will only execute if its real and effective uid is zero.
The first function of pbs_mom is to place jobs into execution as directed by the server, establish resource usage limits, monitor the job's usage, and notify the server when the job completes. If they exist, pbs_mom will execute a prologue script before executing a job and an epilogue script after executing the job.
The second function of pbs_mom is to respond to resource monitor requests. This was done by a separate process in previous versions of PBS but has now been combined into one process. It provides information about the status of running jobs, memory available, etc.
The last function of pbs_mom is to respond to task manager requests. This involves communicating with running tasks over a TCP socket as well as communicating with other MOMs within a job (a.k.a. a "sisterhood").
pbs_mom will record a diagnostic message in a log file for any error occurrence. The log files are maintained in the mom_logs directory below the home directory of the server. If the log file cannot be opened, the diagnostic message is written to the system console.
| Flag | Name | Description |
|---|---|---|
| -a | alarm | Specifies the alarm timeout in seconds for computing a resource. Every time a resource request is processed, an alarm is set for the given amount of time. If the request has not completed before the given time, an alarm signal is generated. The default is 5 seconds. |
| -A | alias | Specifies this multimom's alias name. The alias name needs to be the same name used in the mom.hierarchy file. It is only needed when running multiple MOMs on the same machine. For more information, see Torque Multi-MOM. |
| -c | config | Specifies an alternative configuration file, see description below. If this is a relative file name it will be relative to TORQUE_HOME/mom_priv, (see the -d option). If the specified file cannot be opened, pbs_mom will abort. If the -c option is not supplied, pbs_mom will attempt to open the default configuration file "config" in TORQUE_HOME/mom_priv. If this file is not present, pbs_mom will log the fact and continue. |
| -C | chkdirectory | Specifies the path of the directory used to hold checkpoint files. (Currently this is only valid on Cray systems.) The default directory is TORQUE_HOME/spool/checkpoint (see the -d option). The directory specified with the -C option must be owned by root and accessible (rwx) only by root to protect the security of the checkpoint files. |
| -d | directory | Specifies the path of the directory which is the home of the server's working files, TORQUE_HOME. This option is typically used along with -M when debugging MOM. The default directory is given by $PBS_SERVER_HOME which is typically /usr/spool/PBS. |
| -f | force_update | Forces the server to accept an update of the hardware on the node. Should be used the first time pbs_mom is run after a hardware update on a node. |
| -F | fork |
Do not fork. 
This option is useful when running under systemd (Red Hat 7-based or SUSE 12-based systems). |
| -h | help | Displays the help/usage message. |
| -H | hostname | Sets the MOM's hostname. This can be useful on multi-homed networks. |
| -L | logfile | Specifies an absolute path name for use as the log file. If not specified, MOM will open a file named for the current date in the TORQUE_HOME/mom_logs directory (see the -d option). |
| -M | port | Specifies the port number on which the mini-server (MOM) will listen for batch requests. |
| -p | n/a | Specifies the impact on jobs which were in execution when the mini-server shut down. On any restart of MOM, the new mini-server will not be the parent of any running jobs, MOM has lost control of her offspring (not a new situation for a mother). With the -p option, MOM will allow the jobs to continue to run and monitor them indirectly via polling. This flag is redundant in that this is the default behavior when starting the server. The -p option is mutually exclusive with the -r and -q options. |
| -P | purge | Specifies the impact on jobs which were in execution when the mini-server shut down. With the -P option, it is assumed that either the entire system has been restarted or the MOM has been down so long that it can no longer guarantee that the pid of any running process is the same as the recorded job process pid of a recovering job. Unlike the -p option, no attempt is made to try and preserve or recover running jobs. All jobs are terminated and removed from the queue. |
| -q | n/a | Specifies the impact on jobs which were in execution when the mini-server shut down. With the -q option, MOM will allow the processes belonging to jobs to continue to run, but will not attempt to monitor them. The -q option is mutually exclusive with the -p and -r options. |
| -r | n/a |
Specifies the impact on jobs which were in execution when the mini-server shut down. With the -r option, MOM will kill any processes belonging to jobs, mark the jobs as terminated, and notify the batch server which owns the job. The -r option is mutually exclusive with the -p and -q options. Normally the mini-server is started from the system boot file without the -p or the -r option. The mini-server will make no attempt to signal the former session of any job which may have been running when the mini-server terminated. It is assumed that on reboot, all processes have been killed. If the -r option is used following a reboot, process IDs (pids) may be reused and MOM may kill a process that is not a batch session. |
| -R | port | Specifies the port number on which the mini-server (MOM) will listen for resource monitor requests, task manager requests and inter-MOM messages. Both a UDP and a TCP port of this number will be used. |
| -w | wait_for_server | When started with -w, pbs_moms wait until they get their MOM hierarchy file from pbs_server to send their first update, or until 10 minutes pass. This reduces network traffic on startup and can bring up clusters faster. |
| -x | n/a | Disables the check for privileged port resource monitor connections. This is used mainly for testing since the privileged port is the only mechanism used to prevent any ordinary user from connecting. |
The configuration file, located at mom_priv/config by default, can be specified on the command line at program start with the -c flag. The use of this file is to provide several types of run time information to pbs_mom: static resource names and values, external resources provided by a program to be run on request via a shell escape, and values to pass to internal set up functions at initialization (and re-initialization).
See the Parameters page for a full list of pbs_mom parameters.
Each item type is on a single line with the component parts separated by white space. If the line starts with a hash mark (pound sign, #), the line is considered to be a comment and is skipped.
Static Resources
For static resource names and values, the configuration file contains a list of resource names/values pairs, one pair per line and separated by white space. An example of static resource names and values could be the number of tape drives of different types and could be specified by:
- tape3480 4
- tape3420 2
- tapedat 1
- tape8mm 1
Shell Commands
If the first character of the value is an exclamation mark (!), the entire rest of the line is saved to be executed through the services of the system(3) standard library routine.
The shell escape provides a means for the resource monitor to yield arbitrary information to the scheduler. Parameter substitution is done such that the value of any qualifier sent with the query, as explained below, replaces a token with a percent sign (%) followed by the name of the qualifier. For example, here is a configuration file line which gives a resource name of "escape":
escape !echo %xxx %yyy
If a query for "escape" is sent with no qualifiers, the command executed would be echo %xxx %yyy.
If one qualifier is sent, escape[xxx=hi there], the command executed would be echo hi there %yyy.
If two qualifiers are sent, escape[xxx=hi][yyy=there], the command executed would be echo hi there.
If a qualifier is sent with no matching token in the command line, escape[zzz=snafu], an error is reported.
Resource Manager queries can be made with momctl -q options to retrieve and set pbs_mom options. Any configured static resource may be retrieved with a request of the same name. These are resource requests not otherwise documented in the PBS ERS.
| Request | Description |
|---|---|
| cycle | Forces an immediate MOM cycle. |
| status_update_time | Retrieve or set the $status_update_time parameter. |
| check_poll_time | Retrieve or set the $check_poll_time parameter. |
| configversion | Retrieve the config version. |
| jobstartblocktime | Retrieve or set the $jobstartblocktime parameter. |
| enablemomrestart | Retrieve or set the $enablemomrestart parameter. |
| loglevel | Retrieve or set the $loglevel parameter. |
| down_on_error | Retrieve or set the $down_on_error parameter. |
| diag0 - diag4 | Retrieves varied diagnostic information. |
| rcpcmd | Retrieve or set the $rcpcmd parameter. |
| version | Retrieves the pbs_mom version. |
The health check script is executed directly by the pbs_mom daemon under the root user id. It must be accessible from the compute node and may be a script or compiled executable program. It may make any needed system calls and execute any combination of system utilities but should not execute resource manager client commands. Also, the pbs_mom daemon blocks until the health check is completed and does not possess a built-in timeout. Consequently, it is advisable to keep the launch script execution time short and verify that the script will not block even under failure conditions.
If the script detects a failure, it should return the ERROR keyword to stdout followed by an error message. The message (up to 1024 characters) immediately following the ERROR string will be assigned to the node attribute message of the associated node.
If the script detects a failure when run from "jobstart", then the job will be rejected. You can use this behavior with an advanced scheduler, such as Moab Workload Manager, to cause the job to be routed to another node. Torque currently ignores Error messages by default, but you can configure an advanced scheduler to react appropriately.
If the $down_on_error MOM setting is enabled, the MOM will set itself to state down and report to pbs_server. Additionally, the $down_on_error server attribute can be enabled which has the same effect but moves the decision to pbs_server. It is redundant to have MOM's $down_on_error and pbs_server's down_on_error features enabled. Also see down_on_error (in Server Parameters).
See 13.12 Creating the Health Check Script for more information.
| File | Description |
|---|---|
| $PBS_SERVER_HOME/server_name | Contains the hostname running pbs_server |
| $PBS_SERVER_HOME/mom_priv | The default directory for configuration files, typically (/usr/spool/pbs)/mom_priv |
| $PBS_SERVER_HOME/mom_logs | Directory for log files recorded by the server |
| $PBS_SERVER_HOME/mom_priv/prologue | The administrative script to be run before job execution |
| $PBS_SERVER_HOME/mom_priv/epilogue | The administrative script to be run after job execution |
pbs_mom handles the following signals:
| Signal | Description |
|---|---|
| SIGHUP | Causes pbs_mom to re-read its configuration file, close and reopen the log file, and reinitialize resource structures. |
| SIGALRM | Results in a log file entry. The signal is used to limit the time taken by certain children processes, such as the prologue and epilogue. |
| SIGINT and SIGTERM | Results in pbs_mom exiting without terminating any running jobs. This is the action for the following signals as well: SIGXCPU, SIGXFSZ, SIGCPULIM, and SIGSHUTDN. |
| SIGUSR1, SIGUSR2 | Causes the MOM to increase and decrease logging levels, respectively. |
| SIGPIPE, SIGINFO | Are ignored. |
| SIGBUS, SIGFPE, SIGILL, SIGTRAP, and SIGSYS | Cause a core dump if the PBSCOREDUMP environmental variable is defined. |
All other signals have their default behavior installed.
If the pbs_mom command fails to begin operation, the server exits with a value greater than zero.
Related Topics
Non-Adaptive Computing topics
- pbs_scheduler_basl(8B)
- pbs_scheduler_tcl(8B)
- PBS External Reference Specification
- PBS Administrators Guide