package: torque-mom

title: pbs_mom(8)

summary: start a pbs batch execution mini-server

text:
# pbs_mom(8)

## NAME
pbs_mom - start a pbs batch execution mini-server

## SYNOPSIS
pbs_mom [-a alarm] [-C chkdirectory] [-c config] [-D] [-d directory] [-F] [-h help] [-H hostname] [-L logfile] [-M MOMport] [-R RPPport] [-p|-q|-r] [-w] [-x]

SH DESCRIPTION The pbs_mom command starts the operation of a batch Machine Oriented Mini-server, MOM, on the local host. Typically, this command will be in a local boot file such as /etc/rc.local . To insure 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.

One 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 next 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. The resource monitor function is provided mainly for the PBS scheduler. It provides information about the status of running jobs, memory available etc. The next 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 (aka 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.

## OPTIONS
-A alias

Used with -m (multi-mom option) to give the alias name of this instance of pbs_mom

-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.

-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 PBS_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.

-c config

Specifies an alternative configuration file, see description below. If this is a relative file name it will be relative to PBS_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 PBS_HOME/mom_priv. If this file is not present, pbs_mom will log the fact and continue.

-h help

Displays the help/usage message.

-H hostname

Sets the MOM's hostname. This can be useful on multi-homed networks.

-D

Debug mode. Do not fork.

-d directory

Specifies the path of the directory which is the home of the servers working files, PBS_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

Do not fork. Use when running under systemd.

-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 PBS_HOME/mom_logs directory, see the -d option.

-m

Directs the MOM to start in multi-mom mode. In addition to using -m the -M, -R and -A options need to be used to properly start a MOM in multi-mom mode. For example pbs_mom -m -M 30002 -R 30003 -A alias-host will start pbs_mom with the service port on port 30002, the manager port at 30003 and with the name alias-host.

-M port

Specifies the port number on which the mini-server (MOM) will listen for batch requests.

-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.

-p

(Default after version 2.4.0) (Preserve running jobs) -- Specifies the impact on jobs which were in execution when the mini-server shut-down. The -p option tries to preserve any running jobs when the MOM restarts. 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). The MOM will allow the jobs to continue to run and monitor them indirectly via polling. All recovered jobs will report an exit code of 0 when they are complete. The -p option is mutually exclusive with the -r, -P and -q options.

-P

(Terminate all jobs and remove them from the queue) -- 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. The -q option is mutually exclusive with the -p, -q and -r options.

-q

(Requeue all jobs - This is the default behavior in versions prior to 2.4.0) -- Specifies the impact on jobs which were in execution when the mini-servershut-down. Do not terminate running processes. With the -q 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. No attempt is made to kill job processes. The MOM will mark the jobs as terminated and notify the batch server which owns the job. Re-runnable jobs will be requeued. The -q option is mutually exclusive with the -p, -P and -r options.

-r

(Terminate running processes and requeue all jobs) -- 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 running jobs, mark the jobs as terminated and notify the batch server that owns the job. Re-runnable jobs are reset to a queued state so they can be run again. The -r option is mutually exclusive with the -p, -P and -q options.

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.

-S port

Specifies the port number on which the pbs_server is listening for requests. If pbs_server is started with a -p option, pbs_mom will need to use the -S option and match the port value which was used to start pbs_server.

-w

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

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.

## CONFIGURATION FILE
The configuration file may 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).

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.

size[fs=<FS>]

Specifies that the available and configured disk space in the <FS> filesystem is to be reported to the pbs_server and scheduler. NOTE: To request disk space on a per job basis, specify the file resource as in 'qsub -l nodes=1,file=1000kb' For example, the available and configured disk space in the /localscratch filesystem will be reported:

size[fs=/localscratch]

Initialization Value

An initialization value directive has a name which starts with a dollar sign ($) and must be known to MOM via an internal table. The entries in this table now are:

auto_ideal_load

if jobs are running, sets idea_load based on a simple expression. The expressions start with the variable 't' (total assigned CPUs) or 'c' (existing CPUs), an operator (+ - / *), and followed by a float constant.

$auto_ideal_load t-0.2

auto_max_load

if jobs are running, sets max_load based on a simple expression. The expressions start with the variable 't' (total assigned CPUs) or 'c' (existing CPUs), an operator (+ - / *), and followed by a float constant.

cputmult

which sets a factor used to adjust cpu time used by a job. This is provided to allow adjustment of time charged and limits enforced where the job might run on systems with different cpu performance. If Mom's system is faster than the reference system, set cputmult to a decimal value greater than 1.0. If Mom's system is slower, set cputmult to a value between 1.0 and 0.0. For example:

$cputmult 1.5

$cputmult 0.75

configversion

specifies the version of the config file data, a string.

check_poll_time

specifies the MOM interval in seconds. MOM checks each job for updated resource usages, exited processes, over-limit conditions, etc. once per interval. This value should be equal or lower to pbs_server's job_stat_rate. High values result in stale information reported to pbs_server. Low values result in increased system usage by MOM. Default is 45 seconds.

down_on_error

causes MOM to report itself as state "down" to pbs_server in the event of a failed health check. This feature is EXPERIMENTAL and likely to be removed in the future. See HEALTH CHECK below.

enablemomrestart

enable automatic restarts of MOM. If enabled, MOM will check if its binary has been updated and restart itself at a safe point when no jobs are running; thus making upgrades easier. The check is made by comparing the mtime of the pbs_mom executable. Command-line args, the process name, and the PATH env variable are preserved across restarts. It is recommended that this not be enabled in the config file, but enabled when desired with momctl (see RESOURCES for more information.)

ideal_load

ideal processor load. Represents a low water mark for the load average. Nodes that are currently busy will consider itself free after falling below ideal_load.

igncput

Ignore cpu time violations on this mom, meaning jobs will not be cancelled due to exceeding their limits for cpu time.

ignmem

Ignore memory violations on this mom, meaning jobs will not be cancelled due to exceeding their memory limits.

ignvmem

If set to true, then pbs_mom will ignore vmem/pvmem limit enforcement.

ignwalltime

If set to true, then pbs_mom will ignore walltime limit enforcement.

job_output_file_mask

Specifies a mask for creating job output and error files. Values can be specified in base 8, 10, or 16; leading 0 implies octal and leading 0x or 0X hexadecimal. A value of "userdefault" will use the user's default umask. $job_output_file_mask 027

log_directory

Changes the log directory. Default is $TORQUEHOME/mom_logs/. $TORQUEHOME default is /var/spool/torque/ but can be changed in the ./configure script. The value is a string and should be the full path to the desired mom log directory. $log_directory /opt/torque/mom_logs/

logevent

which sets the mask that determines which event types are logged by pbs_mom. For example:

$logevent 0x1fff

$logevent 255

The first example would set the log event mask to 0x1ff (511) which enables logging of all events including debug events. The second example would set the mask to 0x0ff (255) which enables all events except debug events.

log_file_suffix

Optional suffix to append to log file names. If %h is the suffix, pbs_mom appends the hostname for where the log files are stored if it knows it, otherwise it will append the hostname where the mom is running. $log_file_suffix tom = 20100223.tom

log_keep_days

Specifies how many days to keep log files. pbs_mom deletes log files older than the specified number of days. If not specified, pbs_mom won't delete log files based on their age.

loglevel

specifies the verbosity of logging with higher numbers specifying more verbose logging. Values may range between 0 and 7.

log_file_max_size

If this is set to a value > 0 then pbs_mom will roll the current log file to log-file-name.1 when its size is greater than or equal to the value of log_file_max_size. This value is interpreted as kilobytes.

log_file_roll_depth

If this is set to a value >=1 and log_file_max_size is set then pbs_mom will continue rolling the log files to log-file-name.log_file_roll_depth.

max_load

maximum processor load. Nodes over this load average are considered busy (see ideal_load above).

memory_pressure_threshold

The option is only available, if pbs_mom is enabled to use cpusets. If set to a value > 0, a job gets killed if its memory pressure exceeds this value, and if $memory_pressure_duration is set. The default is 0 (memory pressure recording is off).

See cpuset(7) for more information about memory pressure.

memory_pressure_duration

The option is only available, if pbs_mom is enabled to use cpusets. Specifies the number of subsequent MOM intervals a job's memory pressure must be above $memory_pressure_threshold to get killed. The default is 0 (jobs are never killed due to memory pressure). set

See cpuset(7) for more information about memory pressure.

node_check_script

specifies the fully qualified pathname of the health check script to run (see HEALTH CHECK for more information).

node_check_interval

specifies when to run the MOM health check. The check can be either periodic, event-driver, or both. The value starts with an integer specifying the number of MOM intervals between subsequent executions of the specified health check. After the integer is an optional comma-separated list of event names. Currently supported are "jobstart" and "jobend". This value defaults to 1 with no events indicating the check is run every MOM interval. (see HEALTH CHECK for more information)

$node_check_interval 0 #Disabled.

$node_check_interval 0,jobstart #Only runs at job starts

$node_check_interval 10,jobstart,jobend

nodefile_suffix

Specifies the suffix to append to a host names to denote the data channel network adapter in a multihomed compute node. $nodefile_suffix i With the suffix of 'i' and the control channel adapter with the name node01, the data channel would have a hostname of node01i.

nospool_dir_list

If the job's output file should be in one of the paths specified here, then it will be spooled directly in that directory instead of the normal spool directory.

Specified in the format path1, path2, etc. $nospool_dir_list/home/mike/*,/var/tmp/spool/

pbsclient

which causes a host name to be added to the list of hosts which will be allowed to connect to MOM as long as they are using a privilaged port for the purposes of resource monitor requests. For example, here are two configuration file lines which will allow the hosts "fred" and "wilma" to connect:

$pbsclient fred

$pbsclient wilma

Two host name are always allowed to connection to pbs_mom, "localhost" and the name returned to pbs_mom by the system call gethostname(). These names need not be specified in the configuration file. The hosts listed as "clients" can issue Resource Monitor (RM) requests. Other MOM nodes and servers do not need to be listed as clients.

pbsserver

which defines hostnames running pbs_server that will be allowed to submit jobs, issue Resource Monitor (RM) requests, and get status updates. MOM will continually attempt to contact all server hosts for node status and state updates. Like $PBS_SERVER_HOME/server_name, the hostname may be followed by a colon and a port number. This parameter replaces the oft-confused $clienthost parameter from TORQUE 2.0.0p0 and earlier. Note that the hostname in $PBS_SERVER_HOME/server_name is used if no $pbsserver parameters are found

prologalarm

Specifies maximum duration (in seconds) which the MOM will wait for the job prolog or job job epilog to complete. This parameter default to 300 seconds (5 minutes)

rcpcmd

Specify the the full path and argument to be used for remote file copies. This overrides the compile-time default found in configure. This must contain 2 words: the full path to the command and the switches. The copy command must be able to recursively copy files to the remote host and accept arguments of the form "user@host:files" For example:

$rcpcmd /usr/bin/rcp -rp

$rcpcmd /usr/bin/scp -rpB

restricted

which causes a host name to be added to the list of hosts which will be allowed to connect to MOM without needing to use a privilaged port. These names allow for wildcard matching. For example, here is a configuration file line which will allow queries from any host from the domain "ibm.com".

$restricted *.ibm.com

The restriction which applies to these connections is that only internal queries may be made. No resources from a config file will be found. This is to prevent any shell commands from being run by a non-root process.

This parameter is generally not required except for some versions of OSX.

remote_checkpoint_dirs

Specifies what server checkpoint directories are remotely mounted. This directive is used to tell the MOM which directories are shared with the server. Using remote checkpoint directories eliminates the need to copy the checkpoint files back and forth between the MOM and the server. This parameter is available in 2.4.1 and later.

$remote_checkpoint_dirs /var/spool/torque/checkpoint

remote_reconfig

Enables the ability to remotely reconfigure pbs_mom with a new config file. Default is disabled. This parameter accepts various forms of true, yes, and 1.

source_login_batch

Specifies whether or not mom will source the /etc/profile, etc. type files for batch jobs. Parameter accepts various forms of true, false, yes, no, 1 and 0. Default is True.

source_login_interactive

Specifies whether or not mom will source the /etc/profile, etc. type files for interactive jobs. Parameter accepts various forms of true, false, yes, no, 1 and 0. Default is True.

spool_as_final_name

If set to true, jobs will spool directly as their output files, with no intermediate locations or steps. This is mostly useful for shared filesystems with fast writing capability.

status_update_time

Specifies (in seconds) how often MOM updates its status information to pbs_server. This value should correlate with the server's scheduling interval. High values increase the load of pbs_server and the network. Low values cause pbs_server to report stale information. Default is 45 seconds.

tmpdir

Sets the directory basename for a per-job temporary directory. Before job launch, MOM will append the jobid to the tmpdir basename and create the directory. After the job exit, MOM will recursively delete it. The env variable TMPDIR will be set for all pro/epilog scripts, the job script, and TM tasks.

Directory creation and removal is done as the job owner and group, so the owner must have write permission to create the directory. If the directory already exists and is owned by the job owner, it will not be deleted after the job. If the directory already exists and is NOT owned by the job owner, the job start will be rejected.

timeout

Specifies the number of seconds before TCP messages will time out. TCP messages include job obituaries, and TM requests if RPP is disabled. Default is 60 seconds.

usecp

specifies which directories should be staged with cp instead of rcp/scp. If a shared filesystem is available on all hosts in a cluster, this directive is used to make these filesystems known to MOM. For example, if /home is NFS mounted on all nodes in a cluster:

$usecp *:/home /home

varattr

This is similar to a shell escape above, but includes a TTL. The command will only be run every TTL seconds. A TTL of -1 will cause the command to be executed only once. A TTL of 0 will cause the command to be run everytime varattr is requested. This parameter may be used multiple times, but all output will be grouped into a single "varattr" attribute in the request and status output. The command should output data in the form of varattrname=va1ue1[+value2]...

$varattr 3600 /path/to/script [<ARGS>]...

use_smt

This option is only available, if pbs_mom is enabled to use cpusets. It has only effect, if there are more that one logical processor per physical core in the system (simultaneous multithreading or hyperthreading is enabled via BIOS settings). If set to true, all logical processors of allocated cores are added to the cpuset of a job. If set to false, only the first logical processor per allocated core is contained in the cpuset of a job. The default is true.

wallmult

which sets a factor used to adjust wall time usage by to job to a common reference system. The factor is used for walltime calculations and limits the same as cputmult is used for cpu time.

The configuration file must be executable and "secure". It must be owned by a user id and group id less than 10 and not be world writable. Output from this file must be in the format $VAR=$VAL, i.e.,

dataset13=20070104

dataset22=20070202

viraltest=abdd3

xauthpath

Specifies the path to the xauth binary to enable X11 fowarding.

mom_host

Sets the local hostname as used by pbs_mom.

## LAYOUT FILE
There is also an optional layout file for creating multiple moms on one box in a specified layout. In the file, each mom on the single box is given its own hostname, cpu indexes, memory nodes (a linux construct), and memory size. This is useful for NUMA systems. Each line in the file specifies one mom. The file follows the following format:

<hostname> cpus=<X> mem=<Y> memsize=<Z>

cpus and mem can be comma separated lists, while memsize should be a memory size in the format:

<number><units>

For example, a file could contain the following line:

foohost-1 cpus=1,2 mem=1,2,3,4 memsize=8GB

This would specify that foohost-1 has cpus 1 and 2, memory nodes 1-4, and a total of 8 GB of memory.

## RESOURCES
Resource Monitor queries can be made with momctl's -q option 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.

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 EXPERIMENTAL $down_on_error parameter

diag0 - diag4

retrieves various diagnostic information

rcpcmd

retrieve or set the $rcpcmd parameter

version

retrieves the pbs_mom version

## HEALTH CHECK
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, as of TORQUE 1.0.1, 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 keyword 'ERROR' to stdout followed by an error message. The message (up to 256 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. This should probably only be used with advanced schedulers like Moab so that the job can be routed to another node.

TORQUE currently ignores ERROR messages by default, but advanced schedulers like moab can be configured to react appropriately.

If the experimental $down_on_error MOM setting is enabled, MOM will set itself to state down and report to pbs_server; and pbs_server will report the node as "down". Additionally, the experimental "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. See "down_on_error" in pbs_server_attributes(7B).

## FILES
$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.

## SIGNAL HANDLING
pbs_mom handles the following signals:

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 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.

## EXIT STATUS
If the mini-server command fails to begin operation, the server exits with a value greater than zero.

## SEE ALSO
pbs_server(8B), pbs_scheduler_basl(8B), pbs_scheduler_tcl(8B), the PBS External Reference Specification, and the PBS Administrator's Guide.


package: torque-sched

title: pbs_sched_basl(8)

summary: pbs BASL scheduler

text:
# pbs_sched_basl(8)

## NAME
pbs_sched_basl - pbs BASL scheduler

## SYNOPSIS
pbs_sched [-d home] [-L logfile] [-p print_file] [-a alarm] [-S port] [-c configfile]

## DESCRIPTION
The pbs_sched command starts the operation of a batch scheduler on the local host. It runs in conjunction with the PBS server. It queries the server about the state of PBS and communicates with pbs_mom to get information about the status of running jobs, memory available etc. It then makes decisions as to what jobs to run.

Typically, this command will be in a local boot file such as /etc/rc.local .

pbs_sched must be executed with root permission.

## OPTIONS
-d home

Specifies the name of the PBS home directory, PBS_HOME. If not specified, the value of $PBS_SERVER_HOME as defined at compile time is used. Also see the -L option.

-L logfile

Specifies an absolute path name of the file to use as the log file. If not specified, the scheduler will open a file named for the current date in the PBS_HOME/sched_logs directory. See the -d option.

-p print_file

This specifies the "print" file. Any output from the scheduler code which is written to standard out or standard error will be written to this file. If this option is not given, the file used will be $PBS_HOME/sched_priv/sched_out. See the -d option.

-a alarm

This specifies the time in seconds to wait for a schedule run to finish. If a scheduling iteration takes too long to finish, an alarm signal is sent, and the scheduler is restarted. If a core file does not exist in the current directory, abort() is called and a core file is generated. The default for alarm is 180 seconds.

-S port

Specifies a port on which to talk to the server. This option is not required. It merely overides the default PBS scheduler port.

-c configfile

Specify a configuration file, see description below. If this is a relative file name it will be relative to PBS_HOME/sched_priv, see the -d option. If the -c option is not supplied, pbs_sched will not attempt to open a configuration file. In BASL, this config file is almost always needed because it is where the list of servers, nodes, and host resource queries are specified by the administrator.

## USAGE
This version of the scheduler requires knowledge of the BASL language. The site must first write a function called sched_main() (and all functions supporting it) using BASL constructs, and then translate the functions into C using the BASL compiler basl2c , which would also attach a main program to the resulting code. This main program performs general initialization and housekeeping chores such as setting up local socket to communicate with the server running on the same machine, cd-ing to the priv directory, opening log files, opening configuration file (if any), setting up locks, forking the child to become a daemon, initializing a scheduling cycle (i.e. get node attributes that are static in nature), setting up the signal handlers, executing global initialization assignment statements specified by the scheduler writer, and finally sitting on a loop waiting for a scheduling command from the server. When the server sends the scheduler an appropriate scheduling command {SCH_SCHEDULE_NEW, SCH_SCHEDULE_TERM, SCH_SCHEDULE_TIME, SCH_SCHEDULE_RECYC, SCH_SCHEDULE_CMD, SCH_SCHEDULE_FIRST}, information about server(s), jobs, queues, and execution host(s) are obtained, and then sched_main() is called.

## SCHEDULING LANGUAGE
The BAtch Scheduling Language (BASL) is a C-like procedural language. It provides a number of constructs and predefined functions that facilitate dealing with scheduling issues. Information about a PBS server, the queues that it owns, jobs residing on each queue, and the computational nodes where jobs can be run, are accessed via the BASL data types Server, Que, Job, CNode, Set Server, Set Que, Set Job, and Set CNode.

The following simple sched_main() will cause the server to run all queued jobs on the local server:

```
sched_main()
{

        Server  s;

        Que     q;

        Job     j;

        Set Que queues;

        Set Job jobs;

        s = AllServersLocalHostGet(); // get local server

        queues = ServerQueuesGet(s);

        foreach( q in queues ) {

                jobs = QueJobsGet(q);

                foreach( j in jobs ) {

                         JobAction(j, SYNCRUN, NULLSTR);

                }

        }

}
```

For a more complete discussion of the Batch Scheduler Language, see basl2c(1B) .

## CONFIGURATION FILE
A configuration file may be specified with the -c option. This file is used to specify the (1) hosts which are allowed to connect to pbs_sched, (2) the list of server hosts for which the scheduler writer wishes the system to periodically check for status, queues, and jobs info, (3) list of execution hosts for which the scheduler writer wants the system to periodically check for information like state, property, and so on, and (4) various queries to send to each execution host.

(1) specifying client hosts:

The hosts allowed to connect to pbs_sched are specified in the configuration file in a manner identical to that used in pbs_mom. There is one line per host using the syntax: $clienthost hostname

where clienthost and hostname are separated by white space. Two host names are always allowed to connection to pbs_sched: "localhost" and the name returned to pbs_sched by the system call gethostname(). These names need not be specified in the configuration file.

(2) specifying list of servers:

The list of servers is specified in a one host per line manner, using the syntax: $serverhost hostname port_number

or where $server_host, hostname, and port_number are separated by white space.

If port_number is 0, then the default PBS server port will be used.

Regardless of what has been specified in the file, the list of servers will always include the local server - one running on the same host where the scheduler is running.

Within the BASL code, access to data of the list of servers is done by calling AllServersGet(), or AllServersLocalHostGet() which returns the local server on the list.

(3) specifying the list of execution hosts:

The list of execution hosts (nodes), whose MOMs are to be queried from the scheduler, is specified in a one host per line manner, using the syntax: $momhost hostname port_number

where $momhost, hostname, and port_number are separated by white space.

If port_number is 0, then the default PBS MOM port will be used.

The BASL function AllNodesGet() , or ServerNodesGet(AllServersLocalHostGet()) is available for getting the list of nodes known to the local system.

(4) specifying the list of host resources:

For specifying the list of host resource queries to send to each execution host's MOM, the following syntax is used: $node node_name CNode..Get host_resource

node_name should be the same hostname string that was specified in a $momhost line. A node_name value of "*" (wildcard) means to match any node.

Please consult section 9 of the PBS ERS (Resource Monitor/Resources) for a list of possible values to host_resource parameter.

CNode..Get refers to the actual function name that is called from the scheduler code to obtain the return values to host resource queries. The list of CNode..Get function names that can appear in the configuration file are: .BP

```
    STATIC:

    ================================

    CNodePropertiesGet

    CNodeVendorGet

    CNodeNumCpusGet

    CNodeOsGet

    CNodeMemTotalGet[type]

    CNodeNetworkBwGet[type]

    CNodeSwapSpaceTotalGet[name]

    CNodeDiskSpaceTotalGet[name]

    CNodeDiskInBwGet[name]

    CNodeDiskOutBwGet[name]

    CNodeTapeSpaceTotalGet[name]

    CNodeTapeInBwGet[name]

    CNodeTapeOutBwGet[name]

    CNodeSrfsSpaceTotalGet[name]

    CNodeSrfsInBwGet[name]

    CNodeSrfsOutBwGet[name]

    DYNAMIC:

    ================================

    CNodeIdletimeGet

    CNodeLoadAveGet

    CNodeMemAvailGet[type]

    CNodeSwapSpaceAvailGet[name]

    CNodeSwapInBwGet[name]

    CNodeSwapOutBwGet[name]

    CNodeDiskSpaceReservedGet[name]

    CNodeDiskSpaceAvailGet[name]

    CNodeTapeSpaceAvailGet[name]

    CNodeSrfsSpaceReservedGet[name]

    CNodeSrfsSpaceAvailGet[name]

    CNodeCpuPercentIdleGet

    CNodeCpuPercentSysGet

    CNodeCpuPercentUserGet

    CNodeCpuPercentGuestGet
```

STATIC function names return values that are obtained only during the first scheduling cycle, or when the scheduler is instructed to reconfig; whereas, DYNAMIC function names return attribute values that are taken at every subsequent scheduling cycle.

name and type are arbitrarily defined. For example, you can choose to have name defined as "$FASTDIR" for the CNodeSrfs* calls, and a sample configuration file entry would look like:

```
   $node unicos8 CNodeSrfsSpaceAvailGet[$FASTDIR]

                               quota[type=ares_avail,dir=$FASTDIR]
```

So in a BASL code, if you call CNodeSrfsSpaceAvailGet(node, "$FASTDIR"), then it will return the value to the query "quota[type=ares_avail,dir=$FASTDIR]" (3rd parameter) as sent to the node's MOM.

By default, the scheduler has already internally defined the following mappings, which can be overriden in the configuration file:

```
keyword  node_name   CNode..Get        host_resource
=======  =========   ================  =============
$node    *           CNodeOsGet        arch
$node    *           CNodeLoadAveGet   loadave
$node    *           CNodeIdletimeGet  idletime
```

The above means that for all declared nodes (via $momhost), the host queries arch, loadave, and idletime will be sent to each node's MOM. The value to arch is obtained internally by the system during the first scheduling cycle because it falls under STATIC category, while values to loadave and idletime are taken at every scheduling iteration because they fall under the DYNAMIC category. Access to the return values is done by calling CNodeOsGet(node), CNodeLoadAveGet(node), and CNodeIdletimeGet(node), respectively. The following are some sample $node arguments that you may put in the configuration file. .BP

```
node_name           CNode..Get                       host res
==================  =========================        ==========
<sunos4_nodename>   CNodeIdletimeGet                 idletime
<sunos4_nodename>   CNodeLoadAveGet                  loadave
<sunos4_nodename>   CNodeMemTotalGet[real]           physmem
<sunos4_nodename>   CNodeMemTotalGet[virtual]        totmem
<sunos4_nodename>   CNodeMemAvailGet[virtual]        availmem
<irix5_nodename>    CNodeNumCpusGet                  ncpus
<irix5_nodename>    CNodeMemTotalGet[real]           physmem
<irix5_nodename>    CNodeMemTotalGet[virtual]        totmem
<irix5_nodename>    CNodeIdletimeGet                 idletime
<irix5_nodename>    CNodeLoadAveGet                  loadave
<irix5_nodename>    CNodeMemAvailGet[virtual]        availmem
<linux_nodename>    CNodeNumCpusGet                  ncpus
<linux_nodename>    CNodeMemTotalGet[real]           physmem
<linux_nodename>    CNodeMemTotalGet[virtual]        totmem
<linux_nodename>    CNodeIdletimeGet                 idletime
<linux_nodename>    CNodeLoadAveGet                  loadave
<linux_nodename>    CNodeMemAvailGet[virtual]        availmem
<solaris5_nodename> CNodeIdletimeGet                 idletime
<solaris5_nodename> CNodeLoadAveGet                  loadave
<solaris5_nodename> CNodeNumCpusGet                  ncpus
<solaris5_nodename> CNodeMemTotalGet[real]           physmem
<aix4_nodename>     CNodeIdletimeGet                 idletime
<aix4_nodename>     CNodeLoadAveGet                  loadave
<aix4_nodename>     CNodeMemTotalGet[virtual]        totmem
<aix4_nodename>     CNodeMemAvailGet[virtual]        availmem
<unicos8_nodename>  CNodeIdletimeGet                 idletime
<unicos8_nodename>  CNodeLoadAveGet                  loadave
<unicos8_nodename>  CNodeNumCpusGet                  ncpus
<unicos8_nodename>  CNodeMemTotalGet[real]           physme
<unicos8_nodename>  CNodeMemAvailGet[virtual]        availmem
<unicos8_nodename>  CNodeSwapSpaceTotalGet[primary]  swaptotal
<unicos8_nodename>  CNodeSwapSpaceAvailGet[primary]  swapavail
<unicos8_nodename>  CNodeSwapInBwGet[primary]        swapinrate
<unicos8_nodename>  CNodeSwapOutBwGet[primary]       swapoutrate
<unicos8_nodename>  CNodePercentIdleGet              cpuidle
<unicos8_nodename>  CNodePercentSysGet               cpuunix
<unicos8_nodename>  CNodePercentGuestGet             cpuguest
<unicos8_nodename>  CNodePercentUsrGet               cpuuser
<unicos8_nodename>  CNodeSrfsSpaceAvailGet[$FASTDIR] quota[type

                                                   =ares_avail,

                                                   dir=$FASTDIR]
<unicos8_nodename>  CNodeSrfsSpaceAvailGet[$BIGDIR]  quota[type

                                                   =ares_avail,

                                                   dir=$BIGDIR]
<unicos8_nodename>  CNodeSrfsSpaceAvailGet[$WRKDIR]  quota[type

                                                   =ares_avail,

                                                   dir=$WRKDIR]
<sp2_nodename>      CNodeLoadAveGet                  loadave
```

Suppose you have an execution host that is of irix5 os type, then the <irix5_node_name> entries will be consulted by the scheduler. The initial scheduling cycle would involve sending the STATIC queries ncpus, physmem, totmem to the execution host's MOM, and access to return values of the queries is done via CNodeNumCpusGet(node), CNodeMemTotalGet(node, "real"), CNodeMemTotalGet(node, "virtual") respectively, where node is the CNode representation of the execution host. The subsequent scheduling cycles will only send DYNAMIC queries idletime, loadave, and availmem, and access to the return values of the queries is done via CNodeIdleTimeGet(node), CNodeLoadAveGet(node), CNodeMemAvailGet(node, "virtual"). respectively.

"Later" entries in the config file take precedence.

The configuration file must be "secure". It must be owned by a user id and group id less than 10 and not be world writable.

On receipt of a SIGHUP signal, the scheduler will close and reopen its log file and reread its configuration file (if any).

## FILES
$PBS_SERVER_HOME/sched_priv

the default directory for configuration files, typically (/usr/spool/pbs)/sched_priv.

## Signal Handling
A C based scheduler will handle the following signals:

SIGHUP

The server will close and reopen its log file and reread the config file if one exists.

SIGALRM

If the site supplied scheduling module exceeds the time limit, the Alarm will cause the scheduler to attempt to core dump and restart itself.

SIGINT and SIGTERM

Will result in an orderly shutdown of the scheduler.

All other signals have the default action installed.

## EXIT STATUS
Upon normal termination, an exit status of zero is returned.

## SEE ALSO
basl2c(1B), pbs_sched_tcl(8B), pbs_server(8B), and pbs_mom(8B).

PBS Internal Design Specification


title: pbs_sched_cc(8)

summary: pbs C scheduler

text:
# pbs_sched_cc(8)

## NAME
pbs_sched_cc - pbs C scheduler

## SYNOPSIS
pbs_sched [-a alarm] [-d home] [-L logfile] [-p file] [-S port] [-R port] [-c file]

## DESCRIPTION
The pbs_sched program runs in conjunction with the PBS server. It queries the server about the state of PBS and communicates with pbs_resmon to get information about the status of running jobs, memory available etc. It then makes decisions as to what jobs to run.

pbs_sched must be executed with root permission.

## OPTIONS
-a alarm

This specifies the time in seconds to wait for a schedule run to finish. If a script takes too long to finish, an alarm signal is sent, and the scheduler is restarted. If a core file does not exist in the current directory, abort() is called and a core file is generated. The default for alarm is 180 seconds.

-d home

This specifies the PBS home directory, PBS_HOME. The current working directory of the scheduler is PBS_HOME/sched_priv. If this option is not given, PBS_HOME defaults to $PBS_SERVER_HOME as defined during the PBS build procedure.

-L logfile

Specifies an absolute path name of the file to use as the log file. If not specified, the scheduler will open a file named for the current date in the PBS_HOME/sched_logs directory (see the -d option).

-p file

This specifies the "print" file. Any output from the C code which is written to standard out or standard error will be written to this file. If this option is not given, the file used will be PBS_HOME/sched_priv/sched_out . See the -d option.

-S port

This specifies the port to use. If this option is not given, the default port for the PBS scheduler is used.

-R port

This specifies the resource monitor port to use. If this option is not given, the default port for the PBS mom is used. NOTE: this option only makes the mom port available to the scheduler writer. It doesn't force them to use it.

-c file

Specify a configuration file, see description below. If this is a relative file name it will be relative to PBS_HOME/sched_priv, see the -d option. If the -c option is not supplied, pbs_sched will not attempt to open a configuration file.

The options that specify file names may be absolute or relative. If they are relative, their root directory will be PBS_HOME/sched_priv.

## USAGE
This version of the scheduler requires knowledge of the C language and the PBS API. Source code is provided for a main program for the scheduler. The site must supply the heart of the program. When invoked, the main program performs general initialization and housekeeping chores. Then a locally supplied function, schedinit() is called to perform site specific initialization.

In the main loop, a locally supplied function, schedule() is called to make the scheduling decisions and perform any required actions. Information about jobs and queues is obtained from the Server through the standard PBS API as found in libifl.a. Information about the execution host(s) is obtained from the Resource Monitor. Routines to communicate with the Resource Monitor are found in libnet.a.

If the processing takes more than the allotted time, the scheduler will restart itself. The default amount of time is three minutes. This can be changed with the -a option.

On receipt of a SIGHUP signal, the scheduler will close and reopen its log file and reread its configuration file (if any).

## CONFIGURATION FILE
A configuration file may be specified with the -c option. This file may be used to specify the hosts (servers) which are allowed to connect to pbs_sched. The hosts are specified in the configuration file in a manor identical to that used in pbs_mom.

clienthost

One or more servers, one per line, may be specified:

$clienthost hostname +.IP restricted Allows connections from non-priviledged ports on the named hosts. Typically only used with Mac OSX:

$restricted hostname

Two host names are always allowed to connection to pbs_sched, "localhost" and the name returned to pbs_sched by the system call gethostname(). These names need not be specified in the configuration file.

The configuration file must be "secure". It must be owned by a user id and group id less than 10 and not be world writable.

## FILES
$PBS_SERVER_HOME/sched_priv

the default directory for configuration files, typically (/usr/spool/pbs)/sched_priv.

## Signal Handling
A C based scheduler will handle the following signals:

SIGHUP

The server will close and reopen its log file and reread the config file if one exists.

SIGALRM

If the site supplied scheduling module exceeds the time limit, the Alarm will cause the scheduler to attempt to core dump and restart itself.

SIGINT and SIGTERM

Will result in an orderly shutdown of the scheduler.

All other signals have the default action installed.

## EXIT STATUS
Upon normal termination, an exit status of zero is returned.

## SEE ALSO
pbs_sched_tcl(8B), pbs_server(8B), and pbs_mom(8B).

PBS Internal Design Specification


title: pbs_sched_tcl(8)

summary: pbs Tcl scheduler

text:
# pbs_sched_tcl(8)

## NAME
pbs_sched_tcl - pbs Tcl scheduler

## SYNOPSIS
pbs_sched [-a alarm] [-b file] [-d home] [-i file] [-L logfile] [-p file] [-S port] [-t file] [-v] [-c file]

## DESCRIPTION
The pbs_sched program runs in conjunction with the PBS server. It queries the server about the state of PBS and communicates with pbs_mom to get information about the status of running jobs, memory available etc. It then makes decisions as to what jobs to run.

pbs_sched must be executed with root permission.

## OPTIONS
-a alarm

This specifies the time in seconds to wait for a schedule run to finish. If a script takes too long to finish, an alarm signal is sent, and the scheduler is restarted. If a core file does not exist in the current directory, abort() is called and a core file is generated. The default for alarm is 180 seconds.

-b file

This specifies the "body" file. The file given is read into memory once at program start or after the program receives a SIGHUP and executed each time the scheduler is awakened by the server. If this option is not given, the file "sched_tcl" in the directory PBS_HOME/sched_priv is read for the body code.

-d home

This specifies the PBS home directory, PBS_HOME. The current working directory of the scheduler is PBS_HOME/sched_priv. If this option is not given, PBS_HOME defaults to $PBS_SERVER_HOME as defined during the PBS build procedure.

-i file

This specifies the "initialize" file. The file given is executed once before the main processing loop is entered. If this option is not given, no initialization code is executed.

-L logfile

Specifies an absolute path name of the file to use as the log file. If not specified, the scheduler will open a file named for the current date in the PBS_HOME/sched_logs directory (see the -d option).

-p file

This specifies the "print" file. Any output from the Tcl code which is written to standard out or standard error will be written to this file. If this option is not given, the file used will be PBS_HOME/sched_priv/sched_out. See the -d option.

-S port

This specifies the port to use. If this option is not given, the default port for the PBS scheduler is used.

-t file

This specifies the "terminator" file. If a QUIT command is sent from the server, this code is executed before the scheduler exits. If this option is not given, no special termination handling is done.

-v

This puts the scheduler into "verbose" mode. Any errors will be shown no matter what this may be set to, but some "uninteresting" events may be logged by using this flag. An example is a message each time the server contacts the scheduler.

-c file

Specify a configuration file, see description below. If this is a relative file name it will be relative to PBS_HOME/sched_priv, see the -d option. If the -c option is not supplied, pbs_sched will not attempt to open a configuration file.

The options that specify file names may be absolute or relative. If they are relative, their root directory will be PBS_HOME/sched_priv.

## USAGE
This version of the scheduler requires knowledge of the Tcl language. A set of functions to communicate with the PBS server and resource monitor have been added to those normally available with Tcl. All these calls will set the Tcl variable "pbs_errno" to a value to indicate if an error occured. In all cases, the value "0" means no error. If a call to a Resource Monitor function is made, any error value will come from the system supplied errno variable. If the function call communicates with the PBS Server, any error value will come from the error number returned by the server.

openrm host ?port?

Creates a connection to the PBS Resource Monitor on host using port as the port number or the standard port for the resource monitor if it is not given. A connection handle is returned. If the open is successful, this will be a non-negative integer. If not, an error occurred.

closerm connection

The parameter connection is a handle to a resource monitor which was previously returned from openrm. This connection is closed. Nothing is returned.

downrm connection

Sends a command to the connected resource monitor to shutdown. Nothing is returned.

configrm connection filename

Sends a command to the connected resource monitor to read the configuration file given by filename. If this is successful, a "0" is returned, otherwise, "-1" is returned.

addreq connection request

A resource request is sent to the connected resource monitor. If this is successful, a "0" is returned, otherwise, "-1" is returned.

getreq connection

One resource request response from the connected resource monitor is returned. If an error occurred or there are no more responses, an empty string is returned.

allreq request

A resource request is sent to all connected resource monitors. The number of streams acted upon is returned.

flushreq

All resource requests previously sent to all connected resource monitors are flushed out to the network. Nothing is returned.

activereq

The connection number of the next stream with something to read is returned. If there is nothing to read from any of the connections, a negative number is returned.

fullresp flag

Evaluates flag as a boolean value and sets the response mode used by getreq to full if flag evaluates to "true". The full return from a resource monitor includes the original request followed by an equal sign followed by the response. The default situation is only to return the response following the equal sign. If a script needs to "see" the entire line, this function may be used.

pbsstatserv

The server is sent a status request for information about the server itself. If the request succeeds, a list with three elements is returned, otherwise an empty string is returned. The first element is the server's name. The second is a list of attributes. The third is the "text" associated with the server (usually blank).

pbsstatjob

The server is sent a status request for information about the all jobs resident within the server. If the request succeeds, a list is returned, otherwise an empty string is returned. The list contains an entry for each job. Each element is a list with three elements. The first is the job's jobid. The second is a list of attributes. The attribute names which specify resources will have a name of the form "Resource_List:name" where "name" is the resource name. The third is the "text" associated with the job (usually blank).

pbsstatque

The server is sent a status request for information about all queues resident within the server. If the request succeeds, a list is returned, otherwise an empty string is returned. The list contains an entry for each queue. Each element is a list with three elements. This first is the queue's name. The second is a list of attributes similar to pbsstatjob. The third is the "text" associated with the queue (usually blank).

pbsstatnode

The server is sent a status request for information about all nodes defined within the server. If the request succeeds, a list is returned, otherwise an empty string is returned. The list contains an entry for each node. Each element is a list with three elements. This first is the nodes's name. The second is a list of attributes similar to pbsstatjob. The third is the "text" associated with the node (usually blank).

pbsselstat

The server is sent a status request for information about the all runnable jobs resident within the server. If the request succeeds, a list similar to pbsstatjob is returned, otherwise an empty string is returned.

pbsrunjob jobid ?location?

Run the job given by jobid at the location given by location. If location is not given, the default location is used. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsasyrunjob jobid ?location?

Run the job given by jobid at the location given by location without waiting for a positive response that the job has actually started. If location is not given, the default location is used. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsrerunjob jobid

Re-runs the job given by jobid. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsdeljob jobid

Delete the job given by jobid. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsholdjob jobid

Place a hold on the job given by jobid. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsmovejob jobid ?location?

Move the job given by jobid to the location given by location. If location is not given, the default location is used. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsqenable queue

Set the "enabled" attribute for the queue given by queue to true. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsqdisable queue

Set the "enabled" attribute for the queue given by queue to false. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsqstart queue

Set the "started" attribute for the queue given by queue to true. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsqstop queue

Set the "started" attribute for the queue given by queue to false. If this is successful, a "0" is returned, otherwise, "-1" is returned.

pbsalterjob jobid attribute_list

Alter the attributes for a job specified by jobid. The parameter attribute_list is the list of attributes to be altered. There can be more than one. Each attribute consists of a list of three elements. The first is the name, the second the resource and the third is the new value. If the alter is successful, a "0" is returned, otherwise, "-1" is returned.

pbsrescquery resource_list

Obtain information about the resources specified by resource_list. This will be a list of strings. If the request succeeds, a list with the same number of elements as resource_list is returned. Each element in this list will be a list with four numbers. The numbers specify available, allocated, reserved, and down in that order.

pbsrescreserve resource_id resource_list

Make (or extend) a reservation for the resources specified by resource_list which will be given as a list of strings. The parameter resource_id is a number which provides a unique identifier for a reservation being tracked by the server. If resource_id is given as "0", a new reservation is created. In this case, a new identifier is generated and returned by the function. If an old identifier is used, that same number will be returned. The Tcl variable "pbs_errno" will be set to indicate the success or failure of the reservation.

pbsrescrelease resource_id

The reservation specified by resource_id is released.

The two following commands are not normally used by the scheduler. They are included here because there could be a need for a scheduler to contact a server other than the one which it normally communicates with. Also, these commands are used by the Tcl tools.

pbsconnect ?server?

Make a connection to the named server or the default server if a parameter is not given. Only one connection to a server is allowed at any one time.

pbsdisconnect

Disconnect from the currently connected server.

The above Tcl functions use PBS interface library calls for communication with the server and the PBS resource monitor library to communicate with pbs_mom.

datetime ?day? ?time?

The number of arguments used determine the type of date to be calculated. With no arguments, the current POSIX date is returned. This is an integer in seconds. With one argument there are two possible formats. The first is a 12 (or more) character string specifying a complete date in the following format:

```
YYMMDDhhmmss

```

All characters must be digits. The year (YY) is given by the first two (or more) characters and is the number of years since 1900. The month (MM) is the number of the month [01-12]. The day (DD) is the day of the month [01-32]. The hour (hh) is the hour of the day [00-23]. The minute (mm) is minutes after the hour [00-59]. The second (ss) is seconds after the minute [00-59]. The POSIX date for the given date/time is returned. The second option with one argument is a relative time. The format for this is

```
HH:MM:SS

```

With hours (HH), minutes (MM) and seconds (SS) being separated by colons ":". The number returned in this case will be the number of seconds in the interval specified, not an absolute POSIX date. With two arguments a relative date is calculated. The first argument specifies a day of the week and must be one of the following strings: "Sun", "Mon", "Tue", "Wed", "Thr", "Fri", or "Sat". The second argument is a relative time as given above. The POSIX date calculated will be the day of the week given which follows the current day, and the time given in the second argument. For example, if the current day was Monday, and the two arguments were "Fri" and "04:30:00", the date calculated would be the POSIX date for the Friday following the current Monday, at four-thirty in the morning. If the day specified and the current day are the same, the current day is used, not the day one week later.

strftime format time

This function calls the POSIX function strftime(). It requires two arguments. The first is a format string. The format conventions are the same as those for the POSIX function strftime(). The second argument is POSIX calendar time in second as returned by datetime. It returns a string based on the format given. This gives the ability to extract information about a time, or format it for printing.

The Tcl interpreter is started at program initialization and after a reset (the receipt of a SIGHUP signal). It is not deleted between scheduling runs so variables which are set in one can be accessed later.

The "initialize" and "terminator" files are run with no supplied connection to the server. This means that none of the above functions which talk to the server will work unless pbsconnect is called first. The "body" file is run with a connection to the server already established.

## CONFIGURATION FILE
A configuration file may be specified with the -c option. This file may be used to specify the hosts (servers) which are allowed to connect to pbs_sched. The hosts are specified in the configuration file in a manor identical to that used in pbs_mom. There is one line per host with the syntax:

$clienthost hostname

where clienthost and hostname are separated by white space.

Two host names are always allowed to connection to pbs_sched, "localhost" and the name returned to pbs_sched by the system call gethostname(). These names need not be specified in the configuration file.

The configuration file must be "secure". It must be owned by a user id and group id less than 10 and not be world writable.

## FILES
$PBS_SERVER_HOME/sched_priv

the default directory for configuration files, typically (/usr/spool/pbs)/sched_priv.

## Signal Handling
A C based scheduler will handle the following signals:

SIGHUP

The server will close and reopen its log file and reread the config file if one exists.

SIGALRM

If the site supplied scheduling module exceeds the time limit, the Alarm will cause the scheduler to attempt to core dump and restart itself.

SIGINT and SIGTERM

Will result in an orderly shutdown of the scheduler.

All other signals have the default action installed.

## EXIT STATUS
Upon normal termination, an exit status of zero is returned.

## SEE ALSO
pbs_scheduler_cc(8B), pbs_scheduler_rule(8B), pbs_server(8B), and pbs_mom(8B).

PBS Internal Design Specification


package: torque-server

title: pbs_server(8)

summary: start a pbs batch server

text:
# pbs_server(8)

## NAME
pbs_server - start a pbs batch server

## SYNOPSIS
pbs_server [-a active] [-c] [-d config_path] [-e] [-F] [-f] [-h] [-l location] [-p port] [-t type] [-v] [-A acctfile] [-D] [-H hostname] [-L logfile] [-M mom_port] [-n don't send hierarchy] [-R momRPP_port] [-S scheduler_port] [--about] [--ha] [--help] [--version]

## DESCRIPTION
The pbs_server command starts the operation of a batch server on the local host. Typically, this command will be in a local boot file such as /etc/rc.local . If the batch server is already in execution, pbs_server will exit with an error. To insure that the pbs_server command is not runnable by the general user community, the server will only execute if its real and effective uid is zero.

The server will record a diagnostic message in a log file for any error occurrence. The log files are maintained in the server_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.

## OPTIONS
-a active

Specifies if scheduling is active or not. This sets the server attribute scheduling. If the option argument is "true" ("True", "t", "T", or "1"), the server is active and the PBS job scheduler will be called. If the argument is "false" ("False", "f", "F", or "0), the server is idle, and the scheduler will not be called and no jobs will be run. If this option is not specified, the server will retain the prior value of the scheduling attribute.

-c

Wait 10 minutes before contacting moms. Any mom reporting in does not get pinged if starting pbs_server before moms.

-d config_path

Specifies the path of the directory which is home to the servers configuration files, PBS_HOME. A host may have multiple servers. Each server must have a different configuration directory. The default configuration directory is given by the symbol $PBS_SERVER_HOME which is typically /usr/spool/PBS.

-e

Accept status update from any mom. Adds node to nodes file.

-F

Do not fork. Use when running under systemd.

-f

Force overwrite of server database.

-h

Print help information.

-l location

Specifies where to find the scheduler (for example, Moab) when it does not reside on the same host as Torque. Example: pbs_server -1 <other_host>:<other_port>

-p port

Specifies the port number on which the server will listen for batch requests. If multiple servers are running on a single host, each must have its own unique port number. This option is for use in testing with multiple batch systems on a single host.

-t type

If the job is rerunnable or restartable, and -t create is specified, the server will discard any existing configuration files, queues, and jobs, and initialize configuration files to the default values. The server is idled. If -t is not specified, job states will remain the same.

-v

Shows version.

-A acctfile

Specifies an absolute path name of the file to use as the accounting file. If not specified, the file is named for the current date in the PBS_HOME/server_priv/accounting directory.

-D

Debug mode. Do not fork.

-H hostname

Causes the server to start under a different hostname as obtained from gethostname(2). Useful for servers with multiple network interfaces to support connections from clients over an interface that has a hostname assigned that differs from the one that is returned by gethostname(2).

-L logfile

Specifies an absolute path name of the file to use as the log file. If not specified, the file is one named for the current date in the PBS_HOME/server_logs directory, see the -d option.

-M mom_port

Specifies the host name and/or port number on which the server should connect the job executor, MOM. The option argument, mom_conn, is one of the forms: host_name, [:]port_number, or host_name:port_number. If host_name not specified, the local host is assumed. If port_number is not specified, the default port is assumed. See the -M option for pbs_mom(8).

-n don't send heirarchy

Directs pbs_server to not send the hierarchy to all the MOMs on startup. Instead, the hierarchy is only sent if a MOM requests it. This flag works only in conjunction with the local MOM hierarchy feature.

-R mom_RPPport

Specifies the port number on which the the server should query the up/down status of Mom. See the -R option for pbs_mom(8).

-S scheduler_port

Specifies the port number to which the server should connect when contacting the Scheduler. By default pbs_server looks for the scheduler on the loopback address at port 15004. The -S option changes the default to the value given in the option argument. The option argument, scheduler_conn, is of the same syntax as under the -M option.

--about

Shows information about pbs_server.

--ha

Enables high availability mode.

--help

Prints help information.

--version

Shows version and commit information.

## FILES
$PBS_SERVER_HOME/server_priv

default directory for configuration files, typically /usr/spool/pbs/server_priv

$PBS_SERVER_HOME/server_logs

directory for log files recorded by the server.

## Signal Handling
On receipt of the following signals, the server performs the defined action:

SIGHUP

The current server log and accounting log are closed and reopened. This allows for the prior log to be renamed and a new log started from the time of the signal.

SIGINT

Causes an orderly shutdown of pbs_server.

SIGUSR1, SIGUSR2

Causes server to increase and decrease logging levels, respectively.

SIGTERM

Causes an orderly shutdown of pbs_server.

SIGSHUTDN

On systems (Unicos) where SIGSHUTDN is defined, it also causes an orderly shutdown of the server.

SIGPIPE

This signal is ignored.

All other signals have their default behavior installed.

## EXIT STATUS
If the server command fails to begin batch operation, the server exits with a value greater than zero.

## SEE ALSO
qsub (1B), pbs_connect(3B), pbs_mom(8B), pbs_sched_basl(8B), pbs_sched_tcl(8B), pbsnodes(8B), qdisable(8B), qenable(8B), qmgr(1B), qrun(8B), qstart(8B), qstop(8B), qterm(8B), and the PBS External Reference Specification.


torsocks

package: torsocks

title: torsocks(8)

text:
# torsocks(8)

## NAME
torsocks — Library for intercepting outgoing network connections and redirecting them through the Tor SOCKS proxy.

## DESCRIPTION
Torsocks library overloads the libc symbols use for Internet communication such as connect(2) system call. Using that technique, the library sends everything through the Tor network including DNS resolution done by the application.

For DNS, gethostbyname(3) family functions are rerouted through Tor. Please note that the ISC res_* API is currently not supported.

Here is an example on how to use torsocks library with ssh(1):

$ LD_PRELOAD=/path/to/libtorsocks.so ssh -l kalexander -p 1234 prism.nsa.gov [...]

## SHELL USAGE
Set LD_PRELOAD to load the library then use applications as normal. The syntax to force preload of the library for different shells is specified below:

Bash, Ksh and Bourne shell:

$ export LD_PRELOAD=/path/to/libtorsocks.so

C Shell:

$ setenv LD_PRELOAD=/path/to/libtorsocks.so

This process can be automated (for Bash, Bourne and Korn shell users) for a single command or for all commands in a shell session by using the torsocks(1) script.

You can also setup torsocks(1) in such a way that all processes automatically use it, a very useful configuration. Please refer to the torsocks script documentation for more information.

## ENVIRONMENT VARIABLES
TORSOCKS_CONF_FILE

This environment variable overrides the default location of the torsocks configuration file. This variable is not honored if the program torsocks is embedded in is setuid.

TORSOCKS_LOG_LEVEL

Enable logging level of torsocks library. By default, warnings and errors are printed (level 3). Note that each level includes the lower ones except the 1 which disables any possible logging. (default: 3)

1

No log at all.

2

Error messages.

3

Warning messages.

4

Notice messages.

5

Debug messages.

TORSOCKS_LOG_TIME

Control whether or not the time is added to each logging line. (default: 1)

TORSOCKS_LOG_FILE_PATH

If set, torsocks will log in the file set by this variable. (default: stderr)

TORSOCKS_USERNAME

Set the username for the SOCKS5 authentication method. Password MUST be set also with the variable below.

TORSOCKS_PASSWORD

Set the password for the SOCKS5 authentication method. Username MUST be set also with the variable above.

TORSOCKS_TOR_ADDRESS

Set the Tor address. (default: 127.0.0.1)

TORSOCKS_TOR_PORT

Set the Tor port. (default: 9050)

TORSOCKS_ALLOW_INBOUND

Allow inbound connections so the application can accept and listen for connections.

TORSOCKS_ISOLATE_PID

Set the username and password for the SOCKS5 authentication method to a PID/current time based value automatically. Username and Password MUST NOT be set.

## KNOWN ISSUES

### DNS
Torsocks is not able to send DNS queries through Tor since UDP is not supported. Thus, any UDP socket is denied. However, DNS queries that can be intercept are sent to Tor and sent back to the caller.

### ERRORS
Torsocks might generate error messages and print them to stderr when there are problems with the configuration file or the SOCKS negotiation with the Tor daemon. The TORSOCKS_LOG_LEVEL environment variable controls that behavior as well as the log file option. Keep in mind that this library can output on the stderr of the application.

## LIMITATIONS
Outgoing TCP connections can only be proxified through the Tor network.

Torsocks forces the libc resolver to use TCP for name queries, if it does this it does it regardless of whether or not the DNS to be queried is local or not. This introduces overhead and should only be used when needed.

Torsocks uses ELF dynamic loader features to intercept dynamic function calls from programs in which it is embedded. As a result, non-ELF executables, or executables that make system calls directly with the system call trap (int 0x80) are not supported.

## FILES
/etc/tor/torsocks.conf - default torsocks configuration file

## SEE ALSO
torsocks.conf(5), torsocks(1)

## AUTHOR
David Goulet <dgoulet@ev0ke.net>


title: tpm2-abrmd(8)

text:
# tpm2-abrmd(8)

## NAME
tpm2-abrmd - TPM2 access broker and resource management daemon

## SYNOPSIS
tpm2-abrmd [-m][-e][-i][-o][-l logger-name][-r][-s][-g /dev/urandom][-t conf]

## DESCRIPTION
tpm2-abrmd is a daemon that implements the TPM access broker and resource manager as described by the Trusted Computing Group (TGC) in the “TSS System Level API and TPM Command Transmission Interface Specification”. This daemon uses the DBus system bus and some pipes to communicate with clients.

## OPTIONS
-t, --tcti

Provide the daemon with a string that describes the TCTI and how to configure it for communication with the next component down the TSS2 stack. This string is formatted as "tcti-name:tcti-conf" where:

'tcti-name'

The name of the TCTI library shared object file. Libraries are found using the same algorithm as dlopen (3). If the TCTI library file name follows the naming convention: libtss2-tcti-<name>.so.0 where <name> is the name for the TCTI, the value of <name> may be supplied in place of the full library file name. See 'EXAMPLES' below.

'tcti-conf'

The configuration string passed to the TCTI library upon initialization.

If this option is omitted (or a NULL string provided) then a default TCTI is used in it's default configuration. If the string does not contain a colon then it will be interpreted as only the 'tcti-name'. To provide only the configuration string (using the default TCTI) then the first character in the string passed to this option must be a colon followed by the configuration string. See examples below.

-o, --allow-root

Allow daemon to run as root. If this option is not provided the daemon will refused to run as the root user. Use of this option is not recommended.

-m, --max-connections

Set an upper bound on the number of concurrent client connections allowed. Once this number of client connections is reached new connections will be rejected with an error. If the option is not specified the default is 27.

-f, --flush-all

Flush all objects and sessions when daemon is started.

-l, --logger

Direct logging output to named logging target. Supported targets are stdout and syslog. If the logger option is not specified the default is stdout.

-e, --max-sessions

Set and upper bound on the number of sessions that each client connection is allowed to create (loaded or active) at any one time. If the option is not specified the default is 4.

-r, --max-transients

Set an upper bound on the number of transient objects that each client connection allowed to load. Once this number of objects is reached attempts to load new transient objects will produce an error. If the option is not specified the default is 27.

-n, --dbus-name

Claim the given name on dbus. This option overrides the default of com.intel.tss2.Tabrmd.

-g, --prng-seed-file

Read seed for pseudo-random number generator from the provided file.

-s, --session

Connect daemon to the session dbus. If the option is not specified the daemon connects to the system dbus.

-v, --version

Display version string.

## EXAMPLES
Execute daemon with default TCTI and options:

tpm2-abrmd

Execute daemon with default TCTI and provided config string:

tpm2-abrmd --tcti=":/dev/tpm0"

This is equivalent to:

tpm2-abrmd --tcti="device:/dev/tpm0"

tpm2-abrmd --tcti="libtss2-tcti-device.so.0:/dev/tpm0"

Have daemon use swtpm TPM2 Simulator tcti library

This connects to a TPM2 simulator via a TCP swtpm.

tpm2-abrmd --tcti="swtpm"

tpm2-abrmd --tcti="libtss2-tcti-swtpm.so.0"

Have daemon use tcti library 'libtss2-tcti-swtpm.so.0' and config string

tpm2-abrmd --tcti=swtpm:host=127.0.0.1,port=5555"

tpm2-abrmd --tcti="libtss2-tcti-swtpm.so.0:host=127.0.0.1,port=5555"

## AUTHOR
Philip Tricca <philip.b.tricca@intel.com>

## SEE ALSO
tcsd(8)

## COLOPHON
This page is part of the 2.4.1 release of Intel's TPM2 Access Broker & Resource Management Daemon. A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/01org/tpm2-abrmd/.


trickled

package: trickle

title: trickled(8)

summary: userspace bandwidth manager daemon

text:
# trickled(8)

## NAME
trickled — userspace bandwidth manager daemon

## SYNOPSIS
trickled

[-h] [-v] [-V] [-f] [-s] [-d rate] [-u rate] [-t seconds] [-l length] [-p priority] [-c file] [-n path] [-N seconds] [-w size]

## DESCRIPTION
trickled is a userspace bandwidth manager daemon. trickled manages several trickle(1) sessions at a time, shaping across multiple sessions.

The options are as follows:

-v

Increases the verbosity level (can be specified multiple times).

-V

Prints version.

-f

Runs trickled in the foreground.

-s

Uses syslog for all output (instead of stderr).

-d rate

Limit the download bandwidth consumption to rate KB/s.

-u rate

Limit the upload bandwidth consumption to rate KB/s.

-t seconds

Set smoothing time to seconds s. The smoothing time determines with what intervals trickled will try to let the application transceive data. Smaller values will result in a more continuous (smooth) session, while larger values may produce bursts in the sending and receiving data. Smaller values (0.1 - 1 s) are ideal for interactive applications while slightly larger values (1 - 10 s) are better for applications that need bulk transfer. This parameter is customizable on a per-application basis via trickled.conf(5). The default value is 5 s.

-l length

Set smoothing length to length KB. The smoothing length is a fallback of the smoothing time. If trickled cannot meet the requested smoothing time, it will instead fall back on sending length KB of data. The default value is 10 KB.

-p priority

Set default priority to priority.

-c file

Use the configuration file file. This file must be of the format documented in trickled.conf(5).

-n path

Set socket name to path. By default, trickled uses /tmp/.trickled.sock.

-N seconds

Notifies user of total bandwidth consumption every seconds s.

-w size

Set peak detection window size to size KB. This determines how aggressive trickled is at eliminating bandwidth consumption peaks. Lower values will be more aggressive, but may also result in over shaping. The default value (512 KB) is usually sufficient.

## EXAMPLES
trickled -u 10 -d 20

Limit aggregate trickle(1) upload bandwidth consumption to 10 KB/s and download consumption to 20 KB/s.

## SEE ALSO
trickle(1), trickled.conf(5), syslog(3), netintro(4)

## AUTHORS
trickled has been developed by Marius Aamodt Eriksen ⟨marius@monkey.org⟩.


tcsd

package: trousers

title: tcsd(8)

text:
# tcsd(8)

TCG Software Stack

## NAME
tcsd - daemon that manages Trusted Computing resources

## SYNOPSIS
tcsd [-f] [-e] [-c <configfile> ] [-h]

## DESCRIPTION
Trousers is an open-source TCG Software Stack (TSS), released under the BSD License. Trousers aims to be compliant with the current (1.1b) and upcoming (1.2) TSS specifications available from the Trusted Computing Group website: http://www.trustedcomputinggroup.org.

tcsd is a user space daemon that should be (according to the TSS spec) the only portal to the TPM device driver. At boot time, tcsd should be started, it should open the TPM device driver and from that point on, all requests to the TPM should go through the TSS stack. The tcsd manages TPM resources and handles requests from TSP's both local and remote.

-f, --foreground

run the daemon in the foreground

-e

attempt to connect to software TPMs over TCP

-c, --config <configfile>

use the provided configuration file rather than the default configuration file

-h, --help

display help message

## ACCESS CONTROL
There are two types of access control for the tcsd, access to the daemon's socket itself and access to specific commands internal to the tcsd. Access to the tcsd's port should be controlled by the system administrator using firewall rules. If using iptables, the following rule will allow a specific host access to the tcsd:

\# iptables -A INPUT -s $IP_ADDRESS -p tcp --destination-port 30003 -j ACCEPT

Access to individual commands internal to the tcsd is configured by the tcsd configuration file's "remote_ops" directive. Each function call in the TCS API is reachable by a unique ordinal. Each labeled "remote op" actually defines a set of ordinals (usually more than one) necessary to accomplish the operation. So, for example, the "random" operation enables the ordinals for opening and closing a context, calling TCS_StirRandom and TCS_GetRandom, as well as TCS_FreeMemory. By default, connections from localhost will allow any ordinals.

## DATA FILES
TSS applications have access to 2 different kinds of 'persistant' storage. 'User' persistant storage has the lifetime of that of the application using it and therefore is destroyed when an application exits. User PS is controlled by the TSP of the application. 'System' persistent storage is controlled by the TCS and stays valid across application lifetimes, tcsd restarts and system resets. Data registered in system PS stays valid until an application requests that it be removed. User PS files are by default stored as /var/tpm/user.{pid} and the system PS file by default is /var/tpm/system.data. The system PS file is initially created when ownership of the TPM is first taken.

## CONFIGURATION
tcsd configuration is stored by default in /etc/tcsd.conf

## DEBUG OUTPUT
If TrouSerS has been compiled with debugging enabled, the debugging output can be supressed by setting the TSS_DEBUG_OFF environment variable.

## DEVICE DRIVERS
tcsd is compatible with the IBM Research TPM device driver available from http://ibmswtpm.sourceforge.net/ and the TPM device driver available from http://sf.net/projects/tpmdd, which is also available in the upstream Linux kernel and many Linux distros.

## CONFORMING TO
tcsd conforms to the Trusted Computing Group Software Specification version 1.1 Golden

## SEE ALSO
tcsd.conf(5)

## AUTHOR
Kent Yoder

## REPORTING BUGS
Report bugs to <trousers-tech@lists.sf.net>


tsocks

package: tsocks

title: tsocks(8)

text:
# tsocks(8)

## NAME
tsocks - Library for intercepting outgoing network connections and redirecting them through a SOCKS server.

## SYNOPSIS
Set LD_PRELOAD to load the library then use applications as normal

The syntax to force preload of the library for different shells is specified below:

Bash, Ksh and Bourne shell -

export LD_PRELOAD=libtsocks.so

C Shell -

setenv LD_PRELOAD=libtsocks.so

This process can be automated (for Bash, Bourne and Korn shell users) for a single command or for all commands in a shell session by using the tsocks(1) script

You can also setup tsocks in such a way that all processes automatically use it, a very useful configuration. For more information on this configuration see the CAVEATS section of this manual page.

## DESCRIPTION
tsocks is a library to allow transparent SOCKS proxying. It wraps the normal connect() function. When a connection is attempted, it consults the configuration file (which is defined at configure time but defaults to /etc/tsocks.conf) and determines if the IP address specified is local. If it is not, the library redirects the connection to a SOCKS server specified in the configuration file. It then negotiates that connection with the SOCKS server and passes the connection back to the calling program.

tsocks is designed for use in machines which are firewalled from then internet. It avoids the need to recompile applications like lynx or telnet so they can use SOCKS to reach the internet. It behaves much like the SOCKSified TCP/IP stacks seen on other platforms.

### ARGUMENTS
Most arguments to tsocks are provided in the configuration file (the location of which is defined at configure time by the --with-conf=<file> argument but defaults to /etc/tsocks.conf). The structure of this file is documented in tsocks.conf(8)

Some configuration options can be specified at run time using environment variables as follows:

TSOCKS_CONFFILE

This environment variable overrides the default location of the tsocks configuration file. This variable is not honored if the program tsocks is embedded in is setuid. In addition this environment variable can be compiled out of tsocks with the --disable-envconf argument to configure at build time

TSOCKS_DEBUG

This environment variable sets the level of debug output that should be generated by tsocks (debug output is generated in the form of output to standard error). If this variable is not present by default the logging level is set to 0 which indicates that only error messages should be output. Setting it to higher values will cause tsocks to generate more messages describing what it is doing. If set to -1 tsocks will output absolutely no error or debugging messages. This is only needed if tsocks output interferes with a program it is embedded in. Message output can be permanently compiled out of tsocks by specifying the --disable-debug option to configure at build time

TSOCKS_DEBUG_FILE

This option can be used to redirect the tsocks output (which would normally be sent to standard error) to a file. This variable is not honored if the program tsocks is embedded in is setuid. For programs where tsocks output interferes with normal operation this option is generally better than disabling messages (with TSOCKS_DEBUG = -1)

TSOCKS_USERNAME

This environment variable can be used to specify the username to be used when version 5 SOCKS servers request username/password authentication. This overrides the default username that can be specified in the configuration file using 'default_user', see tsocks.conf(8) for more information. This variable is ignored for version 4 SOCKS servers.

TSOCKS_PASSWORD

This environment variable can be used to specify the password to be used when version 5 SOCKS servers request username/password authentication. This overrides the default password that can be specified in the configuration file using 'default_pass', see tsocks.conf(8) for more information. This variable is ignored for version 4 SOCKS servers.

### DNS ISSUES
tsocks will normally not be able to send DNS queries through a SOCKS server since SOCKS V4 works on TCP and DNS normally uses UDP. Version 1.5 and up do however provide a method to force DNS lookups to use TCP, which then makes them proxyable. This option can only enabled at compile time, please consult the INSTALL file for more information.

### ERRORS
tsocks will generate error messages and print them to stderr when there are problems with the configuration file or the SOCKS negotiation with the server if the TSOCKS_DEBUG environment variable is not set to -1 or and --disable-debug was not specified at compile time. This output may cause some problems with programs that redirect standard error.

### CAVEATS
tsocks will not in the above configuration be able to provide SOCKS proxying to setuid applications or applications that are not run from a shell. You can force all applications to LD_PRELOAD the library by placing the path to libtsocks in /etc/ld.so.preload. Please make sure you correctly enter the full path to the library in this file if you do this. If you get it wrong, you will be UNABLE TO DO ANYTHING with the machine and will have to boot it with a rescue disk and remove the file (or try the saveme program, see the INSTALL file for more info). THIS IS A ***WARNING***, please be careful. Also be sure the library is in the root filesystem as all hell will break loose if the directory it is in is not available at boot time.

## BUGS
tsocks can only proxy outgoing TCP connections

tsocks does NOT work correctly with asynchronous sockets (though it does work with non blocking sockets). This bug would be very difficult to fix and there appears to be no demand for it (I know of no major application that uses asynchronous sockets)

tsocks is NOT fully RFC compliant in its implementation of version 5 of SOCKS, it only supports the 'username and password' or 'no authentication' authentication methods. The RFC specifies GSSAPI must be supported by any compliant implementation. I haven't done this, anyone want to help?

tsocks can force the libc resolver to use TCP for name queries, if it does this it does it regardless of whether or not the DNS to be queried is local or not. This introduces overhead and should only be used when needed.

tsocks uses ELF dynamic loader features to intercept dynamic function calls from programs in which it is embedded. As a result, it cannot trace the actions of statically linked executables, non-ELF executables, or executables that make system calls directly with the system call trap or through the syscall() routine.

## FILES
/etc/tsocks.conf - default tsocks configuration file

## SEE ALSO
tsocks.conf(5) tsocks(1)

## AUTHOR
Shaun Clowes (delius@progsoc.uts.edu.au)

## COPYRIGHT
Copyright 2000 Shaun Clowes

tsocks and its documentation may be freely copied under the terms and conditions of version 2 of the GNU General Public License, as published by the Free Software Foundation (Cambridge, Massachusetts, United States of America).

This documentation is based on the documentation for logwrites, another shared library interceptor. One line of code from it was used in tsocks and a lot of the documentation :) logwrites is by adam@yggdrasil.com (Adam J. Richter) and can be had from ftp.yggdrasil.com pub/dist/pkg


ttysnoop

package: ttysnoop

title: ttysnoop(8)

summary: snoop on a user's tty

text:
# ttysnoop(8)

## NAME
ttysnoop — snoop on a user's tty

## SYNOPSIS
ttysnoop

[pty]

ttysnoops

[loginname]

## DESCRIPTION
The ttysnoop / ttysnoops client-server combo can be used to snoop (watch) on a user's login tty. The server (ttysnoops) is usually started by getty(8) or telnetd(8) and reads the file /etc/snooptab to find out which tty's should be cloned and which programs to run on them (usually /bin/login). A tty may be snooped through a pre-determined (ie. fixed) device, or through a dynamically allocated pseudo-tty (pty). This is also specified in the /etc/snooptab file. To connect to the pty, the ttysnoop client should be used.

### Format of /etc/snooptab
The /etc/snooptab file may contain comment lines (starting with a '#'), empty lines, or entries for tty's that should be snooped upon. The format of such an entry is as follows:

```
tty   snoop-device   type   program
```

where tty is the leaf-name of the tty that should be snooped upon (eg. ttyS2, not /dev/ttyS2) OR the wildcard '*', which matches ANY tty. snoop-device is the device through which tty should be snooped (eg. /dev/tty8) OR the literal constant "socket". The latter is used to tell ttysnoops that the snoop-device will be a dynamically allocated pty. type specifies the type of program that should be run, currently recognized types are "init", "user" and "login" altough the former two aren't really needed. Finally, program is the full pathname to the program to run when ttysnoops has cloned tty onto snoop-device.

## EXAMPLE
The following example /etc/snooptab file should illustrate the typical use of ttysnoop / ttysnoops:

```
 #
 # example /etc/snooptab
 #
 ttyS0    /dev/tty7    login    /bin/login
 ttyS1    /dev/tty8    login    /bin/login
 #
 # the wildcard tty should always be the last one in the file
 #
 *        socket       login    /bin/login
 #
 # example end
 #
```

With the above example, whenever a user logs in on /dev/ttyS0 or /dev/ttyS1, either tty will be snooped through /dev/tty7 or /dev/tty8 respectively. Any other tty's will be snooped through a pty that will be allocated at the time of login. The system-administrator can then run ttysnoop pty to snoop through the pty. Note that it is up to the system-administrator to setup getty and/or telnetd so that they execute ttysnoops instead of /bin/login.

## SEE ALSO
getty(8), telnetd(8)

## FILES
/etc/snooptab

## BUGS
The program is unable to do any terminal control-code translations for the original tty and the snoop-device. I doubt it will ever do this.

## AUTHOR
Carl Declerck, carl@miskatonic.inbe.net


tunctl

package: tunctl

title: tunctl(8)

text:
# tunctl(8)

## NAME
tunctl - create and manage persistent TUN/TAP interfaces

## SYNOPSIS
tunctl [ OPTIONS ] [ -u owner ] [ -t device-name ]

tunctl -d device-name

## DESCRIPTION
tunctl allows the host sysadmin to preconfigure a TUN/TAP network interface for use by a particular user. That user may open and use the network/write side of the interface, but may not change any aspects of the host side of the interface.

## OPTIONS
-b

Brief output, prints just the interface name

-n

Create a point-to-point TUN interface without Ethernet header. Automatically enabled if the desired interface name starts with "tun".

-p

Create a TAP type interface with Ethernet header. Automatically selected if the desired interface starts with "tap" or if no interface name is given.

-f tun-clone-device

Specifies the tun clone device name. The default is /dev/net/tun, but some systems use /dev/misc/net/tun instead.

-d interfacename

Delete the specified interfacename (set it to non-persistent)

-u user

Specifies the owner of the interface. This user is allowed to attach to the "network/wire" side.

-g group

Specifies the group of the interface. This group is allowed to attach to the "network/wire" side of the interface.

-t interface

Specifies the desired interface name.

## USAGE
To create an interface for use by a particular user, invoke tunctl without the -d option:

```
        # tunctl -u someuser

        Set 'tap0' persistent and owned by 'someuser'

```

Then, configure the interface as normal:

```
        # ifconfig tap0 192.168.0.254 up

        # route add -host 192.168.0.253 dev tap0

        # bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'

        # arp -Ds 192.168.0.253 eth0 pub

```

To delete the interface, use the -d option:

```
        # tunctl -d tap0

        Set 'tap0' nonpersistent

```

## SEE ALSO
The UserModeLinux-HOWTO <URL:http://user-mode-linux.sourceforge.net/old/UserModeLinux-HOWTO.html>

## AUTHOR
tunctl was originally written by Jeff Dike <jdike@karaya.com> as part of the User Mode Linux tools. Current version is maintained as a separate package by Henrik Nordstrom <henrik@henriknordstrom.net>.

This manual page was originally written by Matt Zimmerman <mdz@debian.org> for the Debian GNU/Linux system, based on examples from Jeff Dike. Extended by Henrik Nordstrom <henrik@henriknordstrom.net> to cover all options supported.


tuned

package: tuned

title: tuned(8)

text:
# tuned(8)

## NAME
TuneD - dynamic adaptive system tuning daemon

## SYNOPSIS
tuned [options]

## DESCRIPTION
tuned is a dynamic adaptive system tuning daemon that tunes system settings dynamically depending on usage.

## OPTIONS
-d, --daemon

This options starts tuned as a daemon as opposed to in the foreground without forking at startup.

-D, --debug

Sets the highest logging level. This could be very useful when having trouble with tuned.

-h, --help

Show this help.

-l [LOG], --log[=LOG]

Log to the file LOG. If no LOG file is specified /var/log/tuned/tuned.log is used.

--no-dbus

Do not attach to DBus.

-P [PID], --pid[=PID]

Write process ID to the PID file. If no PID file is specified /run/tuned/tuned.pid is used.

-p PROFILE, --profile PROFILE

Tuning profile to be activated. It will override other settings (e.g. from tuned-adm). This is intended for debugging purposes.

-v, --version

Show version information.

## FILES

```
/etc/tuned
```

## SEE ALSO
tuned.conf(5) tuned-adm(8)

## AUTHOR

```
Jan Kaluža <jkaluza@redhat.com>
Jan Včelák <jvcelak@redhat.com>
Jaroslav Škarvada <jskarvad@redhat.com>
Phil Knirsch <pknirsch@redhat.com>
```

## REPORTING BUGS
Report bugs to https://bugzilla.redhat.com/.