TORQUE Resource Manager
1.3 Advanced Configuration

1.3 Advanced Configuration

1.3.1 Customizing the Install

The TORQUE configure command has several options available. Listed below are some suggested options to use when running ./configure.

  • By default, TORQUE does not install the admin manuals. To enable this, use --enable-docs
  • By default, TORQUE does not enable syslog usage. To enable this, use --enable-syslog

Full Configure Options List

Optional features:
Option Description
directs torque not to build and install the TORQUE client utilities such as qsub, qstat, qdel, etc.
directs TORQUE build system to only rebuild changed source files and not rebuild dependent files.
do not include FEATURE (same as --enable-FEATURE=no).
Disable gcc strictness and warnings. If using gcc, default is to error on any warning.
do not include the GUI-clients.
avoid locking (might break parallel builds).
do not include the MOM daemon.
Don't check free space on spool directory and set an error.
disable the moms use of mlockall. Some versions of OSs seem to have buggy POSIX MEMLOCK.
disable the use of privileged ports for authentication. Some versions of OSX have a buggy bind() and cannot bind to privileged ports.
do not allow the qsub -k flag to override -o -e.
By default, TORQUE uses RPP/UDP for resource queries from the PBS server to the MOMs. If disabled, TCP is used. This does not affect general node/job status messages, job launch/exit messages, inter-mom messages, etc.
do not include server and scheduler.
give the job script file as standard input to the shell instead of passing its name via a pipe.
if disabled, TORQUE will create output and error files directly in $HOME/.pbs_spool if it exists or in $HOME otherwise. By default, TORQUE will spool files in TORQUE_HOME/spool and copy them to the users home directory when the job completes.
With HPUX and GCC, don't force usage of XOPEN and libxnet.
enable adding x attributes to accounting log.
setting this under IRIX enables the SGI Origin 2000 parallel support. Normally autodetected from the /etc/config/array file.
allows jobs to run automatically as soon as they are queued if resources are available (available in TORQUE 2.3.1 and later).
enable BLCR support.
enable Cray's CPA support.
enable Linux 2.6 kernel cpusets (in development).
turn on the compilation of DEBUG code.
do not reject slow dependency extractors.
build the DRMAA 1.0 library.
optimize for fast installation [default=yes].
include FEATURE [ARG=yes].
Open files with sync on each write operation. This has a negative impact on TORQUE performance. This is disabled by default.
forces creation of nodefile regardless of job submission parameters. Not on by default.
TORQUE is compiled to use procs_bitmap during job submission.
enables enhanced high availability (high availability is enabled by default, but this option enables the enhanced version)
this is for the autoconf utility and tells autoconf to enable so called rebuild rules. See maintainer mode for more information.
turn on the RESOURCEMAXDEFAULT flag.

Note

Versions of TORQUE earlier than 2.4.5 attempted to apply queue and server defaults to a job that didn't have defaults specified. If a setting still did not have a value after that, TORQUE applied the queue and server maximum values to a job (meaning, the maximum values for an applicable setting were applied to jobs that had no specified or default value).

In TORQUE 2.4.5 and later, the queue and server maximum values are no longer used as a value for missing settings. To reenable this behavior in TORQUE 2.4.5 and later, use --enable-maxdefault.

turn on the NO_SIGCHLD flag.
enable nodemask-based scheduling on the Origin 2000.
enable pemask-based scheduling on the Cray T3e.
enable daemons to lock themselves into memory: logical-or of 1 for pbs_server, 2 for pbs_scheduler, 4 for pbs_mom (no argument means 7 for all three).
turn on the QUICKCOMMIT flag.
build shared libraries [default=yes].
enable this to put the job script name on the command line that invokes the shell. Not on by default. Ignores --enable-shell-pipe setting.
build PBS for an IBM SP2.
enable support for SRFS on Cray.
build static libraries [default=yes].
enable (default) the use of syslog for error reporting.
setting this builds qstat with Tcl interpreter features. This is enabled if Tcl is enabled.
enable the use of Unix Domain sockets for authentication.


Optional Packages:
Option Description
BLCR installation prefix (Note: Available in versions 2.5.6 and 3.0.2 and later.)
include path for libcr.h (Note: Available in versions 2.5.6 and 3.0.2 and later.)
lib path for libcr (Note: Available in versions 2.5.6 and 3.0.2 and later.)
bin path for BLCR utilities (Note: Available in versions 2.5.6 and 3.0.2 and later.)
include path for cpalib.h.
lib path for libcpalib.
compile with debugging symbols.
set the name of the computer that clients will access when no machine name is specified as part of the queue name. It defaults to the hostname of the machine on which PBS is being compiled.
set the path containing the environment variables for the daemons. For SP2 and AIX systems, suggested setting is to /etc/environment. Defaults to the file "pbs_environment" in the server-home. Relative paths are interpreted within the context of the server-home.
assume the C compiler uses GNU ld [default=no].
override the default domain for outgoing mail messages, i.e. "user@maildomain". The default maildomain is the hostname where the job was submitted from.
use module files in specified directory [/etc/modulefiles].
use this directory for MOM logs.
use this suffix for MOM logs.
do not use PACKAGE (same as --with-PACKAGE=no).
do not include readline support (default: included if found).
use PACKAGE [ARG=yes].
Directory that holds the system PAM modules. Defaults to /lib(64)/security on Linux.
try to use only PIC/non-PIC objects [default=use both].
set the name of the file that qstat will use if there is no ".qstatrc" file in the directory where it is being invoked. Relative path names will be evaluated relative to the server home directory (see above). If this option is not specified, the default name for this file will be set to "qstatrc" (no dot) in the server home directory.
one of "scp", "rcp", "mom_rcp", or the fullpath of a remote file copy program. scp is the default if found, otherwise mom_rcp is used. Some rcp programs don't always exit with valid error codes in case of failure. mom_rcp is a copy of BSD rcp included with this source that has correct error codes, but it is also old, unmaintained, and doesn't have largefile support.
sets the scheduler type. If TYPE is "c", the scheduler will be written in C. If TYPE is "tcl" the server will use a Tcl based scheduler. If TYPE is "basl", TORQUE will use the rule based scheduler. If TYPE is "no", then no scheduling is done. "c" is the default.
sets the name of the scheduler to use. This only applies to BASL schedulers and those written in the C language. For C schedulers this should be a directory name and for BASL schedulers a filename ending in ".basl". It will be interpreted relative to srctree/src/schedulers.SCHD_TYPE/samples. As an example, an appropriate BASL scheduler realtive path would be "nas.basl". The default scheduler code for "C" schedulers is "fifo".
In TORQUE 2.1 and later, SCP is the default remote copy protocol. See --with-rcp if a different protocol is desired.
sendmail executable to use.
set the server home/spool directory for PBS use. Defaults to /var/spool/torque.
set the file that will contain the name of the default server for clients to use. If this is not an absolute pathname, it will be evaluated relative to the server home directory that either defaults to /usr/spool/PBS or is set using the --with-server-home option to configure. If this option is not specified, the default name for this file will be set to "server_name".
include additional configurations [automatic].
directory containing tcl configuration (tclConfig.sh).
set the Tcl attribute separator character this will default to "." if unspecified.
directory containing the public Tcl header files.
directory containing tclx configuration (tclxConfig.sh).
directory containing tk configuration (tkConfig.sh).
directory containing the public Tk header files.
directory containing tkx configuration (tkxConfig.sh).
set the tmp directory that pbs_mom will use. Defaults to "/tmp". This is a Cray-specific feature.
specify path to xauth program.

1.3.1.1 HAVE_WORDEXP

Wordxp() performs a shell-like expansion, including environment variables. By default, HAVE_WORDEXP is set to 1 in src/pbs_config.h. If set to 1, TORQUE will limit the characters that can be used in a job name to those allowed for a file in the current environment, such as BASH. If set to 0, any valid character for the file system can be used.

If a user would like to disable this feature by setting HAVE_WORDEXP to 0 in src/include/pbs_config.h, it is important to note that the error and the output file names will not expand environment variables, including $PBS_JOBID. The other important consideration is that characters that BASH dislikes, such as (), will not be allowed in the output and error file names for jobs by default.

1.3.2 Server Configuration

1.3.2.1 Server Configuration Overview

There are several steps to ensure that the server and the nodes are completely aware of each other and able to communicate directly. Some of this configuration takes place within TORQUE directly using the qmgr command. Other configuration settings are managed using the pbs_server nodes file, DNS files such as /etc/hosts and the /etc/hosts.equiv file.

1.3.2.2 Name Service Configuration

Each node, as well as the server, must be able to resolve the name of every node with which it will interact. This can be accomplished using /etc/hosts, DNS, NIS, or other mechanisms. In the case of /etc/hosts, the file can be shared across systems in most cases.

A simple method of checking proper name service configuration is to verify that the server and the nodes can "ping" each other.

1.3.2.3 Configuring Job Submission Hosts

Using RCmd Authentication

When jobs can be submitted from several different hosts, these hosts should be trusted via the R* commands (such as rsh and rcp). This can be enabled by adding the hosts to the /etc/hosts.equiv file of the machine executing the pbs_server daemon or using other R* command authorization methods. The exact specification can vary from OS to OS (see the man page for ruserok to find out how your OS validates remote users). In most cases, configuring this file is as simple as adding a line to your /etc/hosts.equiv file, as in the following:

/etc/hosts.equiv:
#[+ | -] [hostname] [username]
mynode.myorganization.com
.....

Either of the hostname or username fields may be replaced with a wildcard symbol (+). The (+) may be used as a stand-alone wildcard but not connected to a username or hostname, e.g., +node01 or +user01. However, a (-) may be used in that manner to specifically exclude a user.

Caution Following the Linux man page instructions for hosts.equiv may result in a failure. You cannot precede the user or hostname with a (+). To clarify, node1 +user1 will not work and user1 will not be able to submit jobs.

For example, the following lines will not work or will not have the desired effect:

+node02 user1
node02 +user1

These lines will work:

node03 +
+ jsmith
node04 -tjones

The most restrictive rules must precede more permissive rules. For example, to restrict user tsmith but allow all others, follow this format:

node01 -tsmith
node01 +

Please note that when a hostname is specified, it must be the fully qualified domain name (FQDN) of the host. Job submission can be further secured using the server or queue acl_hosts and acl_host_enabled parameters.

Using the submit_hosts Server Parameter

Trusted submit host access may be directly specified without using RCmd authentication by setting the server submit_hosts parameter via qmgr as in the following example:

> qmgr -c 'set server submit_hosts = host1'
> qmgr -c 'set server submit_hosts += host2'
> qmgr -c 'set server submit_hosts += host3'

Note Use of submit_hosts is potentially subject to DNS spoofing and should not be used outside of controlled and trusted environments.

Allowing Job Submission from Compute Hosts

If preferred, all compute nodes can be enabled as job submit hosts without setting .rhosts or hosts.equiv by setting the allow_node_submit parameter to true.

1.3.2.4 Configuring TORQUE on a Multi-Homed Server

If the pbs_server daemon is to be run on a multi-homed host (a host possessing multiple network interfaces), the interface to be used can be explicitly set using the SERVERHOST parameter.

1.3.2.5 Architecture Specific Notes

1.3.2.5.1 Mac OS/X Specific Notes

With some versions of Mac OS/X, it is required to add the line $restricted *.<DOMAIN> to the pbs_mom configuration file. This is required to work around some socket bind bugs in the OS.

1.3.2.6 Specifying Non-Root Administrators

By default, only root is allowed to start, configure and manage the pbs_server daemon. Additional trusted users can be authorized using the parameters managers and operators. To configure these parameters use the qmgr command, as in the following example:

> qmgr

Qmgr: set server managers += josh@*.fsc.com
Qmgr: set server operators += josh@*.fsc.com

All manager and operator specifications must include a user name and either a fully qualified domain name or a host expression.

Note To enable all users to be trusted as both operators and administrators, place the + (plus) character on its own line in the server_priv/acl_svr/operators and server_priv/acl_svr/managers files.

1.3.2.7 Setting Up E-mail

Moab relies on e-mails from TORQUE about job events. To set up e-mail, do the following:

  1. Use the --with-sendmail configure option at configure time. TORQUE needs to know where the email application is. If this option is not used, TORQUE tries to find the sendmail executable. If it isn't found, TORQUE cannot send e-mails.
    > ./configure --with-sendmail=<path_to_executable>
  2. Set mail_domain in your server settings. If your domain is clusterresources.com, execute:
    > qmgr -c 'set server mail_domain=clusterresources.com'
  3. (Optional) You can override the default mail_body_fmt and mail_subject_fmt values via qmgr:
    > qmgr -c 'set server mail_body_fmt=Job: %i \n Name: %j \n On host: %h \n \n %m \n \n %d'
    > qmgr -c 'set server mail_subject_fmt=Job %i - %r'

By default, users receive e-mails on job aborts. Each user can select which kind of e-mails to receive by using the qsub -m option when submitting the job. If you want to dictate when each user should receive e-mails, use a submit filter.

1.3.2.8 Using MUNGE Authentication

MUNGE is an authentication service that creates and validates user credentials. It was developed by Lawrence Livermore National Laboratoy (LLNL) to be highly scalable so it can be used in large environments such as HPC clusters. To learn more about MUNGE and how to install it, see http://code.google.com/p/munge/

Configuring TORQUE to use MUNGE is a compile time operation. When you are building TORQUE use –enable-munge-auth as a command line option with ./configure.

> ./configure –enable-munge-auth

You can use only one authorization method at a time. If –enable-munge-auth is configured, the privileged port ruserok method is disabled.

TORQUE does not link any part of the MUNGE library into its executables. It calls the MUNGE and UNMUNGE utilities which are part of the MUNGE daemon. The MUNGE daemon must be running on the server and all submission hosts. The TORQUE client utilities call MUNGE and then deliver the encrypted credential to pbs_server where the credential is then unmunged and the server verifies the user and host against the authorized users configured in serverdb.

Authorized users are added to serverdb using qmgr and the authorized_users server parameter. The syntax for authorized_users is authorized_users=<user>@<host>. To add an authorized user to the server you can use the following qmgr command:

> qmgr -c 'set server authorized_users=user1@hosta
> qmgr -c 'set server authorized_users+=user2@hosta

The previous example adds user1 and user2 from hosta to the list of authorized users on the server. Users can be removed from the list of authorized users by using the -= syntax as follows:

> qmgr  -c 'set server authorized_users-=user1@hosta

Users must be added with the <user>@<host> syntax. The user and the host portion can use the '*' wildcard to allow multiple names to be accepted with a single entry. A range of user or host names can be specified using a [a-b] syntax where a is the beginning of the range and b is the end.

> qmgr  -c 'set server authorized_users=user[1-10]@hosta

This allows user1 through user10 on hosta to run client commands on the server.

See Also