pbs_module(7B)
๐
pbs_module โ the pbs_module(7B) page, bestie edition
PBS Professional ยท manual section 7B
โจ NAME โจ
pbs_module โ the Python interface to PBS and to the PBS hook environment ๐๐
๐ธ DESCRIPTION ๐ธ
okay so. the pbs module is literally your doorway into PBS and the hook environment. it's built out of Python objects, and those objects come with attributes and methods, which means you justโฆ write Python at them. that's it. that's the whole vibe. ๐ซถ
๐ PBS MODULE OBJECTS ๐
this is the full cast of characters, no skips, no cuts ๐
pbs.aclโ represents a PBS ACL type.pbs.argsโ represents a space-separated list of PBS arguments to commands likeqsub,qdel.pbs.argv[]โ represents a list of argument strings to be passed to the program.pbs.BadAttributeValueErrorโ raised when setting the attribute value of apbs.*object to an invalid value.pbs.BadAttributeValueTypeErrorโ raised when setting the attribute value of apbs.*object to an invalid value type.pbs.BadResourceValueErrorโ raised when setting the resource value of apbs.*object to an invalid value.pbs.BadResourceValueTypeErrorโ raised when setting the resource value of apbs.*object to an invalid value type.pbs.checkpointโ represents a job's Checkpoint attribute.pbs.dependโ represents a job's depend attribute.pbs.durationโ represents a time interval.pbs.email_listโ represents the set of users to whom mail may be sent.pbs.env[]โ dictionary of environment variables.pbs.eventโ represents a PBS event.pbs.EventIncompatibleErrorโ raised when referencing a non-existent attribute inpbs.event().pbs.EXECHOST_PERIODICโ theexechost_periodicevent type.pbs.EXECHOST_STARTUPโ theexechost_startupevent type.pbs.EXECJOB_ATTACHโ theexecjob_attachevent type.pbs.EXECJOB_BEGINโ theexecjob_beginevent type.pbs.EXECJOB_ENDโ theexecjob_endevent type.pbs.EXECJOB_EPILOGUEโ theexecjob_epilogueevent type.pbs.EXECJOB_LAUNCHโ theexecjob_launchevent type.pbs.EXECJOB_PRETERMโ theexecjob_pretermevent type.pbs.EXECJOB_PROLOGUEโ theexecjob_prologueevent type.pbs.exec_hostโ represents a job'sexec_hostattribute.pbs.exec_vnodeโ represents a job'sexec_vnodeattribute.pbs.group_listโ represents a list of group names.pbs.hold_typesโ represents a job'sHold_Typesattribute.pbs.hook_config_filenameโ contains path to hook's configuration file.pbs.jobโ represents a PBS job.pbs.job_list[]โ represents a list ofpbs.jobobjects.pbs.job_sort_formulaโ represents the server'sjob_sort_formulaattribute.pbs.JOB_STATE_BEGUNโ represents the job array state of having started.pbs.JOB_STATE_EXITINGโ represents the job state of exiting.pbs.JOB_STATE_EXPIREDโ represents the subjob state of expiring.pbs.JOB_STATE_FINISHEDโ represents the job state of finished.pbs.JOB_STATE_HELDโ represents the job state of held.pbs.JOB_STATE_MOVEDโ represents the job state of moved.pbs.JOB_STATE_QUEUEDโ represents the job state of queued.pbs.JOB_STATE_RUNNINGโ represents the job state of running.pbs.JOB_STATE_SUSPENDโ represents the job state of suspended.pbs.JOB_STATE_SUSPEND_USERACTIVEโ represents the job state of suspended due to user activity.pbs.JOB_STATE_TRANSITโ represents the job state of transiting.pbs.JOB_STATE_WAITINGโ represents the job state of waiting.pbs.join_pathโ represents a job'sJoin_Pathattribute.pbs.keep_filesโ represents a job'sKeep_Filesattribute.pbs.license_countโ represents a set of licensing-related counters.pbs.LOG_DEBUGโ log level004.pbs.LOG_ERRORโ log level004.pbs.LOG_WARNINGโ log level004.pbs.mail_pointsโ represents a job'sMail_Pointsattribute.pbs.MODIFYJOBโ themodifyjobevent type.pbs.MOVEJOBโ themovejobevent type.pbs.ND_BUSYโ represents busy vnode state.pbs.ND_DEFAULT_EXCLโ representsdefault_exclsharing vnode attribute valuepbs.ND_DEFAULT_SHAREDโ representsdefault_sharedsharing vnode attribute value.pbs.ND_DOWNโ represents down vnode statepbs.ND_FORCE_EXCLโ representsforce_exclsharing vnode attribute value.pbs.ND_FREEโ represents free vnode state.pbs.ND_GLOBUSโ PBS no longer supports Globus. The Globus functionality has been removed from PBS.
Represents globus vnode ntype.
pbs.ND_IGNORE_EXCLโ representsignore_exclsharing vnode attribute value.pbs.ND_JOBBUSYโ represents job-busy vnode state.pbs.ND_JOB_EXCLUSIVEโ represents job-exclusive vnode state.pbs.ND_OFFLINEโ represents offline vnode state.pbs.ND_PBSโ represents pbs vnode ntype.pbs.ND_PROVโ represents provisioning vnode state.pbs.ND_RESV_EXCLUSIVEโ represents resv-exclusive vnode state.pbs.ND_STALEโ represents stale vnode state.pbs.ND_STATE_UNKNOWNโ represents state-unknown, down vnode state.pbs.ND_UNRESOLVABLEโ represents the unresolvable vnode state.pbs.ND_WAIT_PROVโ represents wait-provisioning vnode state.pbs.node_group_keyโ represents the server or queuenode_group_keyattribute.pbs.path_listโ represents a list of pathnames.pbs.pbs_conf[]โ dictionary of entries inpbs.conf.pbs.pidโ represents the process ID of a process belonging to a job.pbs.placeโ represents the place job submission specification.pbs.prognameโ path of job shell or executable.pbs.QTYPE_EXECUTIONโ the execution queue type.pbs.QTYPE_ROUTEโ the route queue type.pbs.queueโ represents a PBS queue.pbs.QUEUEJOBโ thequeuejobevent type.pbs.rangeโ represents a range of numbers referring to array indices.pbs.resvโ represents a PBS reservation.pbs.RESVSUBโ theresvsubevent type.pbs.RESV_STATE_BEING_DELETEDโ represents the reservation stateRESV_BEING_DELETED.pbs.RESV_STATE_CONFIRMEDโ represents the reservation stateRESV_CONFIRMED.pbs.RESV_STATE_DEGRADEDโ represents the reservation stateRESV_DEGRADED.pbs.RESV_STATE_DELETEDโ represents the reservation stateRESV_DELETED.pbs.RESV_STATE_DELETING_JOBSโ represents the reservation stateRESV_DELETING_JOBS.pbs.RESV_STATE_FINISHEDโ represents the reservation stateRESV_FINISHED.pbs.RESV_STATE_NONEโ represents the reservation stateRESV_NONE.pbs.RESV_STATE_RUNNINGโ represents the reservation stateRESV_RUNNING.pbs.RESV_STATE_TIME_TO_RUNโ represents the reservation stateRESV_TIME_TO_RUN.pbs.RESV_STATE_UNCONFIRMEDโ represents the reservation stateRESV_UNCONFIRMED.pbs.RESV_STATE_WAITโ represents the reservation stateRESV_WAIT.pbs.route_destinationsโ represents a queue'sroute_destinationsattribute.pbs.RUNJOBโ therunjobevent type.pbs.selectโ represents the select job submission specification.pbs.serverโ represents the local PBS server.pbs.sizeโ represents a PBS size type.pbs.softwareโ represents a site-dependent software specification resource.pbs.staging_listโ represents a list of file stagein or stageout parameters.pbs.state_countโ represents a set of job-related state counters.pbs.SV_STATE_ACTIVEโ represents the server state "Scheduling".pbs.SV_STATE_HOTโ represents the server state "Hot_Start".pbs.SV_STATE_IDLEโ represents the server state "Idle".pbs.SV_STATE_SHUTDELโ represents the server state "Terminating, Delayed".pbs.SV_STATE_SHUTIMMโ represents the server state "Terminating".pbs.SV_STATE_SHUTSIGโ represents the server state "Terminating", when a signal has been caught.pbs.UnsetAttributeNameErrorโ raised when referencing a non-existent name of apbs.*object.pbs.UnsetResourceNameErrorโ raised when referencing a non-existent name of apbs.*object.pbs.user_listโ represents a list of user names.pbs.vchunkโ represents a resource chunk assigned to a job.pbs.versionโ represents PBS version information.pbs.vnodeโ represents a PBS vnode.pbs.vnode_list[]โ represents a list of PBS vnodes.SystemExitโ raised when accepting or rejecting an action.
๐ฅ PBS MODULE GLOBAL METHODS ๐ฅ
these are the top-level pbs.* creators โ the way you actually make one of those objects ๐
pbs.acl("[+|-]<entity>][,...]")โ creates an object representing a PBS ACL, using the given string parameter. instantiation of these objects requires a formatted input string. ๐pbs.args("<args>")โ where <args> are space-separated arguments to a command such asqsuborqdel. creates an object representing the arguments to the command. example:
pbs.args("-Wsuppress_email=N -r y")
instantiation of these objects requires a formatted input string. โจ
pbs.checkpoint("<checkpoint_string>")โ where <checkpoint_string> must be one of"n","s","c","c=mmm","w", or"w=mmm". creates an object representing the job's Checkpoint attribute, using the given string. instantiation of these objects requires a formatted input string. โ๏ธpbs.depend("<depend_string>")โ <depend_string> must be of format"<type>:<jobid>[,<jobid>...]", or"on:<count>", and where <type> is one of"after","afterok","afterany","before","beforeok", and"beforenotok". creates a PBS dependency specification object representing the job's depend attribute, using the given <depend_string>. instantiation of these objects requires a formatted input string. ๐pbs.duration("[[hours:]minutes:]seconds[.milliseconds]")โ creates a time specification duration instance, returning the equivalent number of seconds from the given time string. represents an interval or elapsed time in number of seconds. duration objects can be specified using either a time or an integer. see the"pbs.duration(<integer>)"creation method. โณ
โฆand that's only the beginning, bestie โ more parts are coming, don't go anywhere ๐
๐ pbs.duration(<integer>)
Makes you an integer duration instance out of the number of seconds you hand it. A pbs.duration instance can be operated on by any of the Python int functions. ๐
Heads up bestie: when you do arithmetic on apbs.durationtype, make sure the resulting value is apbs.duration()type before you assign it to a job member that expects that type. The vibe check will fail otherwise. ๐ซถ
๐ง pbs.email_list("<email_address1>[,<email_address2>...]")
Creates an object representing a mail list. Instantiation of these objects requires a formatted input string. Fr fr, format it right or it's not happening. โจ
๐ฅ๏ธ pbs.exec_host("host/N[*C][+...]")
Creates an object representing the exec_host job attribute, using the given host and resource specification. Instantiation of these objects requires a formatted input string. ๐
๐ pbs.exec_vnode("<vchunk>[+<vchunk>...]")
Okay so <vchunk> is (<vnodename:ncpus=N:mem=M>) โ and this creates an object representing the exec_vnode job attribute, using the given vnode and resource specification. ๐
When the qrun -H command is used, or when the scheduler runs a job, the pbs.job.exec_vnode object contains the vnode specification for the job. Instantiation of these objects requires a formatted input string.
Example:
pbs.exec_vnode("(vnodeA:ncpus=N:mem=X)+(nodeB:ncpus=P:mem=Y+nodeC:mem=Z)")
This object is managed and accessed via the str() or repr() functions.
Example:
Python> ev = pbs.server().job("10").exec_vnode
Python> str(ev)
"(vnodeA:ncpus=2:mem=200m)+(vnodeB:ncpus=5:mem=1g)"
Slay. ๐ฆ
๐ pbs.get_hook_config_file()
Returns the path to the hook's configuration file, or None if there is no configuration file. Literally that simple. For example:
configfilepath = pbs.get_hook_config_file()
๐ pbs.get_local_nodename()
This returns a Python str whose value is the name of the local natural vnode. ๐
If you want to refer to the vnode object representing the current host, you can pass this vnode name as the key to pbs.event().vnode_list[]. For example:
Vn = pbs.event().vnode_list[pbs.get_local_nodename()]
iykyk. ๐
โ๏ธ pbs.get_pbs_conf()
This method returns a dictionary of values which represent entries in the pbs.conf file. The method reads the file on the host where a hook runs, so pre-execution event hooks get the entries on the server host, and execution event hooks get the entries on the execution host where the hook runs. It reads /etc/pbs.conf on the host where pbs_python runs. ๐
Example:
pbs_conf = pbs.get_pbs_conf()
pbs.logmsg(pbs.LOG_DEBUG, "pbs home is " %
(pbs_conf['PBS_HOME']))
If you HUP pbs_mom (Linux/UNIX), pbs.get_pbs_conf returns the reloaded contents of the pbs.conf file. Fresh out the oven. ๐ฅ
๐ฏ pbs.group_list("<group_name>[@<host>][,<group_name>[@<host>]...]")
Creates an object representing a PBS group list. To use a group list object:
pbs.job.group_list = pbs.group_list(....)
Instantiation of these objects requires a formatted input string. No shortcuts, bestie. โจ
โ pbs.hold_types("<hold_type_str>")
where <hold_type_str> is one of "u", "o", "s", or "n". Creates an object representing the Hold_Types job attribute. Instantiation of these objects requires a formatted input string. ๐
๐งฎ pbs.job_sort_formula("<formula_string>")
where <formula_string> is a string containing a math formula. Creates an object representing the job_sort_formula server attribute. Instantiation of these objects requires a formatted input string. Math era. ๐
๐ pbs.join_path({"oe"|"eo"|"n"})
Creates an object representing the Join_Path job attribute. Instantiation of these objects requires a formatted input string. ๐
๐๏ธ pbs.keep_files("<keep_files_str>")
where <keep_files_str> is one of "o", "e", "oe", "eo". Creates an object representing the Keep_Files job attribute. Instantiation of these objects requires a formatted input string. Keep it or lose it, your call. ๐ฆ
๐ชช pbs.license_count("Avail_Global:<W>Avail_Local:<X>Used:<Y>High_Use:<Z>")
Instantiates an object representing a license_count attribute. Instantiation of these objects requires a formatted input string. Get those placeholders right or it's giving nothing. ๐ธ
๐ pbs.logjobmsg(job_ID,message)
where job_ID must be an existing or previously existing job ID and where message is an arbitrary string. This puts a custom string in the PBS Server log. ๐
The tracejob command can be used to print out the job-related messages logged by a hook script. Messages are logged at log event class pbs.LOG_DEBUG. So cute, so findable. ๐
๐ชต pbs.logmsg(log_event_class,message)
where message is an arbitrary string, and where log_event_class can be one of the message log event class constants:
pbs.LOG_WARNINGpbs.LOG_ERRORpbs.LOG_DEBUG
This puts a custom string in the daemon log. Main character logging energy. ๐
๐ฌ pbs.mail_points("<mail_points_string>")
where <mail_points_string> is "a", "b", and/or "e", or "n". Creates an object representing a Mail_Points attribute. Instantiation of these objects requires a formatted input string. ๐
๐๏ธ pbs.node_group_key("<resource>")
Creates an object representing the resource to be used for node grouping, using the specified resource. That's it, that's the whole thing. โจ
๐ pbs.path_list("<path>[@<host>][,<path>@<host>...]")
Creates an object representing a PBS pathname list. To use a path list object:
pbs.job.Shell_Path_List = pbs.path_list(....)
Instantiation of these objects requires a formatted input string. ๐ซถ
๐ฑ pbs.env()
Creates an empty environment variable list. For example, to create an empty environment variable list:
pbs.event().env = pbs.pbs_env()
Empty and unbothered. ๐
๐บ๏ธ pbs.place("[arrangement]:[sharing]:[group]")
- arrangement can be
"pack","scatter","free","vscatter" - sharing can be
"shared","excl","exclhost" - group can be of the form
"group=<resource>"
[arrangement], [sharing], and [group] can be given in any order or combination. ๐ฅ
Creates a place object representing the job's place specification. Instantiation of these objects requires a formatted input string.
Example:
pl = pbs.place("pack:excl")
s = repr(pl) (or s = `pl`)
letter = pl[0] (assigns 'p' to letter)
s = s + ":group=host" (append to string) br pl = pbs.place(s)
(update original pl)
๐ข pbs.range("<start>-<stop>:<step>")
Creates a PBS object representing a range of values. Example:
pbs.range("1-30:3")
Instantiation of these objects requires a formatted input string. Steps go hard. ๐
๐ pbs.reboot([<command>])
Okay this one's a big deal, so listen up. ๐ This stops hook execution, so that remaining lines in the hook script are not executed, and starts the tasks that would normally begin after the hook is finished, such as flagging the current host to be rebooted. The MoM logs show the following:
<hook name> requested for host to be rebooted
We recommend that before calling pbs.reboot(), you set any vnodes managed by this MoM offline, and requeue the current job, if this hook is not an exechost_periodic hook. For example:
for v in pbs.event().vnode_list.keys():
pbs.event().vnode_list[v].state = pbs.ND_OFFLINE
pbs.event().vnode_list[v].comment = "MoM host rebooting"
pbs.event().job.rerun()
pbs.reboot()
The effect of the call topbs.reboot()is not instantaneous. The reboot happens after the hook executes, and after any of the other actions such aspbs.event().job.rerun(),pbs.event().delete(), andpbs.event().vnode_list[]take effect. So don't panic when nothing happens immediately, bestie. ๐ญ
A hook with its user attribute set to pbsuser cannot successfully invoke pbs.reboot(), even if the owner is a PBS Manager or Operator. If this is attempted, the host is not rebooted, and the following message appears at log event class PBSEVENT_DEBUG2 in the MoM logs:
<hook_name>; Not allowed to issue reboot if run as user.
The <command> is an optional argument. It is a Python str which is executed instead of the reboot command that is the default for the system. For example:
pbs.reboot("/usr/local/bin/my_reboot -s 10 -c 'going down in
10'")
The specified <command> is executed in a shell on Linux/UNIX or via cmd on Windows. Custom reboot era. ๐ง
๐ฃ๏ธ pbs.route_destinations("<queue_spec>[,<queue_spec>,...]")
where <queue_spec> is queue_name[@server_host[:port]]
Creates an object that represents a route_destinations routing queue attribute. Instantiation of these objects requires a formatted input string. ๐
โ
pbs.select("[N:]res=val[:res=val][+[N:]res=val[:res=val]...]")
Creates a select object representing the job's select specification. Instantiation of these objects requires a formatted input string. Example:
sel = pbs.select("2:ncpus=1:mem=5gb+3:ncpus=2:mem=5gb")
s = repr(sel) (or s = `sel`)
letter = s[3] (assigns 'c' to letter)
s = s + "+5:scratch=10gb" (append to string)
sel = pbs.select(s) (reset the value of sel)
Iconic. ๐
๐ pbs.size(<integer>)
Creates a PBS size object using the given integer value, storing the value as the number of bytes. ๐ฆ
Size objects can be specified using either an integer or a string. See the pbs.size("<integer><suffix>") creation method. ๐
๐ pbs.size("<integer><suffix>")
Creates a PBS size object out of the given string specification. The size of a word is the word size on the execution host. Size objects can be specified using either an integer or a string. ๐
To operate on pbs.size instances, use the + and - operators. To compare pbs.size instances, use the ==, !=, >, <, >=, and <= operators.
Example: the sizes are normalized to the smaller of the 2 suffixes. In this case, "10gb" becomes "10240mb" and is added to "10mb":
sz = pbs.size("10gb")
sz = sz + 10mb
10250mb
Example: the following returns True because sz is greater than 100 bytes:
if sz > 100:
gt100 = True
Unit math ate, honestly. ๐ฅ
๐พ pbs.software("<software_info_string>")
Creates an object representing a site-dependent software resource. Instantiation of these objects requires a formatted input string. ๐ง
pbs.staging_list("<filespec>[,<filespec>,...]")โ this makes an object that represents a job file staging parameters list, bestie. Thewhere <filespec> issituation looks like this:
<execution_path>@<storage_host>:<storage_path>
To actually use a staging list object:
pbs.job.stagein = pbs.staging_list(....)
Instantiation of these objects requires a formatted input string. That's the vibe check. ๐
pbs.state_count("Transit:<U>Queued:<V>Held:<W>Running:<X>Exiting:<Y>Begun:<Z>)โ instantiates an object representing astate_countattribute. Instantiation of these objects requires a formatted input string. โจpbs.user_list("<user>[@<host>][,<user>@<host>...]")โ creates an object representing a PBS user list. To use a user list object:
pbs.job.User_List = pbs.user_list(....)
Instantiation of these objects requires a formatted input string. ๐ซถ
pbs.version("<pbs_version_string>")โ creates an object representing the PBS version string. Instantiation of these objects requires a formatted input string. ๐
๐ธ ATTRIBUTES AND RESOURCES ๐ธ
Hooks can read Server, Queue, or reservation resources. Hooks can read vnode or job attributes and resources. Hooks can modify:
- The resources requested by a job
- The resources used by a job
- The attributes of a job
- The resource arguments to
pbs_rsub - Vnode attributes and resources
- The shell or program to be executed in a job
- The arguments to the shell or program to be executed in a job
- The environment of the job
Custom and built-in PBS resources are represented in Python dictionaries, where the resource names are the dictionary keys. Built-in resources are listed in pbs_resources(7B). You reference a resource through a vnode, the Server, the event that triggered the hook, or the current job, for example:
pbs.server().resources_available["< resource name>"]
pbs.event().job.Resource_List["< resource name>"]
pbs.event().vnode_list[<vnode name>].resources_available["<
resource name >"]
The resource name must be in quotes. Example: Get the number of CPUs:
ncpus = Resource_List["ncpus"]
An instance R of a job resource can be set as follows:
R["<resource name>"] = <resource value>
For example:
pbs.event().job().Resource_List["mem"] = 8gb
๐ EXCEPTIONS ๐
pbs.BadAttributeValueErrorโ Raised when setting the attribute value of apbs.*object to an invalid value.pbs.BadAttributeValueTypeErrorโ Raised when setting the attribute value of apbs.*object to an invalid value type.pbs.BadResourceValueErrorโ Raised when setting the resource value of apbs.*object to an invalid value.pbs.BadResourceValueTypeErrorโ Raised when setting the resource value of apbs.*object to an invalid value type.pbs.EventIncompatibleErrorโ Raised when referencing a non-existent attribute inpbs.event().pbs.UnsetAttributeNameErrorโ Raised when referencing a non-existent name of an attribute.pbs.UnsetResourceNameErrorโ Raised when referencing a non-existent name of a resource.SystemExitโ Raised when accepting or rejecting an action.
If a hook encounters an unhandled exception:
- PBS rejects the corresponding action, and an error message is printed to
stderr. - A message is printed to the daemon log.
๐ฆ SEE ALSO ๐ฆ
pbs_hook_attributes(7B), pbs_resources(7B), qmgr(1B)
๐ Thatโs the whole pbs_module(7B) page, bestie โ source Local, dated 6 April 2020, page pbs_module(7B). Go forth and hook responsibly, icon. ๐
๐ฆ where this page comes from
- nixos 26.05: openpbs 23.06.06-unstable-2026-04-02
- nixpkgs unstable: openpbs 23.06.06-unstable-2026-04-02
- Copyright (C) 1994-2021 Altair Engineering, Inc
- ๐ girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms