qmgr(8B)

🎀 qmgr(8B) — PBS Professional 🎀

🌸 NAME 🌸

qmgr — the administrator's command interface for managing PBS. Basically the admin group chat for your PBS universe, and yes, she runs the whole thing. 💅

🔥 SYNOPSIS 🔥

At the shell command line:

qmgr -c '<directive> [-a] [-e] [-n] [-z]'
qmgr -c 'help [<help option>]'
qmgr <return>
qmgr --version

In a qmgr session:

<directive> [-a] [-e] [-n] [-z]
help <help option>

💖 DESCRIPTION 💖

The PBS manager command, qmgr, provides a command-line interface to parts of PBS. The qmgr command is used to create or delete queues, vnodes, resources, and hooks, to set or change vnode, queue, hook, server, or scheduler attributes and resources, and to view information about hooks, queues, vnodes, resource definitions, the server, and schedulers. Admin main character energy, honestly. 👑

For a list of quick summaries of information about syntax, commands, attributes, operators, names, and values, type "help" or "?" at the qmgr prompt. See "Printing Usage Information", below. iykyk 🫶

🕹️ Modes of Operation 🕹️

When you type qmgr -c '<directive>', qmgr performs its task and then exits. One-and-done, no lingering.

When you type qmgr <return>, qmgr starts a session and presents you with its command line prompt. The qmgr command then reads directives etc. from standard input; see "Directive Syntax", below. You can edit the command line; see "Reusing and Editing the qmgr Command Line", below. It's giving interactive era. ✨

For a qmgr prompt, type:

qmgr <return>

You will see the qmgr prompt:

Qmgr:

👑 Required Privilege 👑

The qmgr command requires different levels of privilege depending on the operation to be performed.

All users can list or print attributes except for hook attributes. Everyone gets a peek at the basics.

PBS Operator or Manager privilege is required in order to set or change vnode, queue, server, or scheduler attributes. PBS Manager privilege is required in order to create or delete queues, vnodes, and resources. So yes, the manager badge is doing actual work here.

Under Linux, root privilege is required in order to create hooks, or operate on hooks or the job_sort_formula server attribute. Under Windows, this must be done from the installation account. Different OS, different rules, bestie.

For domained environments, the installation account must be a local account that is a member of the local Administrators group on the local computer. For standalone environments, the installation account must be a local account that is a member of the local Administrators group on the local computer. Same energy, both modes.

Users without manager or operator privilege cannot view custom resources or resource definitions which were created to be invisible to users. No sneaky peeking, periodt. 💀

🖥️ When To Run qmgr At Server Host 🖥️

When operating on hooks or on the job_sort_formula server attribute, the qmgr command must be run at the server host. Do not try to do this from just anywhere. 🫶

🎀 Reusing and Editing the qmgr Command Line 🎀

You can reuse or edit qmgr command lines. The qmgr command maintains a history of commands entered, up to a maximum of 500. You can use the 'history' command to see a numbered list of commands, and the !<n> command to execute the line whose number is n. You must not put any spaces between the bang ("!") and the number. For example, to execute the 123rd command, type the following:

!123

You can see the last m commands by typing 'history m'. For example, to see the last 6 commands, type the following:

history 6

You can use the up and down arrows to navigate through the command history list, and the left and right arrows to navigate within a command line. Within a command line, you can use emacs commands to move forward and backward, and delete characters. Full glow-up keyboard navigation. ⌨️

You can edit the qmgr command line using the backspace and delete keys, and you can insert characters anywhere in a command line. Insert anywhere? She's flexible. 💅

History is maintained across qmgr sessions, so that if you start qmgr, then exit, then restart it, you can reuse your commands from the previous session. If you exit qmgr and then restart it, the command lines are renumbered. Your history is lowkey persistent, but the numbering gets a reset.

If you enter the same command line more than once in a row, only one occurrence is recorded in the history. If you enter the same command line multiple times, but intersperse other command lines after each line, each occurrence is recorded. Consecutive twins get collapsed; spaced-out repeats stay.

Each user's history is unique to that user on that host. Your host, your user, your little history bubble. 🦋

In the case where an account runs concurrent sessions, the most recent logout of a session overwrites history from previous logouts. For example, if two people are both logged in as root and using qmgr, the second person to log out overwrites the history file. Heads up: concurrent-session history can absolutely get clobbered. 😭

🌈 The qmgr History File 🌈

The qmgr command stores and retrieves its history. First, it tries to write its history in the ${HOME}/.pbs_qmgr_history file. If this file or directory location is not writable, the command stores its history in $PBS_HOME/spool/.pbs_qmgr_history_<user name>. If this file is also not writable, the following happens:

• The qmgr command prints error messages once at qmgr startup
• The qmgr command cannot provide history across qmgr sessions

So if both spots are unwritable, you get one startup warning and no lovely cross-session history. 🫶

⚙️ OPTIONS TO qmgr ⚙️

The following covers the options to qmgr:

• <return> — Starts a qmgr session and presents user with qmgr prompt.
• -a — Aborts qmgr on any syntax errors or any requests rejected by a server. Bad vibe detected? She exits.
• -c '<directive>' — Executes a single command (directive) and exit qmgr. The directive must be enclosed in single or double quote marks, for example:

qmgr -c print server

• -c 'help [<help option>]' — Prints out usage information. See "Printing Usage Information". Your built-in cheat sheet.
• -e — Echoes all commands to standard output.
• -n — No commands are executed; syntax checking only is performed. Dry run, but make it syntax.
• -z — No errors are written to standard error.
• --version — The qmgr command returns its PBS version information and exits. This option can only be used alone. Solo option only, no buddies. 💅

💬 DIRECTIVES 💬

Ok bestie, so a qmgr directive is basically a command + the object(s) it’s operating on + the attribute(s) you wanna change + the operator + the value(s) those attributes will take. For resources, you can also set the type and/or flag(s). Slay.

✍️ Directive Syntax ✍️

A directive ends at a newline or a semicolon (;). You can put multiple directives on one line. A directive can also stretch across lines by escaping the newline with a backslash (\).

Comments start with the # character and run to the end of the line. qmgr ignores comments and blank lines. Periodt.

🧱 Server, Scheduler, Queue, Vnode Directives 🧱

The syntax for operating on servers, schedulers, queues, and vnodes is:

<command> <object type> [<object name(s)>] [<attribute> <operator> <value>[,<attribute> <operator> <value>,...]]

🌈 Resource Directives 🌈

The syntax for operating on resources is:

<command> <resource name> [<resource name> ...] [type = <type>][,flag = <flag(s)>]

For the full resource lore, see pbs_resources.7B. 💅

🪝 Hook-only Directives 🪝

These directives apply only to hooks. Other directives apply to all objects like queues, resources, hooks, etc.

Syntax for importing and exporting site-defined hooks:

import hook <hook name> application/x-python <content-encoding> (<input file> | -)
export hook <hook name> <content-type> <content-encoding> [<output file>]

Syntax for importing a site-defined hook configuration file:

import hook <hook name> application/x-config <content-encoding> (<input file> | -)

Syntax for importing a built-in hook configuration file:

import pbshook <hook name> application/x-config <content-encoding> (<input file> | -)

🎀 Using Directives 🎀

You can use a directive straight from the shell command line, or from inside the qmgr session. Both are valid, bestie.

To use a directive from the command line, wrap the command and its arguments in single or double quotes:

qmgr -c '<command> <command arguments>'

For example, to have qmgr print server information and exit:

qmgr -c print server

To use a directive from inside the qmgr session, start qmgr first:

qmgr <return>

The qmgr session gives you a qmgr prompt:

Qmgr:

At the qmgr prompt, enter the directive — that’s the command and its arguments. For example, to enter the same print server directive:

Qmgr: print server

👑 Commands Used in Directives 👑

Commands can be abbreviated to their minimum unambiguous form. Commands apply to all target objects unless you explicitly limit them.

Here’s the command roster — effect and where the full description lives, no details dropped:

• active, a — Specifies active objects. See “Making Objects Active”.
• create, c — Creates object. See “Creating Objects (Server, Scheduler, Vnode, Queue, Hook)”.
• delete, d — Deletes object. See “Deleting Objects”.
• exit — Exits (quits) the qmgr session.
• export, e — Exports hook. See “Exporting Hooks”.
• help, h|? — Prints usage to stdout. See “Printing Usage Information”.
• import, i — Imports hook or configuration file. See “Importing Hooks” and “Importing Hook Configuration Files”.
• list, l — Lists object attributes and their values. See “Listing Objects and Their Attributes”.
• print, p — Prints creation and configuration commands. See “Printing Creation and Configuration Commands”.
• quit, q — Quits (exits) the qmgr session.
• set, s — Sets value of attribute. See “Setting Attribute and Resource Values”.
• unset, u — Unsets value of attribute. See “Unsetting Attribute and Resource Values”.

Arguments to Directive Commands 💬

Object Arguments to Directive Commands 🧸

okay so here's the tea: qmgr doesn't just sit there — it operates on objects. We're talking servers, schedulers, queues, vnodes, resources, hooks, and built-in hooks. And because typing full words is a lot, every one of them can be abbreviated inside a directive. Here's the whole lineup, with who's allowed to create/delete and who's allowed to modify each one:

• server (abbr s) — object: server. Can be created or deleted by: no one (it's created at installation). Can be modified by: Administrator, Operator, Manager.
• sched (abbr sc) — object: default scheduler. Can be created or deleted by: no one (created at installation). Can be modified by: Administrator, Operator, Manager.
  • same sched / sc, object: multisched — created or deleted by Administrator, Manager. Modified by Administrator, Operator, Manager.
• queue (abbr q) — object: queue. Created or deleted by Administrator, Operator, Manager. Modified by Administrator, Operator, Manager.
• node (abbr n) — object: vnode. Created or deleted by Administrator, Operator, Manager. Modified by Administrator, Operator, Manager.
• resource (abbr r) — object: resource. Created or deleted by Administrator, Manager. Modified by Administrator, Manager.
• hook (abbr h) — object: hook. Created or deleted by — Linux: root; Windows: installation account. Modified by — Linux: root; Windows: installation account.
• pbshook (abbr p) — object: built-in hook. Created or deleted by: no one (created at installation). Modified by — Linux: root; Windows: installation account.

---

Specifying Active Server 🌐

so qmgr does its thing on objects (queues, vnodes, etc.) at the active server. There is always at least one active server — the default server is the active server unless you've gone and made other servers active. And the default server is the one managing the host where the qmgr command runs, meaning it's the server specified in that host's pbs.conf file. Server names look like this:

<hostname>[:<port number>]

where:

• hostname — the fully-qualified domain name of the host on which the server is running, and
• port number — the port number to which to connect. If port number is not specified, the default port number, 15001, is used.

To specify the default server:

@default

To specify a named server:

@<server name>

To specify all active servers:

@active

---

Using Lists of Object Names 📋

In a qmgr directive, object name(s) is a list of one or more names of specific objects. The administrator specifies the name of an object when creating the object. The name list is in the form:

<object name>[@<server>][,<object name>[@<server>] ...]

where server is replaced in the directive with "default", "active", or the name of the server. And bestie, the name list must conform to the following — no exceptions:

• There must be no space between the object name and the @ sign.
• Name lists must not contain white space between entries.
• All objects in a list must be of the same type.
• Node attributes cannot be used as vnode names.

---

Specifying Object Type and Name 🏷️

You can specify objects in the following ways:

To act on the active objects of the named type, at the active server:

<object type>

For example, to list all active vnodes, along with their attributes, at the active server:

Qmgr: list node

To act on the active objects of the named type, at a specified server:

<object type> @<server name>

(note the space before the @ sign 👀)

For example, to list all active vnodes at the default server, along with their attributes:

Qmgr: list node @default

For example, to print out all queues at the default server, along with their attributes:

qmgr -c print queue @default

To act on a specific named object:

<object type> <object name>

For example, to list Node1 and its attributes:

Qmgr: list node Node1

To list queues workq, slowq, and fastq at the active server:

Qmgr: list queue workq,slowq,fastq

To act on the named object at the specified server:

<object type> <object name>@<server name>

For example, to list Node1 at the default server, along with the attributes of Node1:

Qmgr: list node Node1@default

To list queues Queue1 at the default server, Queue2 at Server2, and Queue3 at the active server:

Qmgr: list queue Queue1@default,Queue2@Server2,Queue3@active

---

Operators in Directive Commands ➕➖

In a qmgr directive, operator is the operation to be performed with the attribute and its value. Here are the operators, and yes there are exactly three:

• = — Sets the value of the attribute or resource. If the attribute or resource has an existing value, the current value is replaced with the new value.
• += — Increases the current value of the attribute or resource by the amount in the new value. When used for a string array, adds the new value as another string after a comma.
• -= — Decreases the current value of the attribute or resource by the specified amount. When used for a string array, removes the first matching string.

Example: Set routing destination for queue Queue1 to be Dest1:

Qmgr: set queue route_destinations = Dest1

Example: Add new routing destination for queue Queue1:

Qmgr: set queue route_destinations += Dest2

Example: Remove new routing destination for queue Queue1:

Qmgr: set queue route_destinations -= Dest2

⚠️ When setting numerical resource values, you can use only the equal sign ("="). That's it. That's the rule. 🫶

---

Windows Requirements For Directive Arguments 🪟

Under Windows, use double quotes when specifying arguments to qmgr. For example:

Qmgr: import hook hook1 application/x-python default “\Documents and Settings\pbsuser1\hook1.py\”

or

qmgr -c 'import hook hook1 application/x-python default “\Documents and Settings\pbsuser1\hook1.py\”'

🌸 Operating on Objects (Server, Scheduler, Vnode, Queue, Hook) 🌸

✨ Making Objects Active ✨

okay so making objects active is literally just building a little squad of same-type objects so you can hit them all with one command later. like if you're about to set the same attribute to the same value on several vnodes, you make all the target vnodes active first, then use a single command to set the attribute value — no repeating the command once per vnode. You can make any type of object active except for resources or hooks.

When an object is active, it gets acted upon when you specify its type but don't specify names. When you specify any object names in a directive, active objects are not operated on unless they're named in the directive. iykyk 💅

You can specify a list of active objects for each type of object. You can have active objects of multiple types at the same time. The active objects of one type have no effect on whether objects of another type are active. slay, independent little lists ✨

Objects are active only until the qmgr command is exited, so this feature can be used only at the qmgr prompt. 💀

Each time you make any objects active at a given server, that list of objects replaces any active objects of the same kind at that server. For example, if you have four queues at a particular server, and you make Q1 and Q2 active, then later make Q3 and Q4 active, the result is that Q3 and Q4 are the only active queues. the way it just swaps the whole squad 😭

You can make different objects be active at different servers simultaneously. For example, you can set vnodes N1 and N2 at the default server, and vnodes N3 and N4 at server Server2 to be active at the same time.

To make all objects inactive, quit qmgr. When you quit qmgr, any object that was active is no longer active. bye-bye active list 🫶

💅 Using the active Command 💅

To make the named object(s) of the specified type active:

active <object type> [<object name>[,<object name> ...]]

Example: To make queue Queue1 active:

Qmgr: active queue Queue1

Example: To make queues Queue1 and Queue2 at the active server be active, then enable them:

Qmgr: active queue Queue1,Queue2
Qmgr: set queue enabled=True

Example: To make queue Queue1 at the default server and queue Queue2 at Server2 be active:

Qmgr: active queue Queue1@default,Queue2@Server2

Example: To make vnodes N1, N2, N3, and N4 active, and then give them all the same value for their max_running attribute:

Qmgr: active node N1,N2,N3,N4
Qmgr: set node max_running = 2

To make all object(s) of the specified type at the specified server active:

active <object type> @<server name>

note space before @ sign ✨

Example: To make all queues at the default server active:

Qmgr: active queue @default

Example: To make all vnodes at server Server2 active:

Qmgr: active node @Server2

To report which objects of the specified type are active:

active <object type>

The qmgr command prints a list of names of active objects of the specified type to stdout. getting receipts, love that for us 💖

🎀 Creating Objects (Server, Scheduler, Vnode, Queue, Hook) 🎀

To create one new object of the specified type for each name, and give it the specified name:

create <object type> <object name>[,<object name> ...] [[<attribute> = <value>] [,<attribute> = <value>] ...]

Can be used only with multischeds, queues, vnodes, resources, and hooks. Cannot be used with built-in hooks. no built-in hook creation, bestie 🚫

For example, to create a multisched named multisched_1 at the active server:

Qmgr: create sched multisched_1

For example, to create a queue named Q1 at the active server:

Qmgr: create queue Q1

For example, to create a vnode named N1 and a vnode named N2:

Qmgr: create node N1,N2

For example, to create queue Queue1 at the default server and queue Queue2 at Server2:

Qmgr: create queue Queue1@default,Queue2@Server2

For example, to create vnodes named N1, N2, N3, and N4 at the active server, and to set their Mom attribute to Host1 and their max_running attribute to 1:

Qmgr: create node N1,N2,N3,N4 Mom=Host1, max_running = 1

For example, to create a host-level consumable string resource named "foo":

qmgr -c create resource foo type=string,flag=nh

All objects of the same type at a server must have unique names. For example, each queue at server Server1 must have a unique name. Objects at one server can have the same name as objects at another server. same name, different server? iconic, no conflict 💙

You can create multiple objects of the same type with a single command. You cannot create multiple types of objects in a single command.

To create multiple resources of the same type and flag, separate each resource name with a comma:

qmgr -c create resource <resource>[,<resource> ...]
type=<type>,flag=<flag(s)>

🌈 Examples of Creating Objects 🌈

Example: Create queue:

Qmgr: create queue fast priority=10,queue_type=e,enabled = true,max_running=0

Example: Create queue, set resources:

Qmgr: create queue little
Qmgr: set queue little resources_max.mem=8mw,resources_max.cput=10

🦋 Deleting Objects 🦋

To delete the named object(s):

delete <object type> <object name>[,<object name> ...]

When you delete more than one object, do not put a space after a comma. fr fr, no space 💀

Can be used only with queues, vnodes, resources, and hooks. Cannot be used with built-in hooks.

For example, to delete queue Q1 at the active server:

Qmgr: delete queue Q1

For example, to delete vnodes N1 and N2 at the active server:

Qmgr: delete node N1,N2

For example, to delete queue Queue1 at the default server and queue Queue2 at Server2:

Qmgr: delete queue Queue1@default,Queue2@Server2

For example, to delete resource "foo" at the active server:

Qmgr: delete resource foo

To delete the active objects of the specified type:

delete <object type>

For example, to delete the active queues:

Qmgr: delete queue

To delete the active objects of the specified type at the specified server:

delete <object type> @<server name>

For example, to delete the active queues at server Server2:

Qmgr: delete queue @Server2

You can delete multiple objects of the same type with a single command. You cannot delete multiple types of objects in a single command. To delete multiple resources, separate the resource names with commas.

For example:

Qmgr: delete resource r1,r2

You cannot delete a resource that is requested by a job or reservation, or that is set on a server, queue, or vnode. blocked by obligations, unfortunately 😭

🎀 Operating on Attributes and Resources 🎀

Okay bestie, so you can set attributes and resources for named objects, or for, like, all objects of a type. Both are valid, both are iconic. 💅

💖 Setting Attribute and Resource Values 💖

To set the value of the specified attribute(s) for the named object(s):

set <object type> <object name>[,<object name> ...] <attribute> =
<value> [,<attribute> = <value> ...]

Every attribute you name gets set for every object you name. So if you give three attributes and two objects, both objects get all three attributes. No cap, that's just how it works. ✨

To set the attribute value for all active objects when there are active objects of the type specified:

set <object type> <attribute> = <value>

To set the attribute value for all active objects at the specified server when there are active objects of the type specified:

set <object type> @<server name> <attribute> = <value>

For example, to set the amount of memory on a vnode:

Qmgr: set node Vnode1 resources_available.mem = 2mb

If the attribute describes a set of resources — think resources_available, resources_default, resources_max, resources_used, etc. — you write it in this form:

<attribute name>.<resource name>

And yes, you can have spaces between attribute=value pairs. Spaces are lowkey fine here. 🫶

✨ Examples of Setting Attribute Values ✨

Increase limit on queue:

Qmgr: set queue fast max_running +=2

Set software resource on mynode:

Qmgr: set node mynode resources_available.software = myapp=/tmp/foo

Set limit on queue:

Qmgr: set queue max_running = 10

Set vnode offline:

Qmgr: set node state = offline

🫶 Unsetting Attribute and Resource Values 🫶

You can use the qmgr command to unset attributes of any object, except for the type attribute of a built-in hook. That one is off-limits, bestie. 🚫

To unset the value of the specified attributes of the named object(s):

unset <object type> <object name>[,<object name> ...] <attribute>[,<attribute>...]

To unset the value of specified attributes of active objects:

unset <object type> <attribute>[,<attribute>...]

To unset the value of specified attributes of the named object:

unset <object type> <object name> <attribute>[,<attribute>...]

To unset the value of specified attributes of the named object:

unset <object type> @<server name> <attribute>[,<attribute>...]

🌸 Example of Unsetting Attribute Value 🌸

Unset limit on queue:

Qmgr: unset queue fast max_running

⚠️ Caveats and Restrictions for Setting Attribute and Resource Values ⚠️

If the value includes whitespace, commas, or other special characters — like the # character — the value string must be enclosed in single or double quotes. For example:

Qmgr: set node Vnode1 comment="Node will be taken offline Friday at 1:00 for memory upgrade."

You can set or unset attribute values for only one type of object in each command. One type per command, periodt. 💅

You can use the qmgr command to set attributes of any object, except for the type attribute of a built-in hook.

You can have spaces between attribute names. Yes, really. ✨

Attribute and resource values must conform to the format for the attribute or resource type.

Most of a vnode's attributes may be set using qmgr. However, some must be set on the individual execution host in local vnode definition files, NOT by using qmgr. That part is important — don't come for qmgr for the stuff it literally cannot do. 😭

🦋 Setting Resource Type and Flag(s) 🦋

You can use the qmgr command to set or unset the type and flag(s) for resources.

Resource types can be the following:

• string
• boolean
• string_array
• long
• size
• float

To set a resource type:

set resource <resource name> type = <type>

This sets the type of the named resource to the specified type. For example:

qmgr -c set resource foo type=string_array

🌈 Resource Accumulation Flags 🌈

The resource accumulation flag for a resource can be one of the following:

• (no flags) — Indicates a queue-level or server-level resource that is not consumable.
• fh — The amount is consumable at the host level for only the first vnode allocated to the job (vnode with first task.) Must be consumable or time-based. Cannot be used with Boolean or string resources.

This flag specifies that the resource is accumulated at the first vnode, meaning that the value of resources_assigned.<resource> is incremented only at the first vnode when a job is allocated this resource or when a reservation requesting this resource on this vnode starts.

• h — Indicates a host-level resource. Used alone, means that the resource is not consumable. Required for any resource that will be used inside a select statement. This flag selects hardware. This flag indicates that the resource must be requested inside of a select statement.

Example: for a Boolean resource named "green":

green type=boolean,flag=h

• nh — The amount is consumable at the host level, for all vnodes assigned to the job. Must be consumable or time-based. Cannot be used with Boolean or string resources.

This flag specifies that the resource is accumulated at the vnode level, meaning that the value of resources_assigned.<resource> is incremented at relevant vnodes when a job is allocated this resource or when a reservation requesting this resource on this vnode starts.

This flag is not used with dynamic consumable resources. A scheduler will not oversubscribe dynamic consumable resources.

• q — The amount is consumable at the queue and server level. When a job is assigned one unit of a resource with this flag, the resources_assigned.<resource> attribute at the server and any queue is incremented by one. Must be consumable or time-based.

This flag specifies that the resource is accumulated at the queue and server level, meaning that the value of resources_assigned.<resource> is incremented at each queue and at the server when a job is allocated this resource. When a reservation starts, allocated resources are added to the server's resources_assigned attribute.

This flag is not used with dynamic consumable resources. A scheduler will not oversubscribe dynamic consumable resources.

🔥 Resource Permission Flags 🔥

The permission flag for a resource can be one of the following:

• (no flag) — Users can view and request the resource, and qalter a resource request for this resource.
• i — "Invisible". Users cannot view or request the resource. Users cannot qalter a resource request for this resource.
• r — "Read only". Users can view the resource, but cannot request it or qalter a resource request for this resource.

To set resource flags, concatenate the flags you want without spaces or commas.

To set the flag(s) of the named resource to the specified flag(s):

set resource <resource name> flag=<flag(s)>

For example:

qmgr -c set resource foo flag=nhi

To set both type and flag(s):

set resource <resource name> type=<type>,flag=<flag(s)>

This sets the type and flag(s) of the named resource to the specified type and flag(s). For example:

qmgr -c set resource foo type=long,flag=nhi

You can set multiple resources by separating the names with commas. For example:

qmgr -c set resource r1,r2 type=long

You cannot set the type for a resource that is requested by a job or reservation, or set on a server, queue, or vnode.

You cannot set the flag(s) to h, nh, fh, or q for a resource that is requested by a job or reservation.

💅 Unsetting Resource Flag(s) 💅

You can use the qmgr command to unset the flag(s) for resources.

To unset the flag(s) of the named resource:

unset resource <resource name> flag

For example:

qmgr -c unset resource foo flag

You can unset the flag(s) of multiple resources by separating the resource names with commas. For example:

qmgr -c unset resource r1,r2 flag

You cannot unset the type for a resource.

You cannot unset the flag(s) for a resource that is requested by a job or reservation, or set on any server, queue, or vnode.

✨ Viewing Object, Attribute, and Resource Information ✨

okay bestie, this is the part where we look at stuff 👀 — object attributes, resource definitions, creation commands, all of it. Let's get into it.

🔍 Listing Objects and Their Attributes

You can use the qmgr command to list attributes of any object, including attributes at their default values. No cap, defaults show up too.

To list the attributes, with associated values, of the named object(s):

list <object type> <object name>[,<object name> ...]

To list values of the specified attributes of the named object:

list <object type> <object name> <attribute name>[, <attribute name>]...

To list attributes, with associated values, of active objects of the specified type at the active server:

list <object type>

To list all objects of the specified type at the specified server, with their attributes and the values associated with the attributes:

list <object type> @<server name>

To list attributes of the active server:

list server

If no server other than the default server has been made active, this lists attributes of the default server (it is the active server). 💅

To list attributes of the specified server:

list server <server name>

To list all attributes of all schedulers:

list sched

To list all attributes of the specified scheduler:

list sched <scheduler name>

To list all hooks, along with their attributes:

list hook

To list attributes of the specified hook:

list hook <hook name>

🌸 Examples of Listing Objects and Their Attributes

List serverA's schedulers' attributes:

Qmgr: list sched @serverA

List attributes for default server's scheduler(s):

Qmgr: l sched @default

List PBS version for default server's scheduler:

Qmgr: l sched @default pbs_version

List queues at a specified server:

Qmgr: list queue @server1

🎀 Listing Resource Definitions

You can use the qmgr list and print commands to list resource definitions showing resource name, type, and flag(s). So iconic of them honestly.

To list the name, type, and flag(s) of the named resource(s):

list resource <resource name>[,<resource name> ...]

or

print resource <resource name>[,<resource name> ...]

To list name, type, and flag(s) of custom resources only:

list resource

or

print resource

or

print server

(note that this also prints information for the active server)

To list all custom resources at the specified server, with their names, types, and flags:

list resource @<server name>

or

print resource @<server name>

When used by a non-privileged user, qmgr prints only resource definitions for resources that are visible to non-privileged users (those that do not have the i flag set). 🫶

👑 Printing Creation and Configuration Commands

This is for printing the creation commands for any object except for a built-in hook.

To print out the commands to create the named object(s) and set their attributes to their current values:

print <object type> <object name>[,<object name> ...]

where object name follows the name rules in "Using Lists of Object Names".

To print out the commands to create the named object and set its attributes to their current values:

print <object type> <object name> [<attribute name>[, <attribute name>]...]

where object name follows the name rules in "Using Lists of Object Names".

To print out the commands to create and configure the active objects of the named type:

print <object type>

To print out the commands to create and configure all of the objects of the specified type at the specified server:

print <object type> @<server name>

To print out the commands to create each queue, set the attributes of each queue to their current values, and set the attributes of the server to their current values:

print server

This is used for the server and queues, but not hooks.

Prints information for the active server. If there is no active server, prints information for the default server.

⚠️ Caveats for Viewing Information

Some attributes whose values are unset do not appear in the output of the qmgr command.

Definitions for built-in resources do not appear in the output of the qmgr command.

When a non-privileged user prints resource definitions, qmgr prints only resource definitions for resources that are visible to non-privileged users (those that do not have the i flag set).

💾 Saving and Re-creating Server and Queue Information

To save and recreate server and queue configuration, print the configuration information to a file, then read it back in later. For example, to save your configuration:

# qmgr -c print server > savedsettings

or

Qmgr: print server > savedsettings

When re-creating queue and server configuration, read the commands back into qmgr. For example:

qmgr < savedsettings

🪝 Operating on Hooks 🪝

Okay bestie, hooks era. This is where you create, delete, import, export, and generally give your hooks main character energy. Let’s go 💅

✨ Creating Hooks ✨

To create a hook, you literally just:

Qmgr: create hook <hook name>

For example:

Qmgr: create hook my_hook

Slay. New hook acquired. 🎀

🗑️ Deleting Hooks 🗑️

To delete a hook:

Qmgr: delete hook <hook name>

For example:

Qmgr: delete hook my_hook

Gone. Not me being dramatic, it’s just deleted. 💀

🎛️ Setting and Unsetting Hook Attributes 🎛️

To set a hook attribute:

Qmgr: set hook <hook name> <attribute> = <value>

To unset a hook attribute:

Qmgr: unset hook <hook name> <attribute>

Example: unset hook1’s alarm attribute, causing hook1’s alarm to revert to its default value of 30 seconds:

Qmgr: unset hook hook1 alarm

The way that default just snaps back into place? Iconic. ✨

📥 Importing Hooks 📥

This is for importing the contents of a site-defined hook. It cannot be used with built-in hooks. No cap.

To import a hook, you import the contents of a hook script into the hook. You must specify a filename that is locally accessible to qmgr and the PBS server.

Format for importing a site-defined hook:

import hook <hook name> application/x-python <content encoding> {<input file> | -}

This uses the contents of input file or stdin (-) as the contents of hook hook name.

The input file or stdin (-) data must have a format of content type and must be encoded with content encoding.

The allowed values for content encoding are default (7bit) and base64.

If the source of input is stdin (-) and content encoding is default, qmgr expects the input data to be terminated by EOF.

If the source of input is stdin (-) and content encoding is base64, qmgr expects input data to be terminated by a blank line.

input file must be locally accessible to both qmgr and the requested batch server.

A relative path input file is relative to the directory where qmgr was executed.

If a hook already has a content script, that is overwritten by this import call.

If the name in input file contains spaces as are used in Windows filenames, input file must be quoted.

There is no restriction on the size of the hook script. Big script? Fine. Huge script? Also fine. 🦋

🌸 Examples of Importing Hooks 🌸

Example: Given a Python script in ASCII text file hello.py, use its contents as the script contents of hook1:

#cat hello.py
import pbs

pbs.event().job.comment="Hello, world"

# qmgr -c 'import hook hook1 application/x-python default hello.py'

Example: Given a base64-encoded file hello.py.b64, qmgr unencodes the file’s contents, and then makes this the script contents of hook1:

# cat hello.py.b64
cHJpbnQgImhlbGxvLCB3b3JsZCIK

# qmgr -c 'import hook hook1 application/x-python base64 hello.py.b64'

Example: To create a provisioning hook called Provision_Hook, and import the ASCII hook script called master_provision.py located in /root/data/:

Qmgr: create hook Provision_Hook
Qmgr: import hook Provision_Hook application/x-python default /root/data/master_provision.py

Bestie, that path is doing the most, but it’s valid. 💜

📦 Importing and Exporting Hook Configuration Files 📦

📥 Importing Configuration Files 📥

This is for importing the contents of a site-defined or built-in hook configuration file. To import a hook configuration file, you import the contents of a file to a hook. You must specify a filename that is locally accessible to qmgr and the PBS server.

Format for importing a site-defined hook configuration file:

import hook <hook name> application/x-config <content encoding> {<config file>|-}

Format for importing a built-in hook configuration file:

import pbshook <hook name> application/x-config <content encoding> {<config file>|-}

This uses the contents of config file or stdin (-) as the contents of the configuration file for hook hook name.

The config file or stdin (-) data must have a format of content-type and must be encoded with content encoding.

The allowed values for content encoding are default (7bit) and base64.

If the source of input is stdin (-) and content encoding is default, qmgr expects the input data to be terminated by EOF.

If the source of input is stdin (-) and content encoding is base64, qmgr expects input data to be terminated by a blank line.

config file must be locally accessible to both qmgr and the requested batch server.

A relative path config file is relative to the directory where qmgr was executed.

If a hook already has a configuration file, that file is overwritten by this import call.

If the name in config file contains spaces as are used in Windows filenames, input file must be quoted.

There is no restriction on the size of the hook configuration file. 🫶

📤 Exporting Configuration Files 📤

Format for exporting a site-defined hook configuration file:

export hook <hook name> application/x-config default {<config file>|-}

Format for exporting a built-in hook configuration file:

export pbshook <hook name> application/x-config default {<config file>|-}

🧚 Hook Configuration File Format 🧚

PBS supports several file formats for configuration files. The format of the file is specified in its suffix. Formats can be any of the following:

• .ini
• .json
• .py (Python)
• .txt (generic, no special format)
• .xml
• No suffix: treat the input file as if it is a .txt file
• The dash (-) symbol: configuration file content is taken from STDIN. The content is treated as if it is a .txt file.

Example: To import a configuration file in .json format:

# qmgr -c import hook my_hook application/x-config default my_input_file.json

JSON girlies stay winning. 🌈

📤 Exporting Hooks 📤

This is for exporting the contents of a site-defined hook. It cannot be used with built-in hooks.

Format for exporting a hook:

export hook <hook name> <content type> <content encoding> [<output file>]

This dumps the script contents of hook hook name into output file, or stdout if output file is not specified.

The resulting output file or stdout data is of content type and content encoding.

The only content type currently supported is application/x-python.

The allowed values for content encoding are default (7bit) and base64.

output file must be a path that can be created by qmgr.

Any relative path output file is relative to the directory where qmgr was executed.

If output file already exists it is overwritten. If PBS is unable to overwrite the file due to ownership or permission problems, an error message is displayed in stderr.

If the output file name contains spaces like the ones used in Windows file names, output file must be enclosed in quotes.

🎀 Examples of Exporting Hooks 🎀

Example: Dump hook1’s script contents directly into a file hello.py.out:

# qmgr -c 'export hook hook1 application/x-python default hello.py'
# cat hello.py
import pbs
pbs.event().job.comment="Hello, world"

Example: To dump the script contents of a hook named hook1 into a file named hook1.py:

Qmgr: export hook hook1 application/x-python default hook1.py

File go brrr. 💅

🖨️ Printing Hook Information 🖨️

To print out the commands to create and configure all hooks, including their configuration files:

print hook

To print out the commands to create and configure the specified hook, including its configuration file:

print hook <hook name>

💾 Saving and Re-creating Hook Information 💾

You can save creation and configuration information for all hooks. For example:

# qmgr -c print hook > hook.qmgr

You can re-create all hooks and their configuration files. For example:

# qmgr < hook.qmgr

Save file bestie. Restore file bestie. Balance. ✨

🚫 Restrictions on Built-in Hooks 🚫

You cannot do the following with built-in hooks:

• Import a built-in hook
• Export a built-in hook
• Print creation commands for a built-in hook
• Create a built-in hook
• Delete a built-in hook
• Set the type attribute for a built-in hook

Built-ins said “no thank you” to all of that. Periodt. 💀

---

💬 Printing Usage Information 💬

You use the help command or a question mark (?) to invoke the qmgr built-in help function. You can request usage information for any of the qmgr commands, and for topics including attributes, operators, names, and values.

To print out usage information for the specified command or topic:

Qmgr: help [<command or topic>]

or

Qmgr: ? [<command or topic>]

For example, to print usage information for the set command:

qmgr
Qmgr: help set
Syntax: set object [name][,name...] attribute[.resource] OP value

Help me help you, bestie. 🫶

📥 Standard Input 📥

When you start a qmgr session, the qmgr command reads standard input for directives until it reaches end-of-file, or it reads the exit or quit command.

📤 Standard Output 📤

When you start a qmgr session, and standard output is connected to a terminal, qmgr writes a command prompt to standard output.

If you specify the -e option, qmgr echoes the directives it reads from standard input to standard output.

🚨 Standard Error 🚨

If you do not specify the -z option, the qmgr command writes a diagnostic message to standard error for each error occurrence.

🚦 Exit Status 🚦

• 0 — Success
• 1 — Error in parsing
• 2 — Error in execution
• 3 — Error connecting to server
• 4 — Error making object active
• 5 — Memory allocation error

Numbers don’t lie, bestie. Check your exit status. 👑

👀 See Also 👀

Peep these too:

• pbs_server_attributes.7B
• pbs_job_attributes.7B
• pbs_hook_attributes.7B
• pbs_node_attributes.7B
• pbs_queue_attributes.7B
• pbs_resv_attributes.7B
• pbs_sched_attributes.7B

---

That’s the whole qmgr(8B) page, bestie — source Local, dated 6 May 2020, page qmgr(8B). You ate. 💅✨🎀