.\" Copyright (C) 1994-2018 Altair Engineering, Inc. .\" For more information, contact Altair at www.altair.com. .\" .\" This file is part of the PBS Professional ("PBS Pro") software. .\" .\" Open Source License Information: .\" .\" PBS Pro is free software. You can redistribute it and/or modify it under the .\" terms of the GNU Affero General Public License as published by the Free .\" Software Foundation, either version 3 of the License, or (at your option) any .\" later version. .\" .\" PBS Pro is distributed in the hope that it will be useful, but WITHOUT ANY .\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS .\" FOR A PARTICULAR PURPOSE. .\" See the GNU Affero General Public License for more details. .\" .\" You should have received a copy of the GNU Affero General Public License .\" along with this program. If not, see . .\" .\" Commercial License Information: .\" .\" For a copy of the commercial license terms and conditions, .\" go to: (http://www.pbspro.com/UserArea/agreement.html) .\" or contact the Altair Legal Department. .\" .\" Altair’s dual-license business model allows companies, individuals, and .\" organizations to create proprietary derivative works of PBS Pro and .\" distribute them - whether embedded or bundled with other software - .\" under a commercial license agreement. .\" .\" Use of Altair’s trademarks, including but not limited to "PBS™", .\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's .\" trademark licensing policies. .\" .TH qmgr 8B "16 April 2018" Local "PBS Professional" .nf .SH NAME .B qmgr \- administrator's command interface for managing PBS .SH SYNOPSIS .B At shell command line: .br .B qmgr -c ' [-a] [-e] [-n] [-z]' .br .B qmgr -c 'help []' .br .B qmgr .br .B qmgr --version .br .B In qmgr session: .br [-a] [-e] [-n] [-z] .br help .SH DESCRIPTION The PBS manager command, qmgr, provides a command-line interface to parts of PBS. The .B 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. 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. .B Modes of Operation .br When you type qmgr -c '', .B qmgr performs its task and then exits. When you type qmgr , .B qmgr starts a session and presents you with its command line prompt. The .B 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. For a qmgr prompt, type: .br .B \ \ \ qmgr .br You will see the qmgr prompt: .br .B \ \ \ Qmgr: .br .B Required Privilege .br 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. 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. Under Linux, root privilege is required in order to create hooks, or operate on hooks or the .I job_sort_formula server attribute. Under Windows, this must be done from the installation account. 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. Users without manager or operator privilege cannot view custom resources or resource definitions which were created to be invisible to users. .B When To Run qmgr At Server Host .br When operating on hooks or on the .I job_sort_formula server attribute, the qmgr command must be run at the server host. .B Reusing and Editing the qmgr Command Line .br 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 ! 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: .br .B \ \ \ !123 .br You can see the last m commands by typing 'history m'. For example, to see the last 6 commands, type the following: .br .B \ \ \ history 6 .br 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. You can edit the qmgr command line using the backspace and delete keys, and you can insert characters anywhere in a command line. 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. 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. Each user's history is unique to that user on that host. 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. .B The qmgr History File .br 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_. 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 .SH OPTIONS TO qmgr The following table lists the options to qmgr: .nf .B Option \ \ \ \ \ \ \ \ \ \ \ Action ----------------------------------------------------------------------- Starts a qmgr session and presents user with qmgr prompt ----------------------------------------------------------------------- -a Aborts qmgr on any syntax errors or any requests rejected by a server. ----------------------------------------------------------------------- -c '' Executse a single command (directive) and exit qmgr. The directive must be enclosed in single or double quote marks, for example: .B \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qmgr -c "print server" ----------------------------------------------------------------------- -c 'help Prints out usage information. []' See "Printing Usage Information" ----------------------------------------------------------------------- -e Echoes all commands to standard output ----------------------------------------------------------------------- -n No commands are executed; syntax checking only is performed ----------------------------------------------------------------------- -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 ----------------------------------------------------------------------- .SH Directives A qmgr .I directive is a command together with the object(s) to be operated on, the attribute(s) belonging to the object that is to be changed, the operator, and the value(s) the attribute(s) will take. In the case of resources, you can set the type and/or flag(s). .B Directive Syntax .br A directive is terminated by a newline or a semicolon (";"). Multiple directives may be entered on a single line. A directive may extend across lines by escaping the newline with a backslash ("\"). Comments begin with the "#" character and continue to the end of the line. Comments and blank lines are ignored by qmgr. .B Server, Scheduler, Queue, Vnode Directives .br Syntax for operating on servers, schedulers, queues, vnodes: .RS 3 .I [] [ [, ,...]] .RE .B Resource Directives .br Syntax for operating on resources: .nf .RS 3 .I [ ...] [type = ],[,flag = ] .RE .fi For information about resources, see .I pbs_resources.7B. .B Hook Directives .br Syntax for operating on hooks: .nf .RS 3 .I import hook application/x-python ( | -) .I import hook application/x-config ( | -) .I export hook [] .fi .RE .B Using Directives .br You can use a directive from the shell command line or from within the qmgr session. To use a directive from the command line, enclose the command and its arguments in single or double quotes. .br .I \ \ \ qmgr -c ' ' For example, to have qmgr print server information and exit: .br .B \ \ \ qmgr -c "print server" To use a directive from within the qmgr session, first start qmgr: .br .I \ \ \ qmgr The qmgr session presents a qmgr prompt: .br .B \ \ \ Qmgr: At the qmgr prompt, enter the directive (a command and its arguments). For example, to enter the same "print server" directive: .br .B \ \ \ Qmgr: print server .B Commands Used in Directives .br Commands can be abbreviated to their minimum unambiguous form. Commands apply to all target objects unless explicitly limited. The following table lists the commands, briefly tells what they do, and lists the section with the full description: .nf .B Command \ Abbr \ Effect \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ See Description ----------------------------------------------------------------------- active a Specifies active objects "Making Objects Active" ----------------------------------------------------------------------- create c Creates object "Creating Objects (Server, Scheduler, Vnode, Queue, Hook)" ----------------------------------------------------------------------- delete d Deletes object "Deleting Objects" ----------------------------------------------------------------------- exit Exits (quits) the qmgr session ----------------------------------------------------------------------- export e Exports hook "Exporting Hooks" ----------------------------------------------------------------------- help h|? Prints usage to stdout "Printing Usage Information" ----------------------------------------------------------------------- import i Imports hook or "Importing Hooks" configuration file "Importing Hook Configuration Files" ----------------------------------------------------------------------- list l Lists object attributes "Listing Objects and Their and their values Attributes" ----------------------------------------------------------------------- print p Prints creation and "Printing Creation and configuration commands Configuration Commands" ----------------------------------------------------------------------- quit q Quits (exits) the qmgr session ----------------------------------------------------------------------- set s Sets value of attribute "Setting Attribute and Resource Values" ----------------------------------------------------------------------- unset u Unsets value of attribute "Unsetting Attribute and Resource Values" ----------------------------------------------------------------------- .SH Arguments to Directive Commands .B Object Arguments to Directive Commands .br The qmgr command can operate on objects (servers, schedulers, queues, vnodes, resources, hooks, and built-in hooks). Each of these can be abbreviated inside a directive. The following table lists the objects and their abbreviations: .nf .B Object \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Can Be Created or \ \ \ \ \ Can Be .B Name \ \ \ \ \ Abbr \ Object \ \ \ Deleted By: \ \ \ \ \ \ \ \ \ \ \ \ Modified By: ----------------------------------------------------------------------- server s server No one (created Administrator, at installation) Operator, Manager ----------------------------------------------------------------------- sched sc default No one (created Administrator, scheduler at installation) Operator, Manager -------------------------------------------------------- multisched Administrator, Manager Administrator, Operator, Manager ----------------------------------------------------------------------- queue q queue Administrator, Administrator, Operator, Manager Operator, Manager ----------------------------------------------------------------------- node n vnode Administrator, Administrator, Operator, Manager Operator, Manager ----------------------------------------------------------------------- resource r resource Administrator, Manager Administrator, Manager ----------------------------------------------------------------------- hook h hook Linux: root Linux: root Windows: installation Windows: installation account account ----------------------------------------------------------------------- pbshook p built-in No one (created Linux: root hook at installation) Windows: installation account ----------------------------------------------------------------------- .B Specifying Active Server .br The qmgr command operates 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 other servers have been made active. The default server is the server managing the host where the qmgr command runs, meaning it is the server specified in that host's pbs.conf file. Server names have the following format: .br .I \ \ \ [:] .br where .I hostname is the fully-qualified domain name of the host on which the server is running and .I port number is the port number to which to connect. If .I port number is not specified, the default port number, 15001, is used. To specify the default server: .br .I \ \ \ @default To specify a named server: .br .I \ \ \ @ To specify all active servers: .br .I \ \ \ @active .B Using Lists of Object Names .br In a qmgr directive, .I 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: .br .I \ \ \ [@][,[@] ...] .br where .I server is replaced in the directive with "default", "active", or the name of the server. The name list must conform to the following: .RS 3 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. .RE .B Specifying Object Type and Name .br You can specify objects in the following ways: To act on the active objects of the named type, at the active server: .RS 3 .I For example, to list all active vnodes, along with their attributes, at the active server: .br .B Qmgr: list node .RE To act on the active objects of the named type, at a specified server: .RS 3 .I @ (note space before @ sign) For example, to list all active vnodes at the default server, along with their attributes: .br .B Qmgr: list node @default For example, to print out all queues at the default server, along with their attributes: .br .B qmgr -c "print queue @default" .RE To act on a specific named object: .RS 3 .I For example, to list Node1 and its attributes: .br .B Qmgr: list node Node1 To list queues workq, slowq, and fastq at the active server: .br .B Qmgr: list queue workq,slowq,fastq .RE To act on the named object at the specified server: .RS 3 .I @ For example, to list Node1 at the default server, along with the attributes of Node1: .br .B Qmgr: list node Node1@default To list queues Queue1 at the default server, Queue2 at Server2, and Queue3 at the active server: .br .B Qmgr: list queue Queue1@default,Queue2@Server2,Queue3@active .RE .B Operators in Directive Commands .br In a qmgr directive, .I operator is the operation to be performed with the attribute and its value. Operators are listed here: .nf .B Operator \ \ Effect ----------------------------------------------------------------------- = 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: .br .B \ \ \ Qmgr: set queue route_destinations = Dest1 Example: Add new routing destination for queue Queue1: .br .B \ \ \ Qmgr: set queue route_destinations += Dest2 Example: Remove new routing destination for queue Queue1: .br .B \ \ \ Qmgr: set queue route_destinations -= Dest2 When setting numerical resource values, you can use only the equal sign ("="). .B Windows Requirements For Directive Arguments .br Under Windows, use double quotes when specifying arguments to qmgr. For example: .br Qmgr: import hook hook1 application/x-python default \*(lq\\Documents and Settings\\pbsuser1\\hook1.py\\\*(rq .br or .br qmgr -c 'import hook hook1 application/x-python default \*(lq\\Documents and Settings\\pbsuser1\\hook1.py\\\*(rq' .SH Operating on Objects (Server, Scheduler, Vnode, Queue, Hook) .B Making Objects Active .br Making objects active is a way to set up a list of objects, all of the same type, on which you can then use a single command. For example, if you are going to set the same attribute to the same value on several vnodes, you can make all of the target vnodes active before using a single command to set the attribute value, instead of having to give the command once for each vnode. You can make any type of object active except for resources or hooks. When an object is active, it is acted upon when you specify its type but do not specify names. When you specify any object names in a directive, active objects are not operated on unless they are named in the directive. 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. 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. 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. .B Using the active Command .br To make the named object(s) of the specified type active: .RS 3 .I active [[, ...]] Example: To make queue Queue1 active: .br .B Qmgr: active queue Queue1 Example: To make queues Queue1 and Queue2 at the active server be active, then enable them: .br .B Qmgr: active queue Queue1,Queue2 .br .B Qmgr: set queue enabled=True Example: To make queue Queue1 at the default server and queue Queue2 at Server2 be active: .br .B 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 .I max_running attribute: .br .B Qmgr: active node N1,N2,N3,N4 .br .B Qmgr: set node max_running = 2 .RE To make all object(s) of the specified type at the specified server active: .RS 3 .I active @ (note space before @ sign) Example: To make all queues at the default server active: .br .B Qmgr: active queue @default Example: To make all vnodes at server Server2 active: .br .B Qmgr: active node @Server2 .RE To report which objects of the specified type are active: .RS 3 .I active The qmgr command prints a list of names of active objects of the specified type to stdout. .RE .B Creating Objects (Server, Scheduler, Vnode, Queue, Hook) .br To create one new object of the specified type for each name, and give it the specified name: .RS 3 .I create [, ...] [[ = ] [, = ] ...] .RE Can be used only with multischeds, queues, vnodes, resources, and hooks. Cannot be used with built-in hooks. .RS 3 For example, to create a multisched named multisched_1 at the active server: .br .B Qmgr: create sched multisched_1 For example, to create a queue named Q1 at the active server: .br .B Qmgr: create queue Q1 For example, to create a vnode named N1 and a vnode named N2: .br .B Qmgr: create node N1,N2 For example, to create queue Queue1 at the default server and queue Queue2 at Server2: .br .B 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 .I max_running attribute to 1: .br .B Qmgr: create node N1,N2,N3,N4 Mom=Host1, max_running = 1 For example, to create a host-level consumable string resource named "foo": .br .B qmgr -c "create resource foo type=string,flag=nh" .RE 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. 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: .RS 3 .I qmgr -c "create resource [, ...] type=,flag=" .RE .B Examples of Creating Objects .br Example: Create queue: .RS 3 .B Qmgr: create queue fast priority=10,queue_type=e,enabled = true,max_running=0 .RE Example: Create queue, set resources: .RS 3 .B Qmgr: create queue little .br .B Qmgr: set queue little resources_max.mem=8mw,resources_max.cput=10 .RE .B Deleting Objects .br To delete the named object(s): .RS 3 .I delete [, ...] When you delete more than one object, do not put a space after a comma. 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: .br .B Qmgr: delete queue Q1 For example, to delete vnodes N1 and N2 at the active server: .br .B Qmgr: delete node N1,N2 For example, to delete queue Queue1 at the default server and queue Queue2 at Server2: .br .B Qmgr: delete queue Queue1@default,Queue2@Server2 For example, to delete resource "foo" at the active server: .br .B Qmgr: delete resource foo .RE To delete the active objects of the specified type: .RS 3 .I delete For example, to delete the active queues: .br .B Qmgr: delete queue .RE To delete the active objects of the specified type at the specified server: .RS 3 .I delete @ For example, to delete the active queues at server Server2: .br .B Qmgr: delete queue @Server2 .RE 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. .RS 3 For example: .br .B Qmgr: delete resource r1,r2 .RE You cannot delete a resource that is requested by a job or reservation, or that is set on a server, queue, or vnode. .SH Operating on Attributes and Resources You can specify attributes and resources for named objects or for all objects of a type. .B Setting Attribute and Resource Values .br To set the value of the specified attribute(s) for the named object(s): .RS 3 .I set [, ...] = [, = ...] .RE Each specified attribute is set for each named object, so if you specify three attributes and two objects, both objects get all three attributes set. To set the attribute value for all active objects when there are active objects of the type specified: .br .I \ \ \ set = To set the attribute value for all active objects at the specified server when there are active objects of the type specified: .RS 3 .I set @ = For example, to set the amount of memory on a vnode: .br .B Qmgr: set node Vnode1 resources_available.mem = 2mb .RE If the attribute is one which describes a set of resources such as .I resources_available, resources_default, resources_max, resources_used, etc., the attribute is specified in the form: .br .I \ \ \ . You can have spaces between attribute=value pairs. .B Examples of Setting Attribute Values .br Increase limit on queue: .RS 3 .B Qmgr: set queue fast max_running +=2 .RE Set software resource on mynode: .RS 3 .B Qmgr: set node mynode resources_available.software = "myapp=/tmp/foo" .RE Set limit on queue: .RS 3 .B Qmgr: set queue max_running = 10 .RE Set vnode offline: .RS 3 .B Qmgr: set node state = "offline" .RE .B Unsetting Attribute and Resource Values .br You can use the qmgr command to unset attributes of any object, except for the .I type attribute of a built-in hook. To unset the value of the specified attributes of the named object(s): .nf .RS 3 .I unset [, ...] [,...] .RE To unset the value of specified attributes of active objects: .br .I \ \ \ unset [,...] To unset the value of specified attributes of the named object: .br .I \ \ \ unset [,...] To unset the value of specified attributes of the named object: .br .I \ \ \ unset @ [,...] .B Example of Unsetting Attribute Value .br Unset limit on queue .br .B \ \ \ Qmgr: unset queue fast max_running .B Caveats and Restrictions for Setting Attribute and Resource Values .br If the value includes whitespace, commas or other special characters, such as the # character, the value string must be enclosed in single or double quotes. For example: .RS 3 .B Qmgr: set node Vnode1 comment="Node will be taken offline Friday at 1:00 for memory upgrade." .RE You can set or unset attribute values for only one type of object in each command. You can use the qmgr command to set attributes of any object, except for the .I type attribute of a built-in hook. You can have spaces between attribute names. 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. See the .I PBS Professional Administrator's Guide. .B Setting Resource Type and Flag(s) .br You can use the qmgr command to set or unset the type and flag(s) for resources. Resource types can be the following: .RS 3 string .br boolean .br string_array .br long .br size .br float .RE To set a resource type: .br .I \ \ \ set resource type = Sets the type of the named resource to the specified type. For example: .br .B \ \ \ qmgr -c "set resource foo type=string_array" .B Resource Accumulation Flags The resource accumulation flag for a resource can be one of the following: .B Flag \ \ \ \ \ \ \ Meaning ----------------------------------------------------------------------- (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. 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": .B \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 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. 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. 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. 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. ----------------------------------------------------------------------- .B Resource Permission Flags The permission flag for a resource can be one of the following: .B Flag \ \ \ \ \ \ \ Meaning ----------------------------------------------------------------------- (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): .RS 3 .I set resource flag = For example: .br .B qmgr -c "set resource foo flag=nhi" .RE To set both type and flag(s): .RS 3 .I set resource type=, flag = Sets the type and flag(s) of the named resource to the specified type and flag(s). For example: .br .B qmgr -c "set resource foo type=long,flag=nhi" .RE You can set multiple resources by separating the names with commas. .RS 3 For example: .br .B qmgr -c "set resource r1,r2 type=long" .RE 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. .B Unsetting Resource Flag(s) .br You can use the qmgr command to unset the flag(s) for resources. To unset the flag(s) of the named resource: .RS 3 .I unset resource flag For example: .br .B qmgr -c "unset resource foo flag" .RE You can unset the flag(s) of multiple resources by separating the resource names with commas. .RS 3 For example: .br .B qmgr -c "unset resource r1,r2 flag" .RE 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. .SH Viewing Object, Attribute, and Resource Information .B Listing Objects and Their Attributes .br You can use the qmgr command to list attributes of any object, including attributes at their default values. To list the attributes, with associated values, of the named object(s): .RS 3 .I list [, ...] .RE To list values of the specified attributes of the named object: .RS 3 .I list [, ]... .RE To list attributes, with associated values, of active objects of the specified type at the active server: .br .I \ \ \ list To list all objects of the specified type at the specified server, with their attributes and the values associated with the attributes: .br .I \ \ \ list @ To list attributes of the active server: .RS 3 .I list server .br If no server other than the default server has been made active, lists attributes of the default server (it is the active server). .RE To list attributes of the specified server: .br .I \ \ \ list server To list all attributes of all schedulers: .br .I \ \ \ list sched To list all attributes of the specified scheduler: .br .I \ \ \ list sched To list all hooks, along with their attributes: .br .I \ \ \ list hook To list attributes of the specified hook: .br .I \ \ \ list hook .B Examples of Listing Objects and Their Attributes .br List serverA's schedulers' attributes: .br .B \ \ \ Qmgr: list sched @serverA List attributes for default server's scheduler(s): .br .B \ \ \ Qmgr: l sched @default List PBS version for default server's scheduler: .br .B \ \ \ Qmgr: l sched @default pbs_version List queues at a specified server: .br .B \ \ \ Qmgr: list queue @server1 .B Listing Resource Definitions .br You can use the qmgr .B list and .B print commands to list resource definitions showing resource name, type, and flag(s). To list the name, type, and flag(s) of the named resource(s): .RS 3 .I list resource [, ...] .RE or .RS 3 .I print resource [, ...] .RE To list name, type, and flag(s) of custom resources only: .RS 3 .I list resource .RE or .RS 3 .I print resource .RE or .RS 3 .I print server (note that this also prints information for the active server) .RE To list all custom resources at the specified server, with their names, types, and flags: .RS 3 .I list resource @ .RE or .RS 3 .I print resource @ .RE 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 .B i flag set). .B Printing Creation and Configuration Commands .br 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: .RS 3 .I print [, ...] .br where object name follows the name rules in "Using Lists of Object Names". .RE To print out the commands to create the named object and set its attributes to their current values: .RS 3 .I print [[, ]...] .br where object name follows the name rules in "Using Lists of Object Names". .RE To print out the commands to create and configure the active objects of the named type: .br .I \ \ \ print To print out the commands to create and configure all of the objects of the specified type at the specified server: .br .I \ \ \ print @ 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: .br .I \ \ \ 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. .B Caveats for Viewing Information .br 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 .B i flag set). .SH 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: .br .B \ \ \ # qmgr -c "print server" > savedsettings .br or .br .B \ \ \ Qmgr: print server > savedsettings When re-creating queue and server configuration, read the commands back into qmgr. For example: .br .B \ \ \ qmgr < savedsettings .SH Operating on Hooks .B Creating Hooks .br To create a hook: .RS 3 .I Qmgr: create hook For example: .br .B Qmgr: create hook my_hook .RE .B Deleting Hooks .br To delete a hook: .RS 3 .I Qmgr: delete hook For example: .br .B Qmgr: delete hook my_hook .RE .B Setting and Unsetting Hook Attributes .br To set a hook attribute: .RS 3 .I Qmgr: set hook = .RE To unset a hook attribute: .RS 3 .I Qmgr: unset hook Example: Unset hook1's .I alarm attribute, causing hook1's alarm to revert to its default value of 30 seconds: .br .B Qmgr: unset hook hook1 alarm .RE .B Importing Hooks .br For importing the contents of a hook. Cannot be used with built-in hooks. 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 hook: .RS 3 .I import hook application/x-python { | -} .RE This uses the contents of .I input file or stdin (-) as the contents of hook .I hook name. The .I input file or stdin (-) data must have a format of .I content type and must be encoded with .I content encoding. The allowed values for .I content encoding are "default" (7bit) and "base64". If the source of input is stdin (-) and .I content encoding is "default", qmgr expects the input data to be terminated by EOF. If the source of input is stdin (-) and .I content encoding is "base64", qmgr expects input data to be terminated by a blank line. .I input file must be locally accessible to both qmgr and the requested batch server. A relative path .I 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 .I 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. .B Examples of Importing Hooks .br 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" .RS 3 .B # qmgr -c 'import hook hook1 application/x-python default hello.py' .RE Example: Given a base64-encoded file "hello.py.b64", qmgr unencodes the file's contents, and then makes this the script contents of hook1: .B \ \ \ # cat hello.py.b64 .br cHJpbnQgImhlbGxvLCB3b3JsZCIK .RS 3 .B # qmgr -c 'import hook hook1 application/x-python base64 hello.py.b64' .RE Example: To create a provisioning hook called Provision_Hook, and import the ASCII hook script called "master_provision.py" located in /root/data/: .RS 3 .B Qmgr: create hook Provision_Hook .br .B Qmgr: import hook Provision_Hook application/x-python default /root/data/master_provision.py .RE .B Importing Hook Configuration Files .br For importing the contents of a 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 hook configuration file: .RS 3 .I import hook application/x-config {|-} .RE This uses the contents of .I config file or stdin (-) as the contents of the configuration file for hook .I hook name. The .I config file or stdin (-) data must have a format of .I content-type and must be encoded with .I content encoding. The allowed values for .I content encoding are "default" (7bit) and "base64". If the source of input is stdin (-) and .I content encoding is "default", qmgr expects the input data to be terminated by EOF. If the source of input is stdin (-) and .I content encoding is "base64", qmgr expects input data to be terminated by a blank line. .I config file must be locally accessible to both qmgr and the requested batch server. A relative path .I 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 .I 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. .B Hook Configuration File Format .br 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: .RS 3 .ini .br .json .br .py (Python) .br .txt (generic, no special format) .br .xml .RE .RS 4 No suffix: treat the input file as if it is a .txt file .br The dash (-) symbol: configuration file content is taken from STDIN. The content is treated as if it is a .txt file. .RE Example: To import a configuration file in .json format: .RS 3 .I # qmgr -c "import hook my_hook application/x-config default my_input_file.json" .RE .B Exporting Hooks .br For exporting the contents of a hook. Cannot be used with built-in hooks. Format for exporting a hook: .br .RS 3 .I export hook [] .RE This dumps the script contents of hook .I hook name into .I output file, or stdout if .I output file is not specified. The resulting .I output file or stdout data is of .I content type and .I content encoding. The only .I content type currently supported is "application/x-python". The allowed values for .I content encoding are "default" (7bit) and "base64". .I output file must be a path that can be created by qmgr. Any relative path .I output file is relative to the directory where qmgr was executed. If .I 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 .I output file name contains spaces like the ones used in Windows file names, .I output file must be enclosed in quotes. .B Examples of Exporting Hooks .br Example: Dump hook1's script contents directly into a file "hello.py.out": .RS 3 .B # qmgr -c 'export hook hook1 application/x-python default hello.py' .br .B # cat hello.py .br import pbs .br pbs.event().job.comment="Hello, world" .RE Example: To dump the script contents of a hook 'hook1' into a file in "\My Hooks\hook1.py": .RS 3 .B Qmgr: export hook hook1 application/x-python default "\My Hooks\hook1.py" .RE .B Printing Hook Information .br To print out the commands to create and configure all hooks, including their configuration files: .br .I \ \ \ print hook To print out the commands to create and configure the specified hook, including its configuration file: .br .I \ \ \ print hook .B Saving and Re-creating Hook Information .br You can save creation and configuration information for all hooks. For example: .br .B \ \ \ # qmgr -c "print hook" > hook.qmgr You can re-create all hooks and their configuration files. For example: .br .B \ \ \ # qmgr < hook.qmgr .B Restrictions on Built-in Hooks .br You cannot do the following with built-in hooks: .RS 3 Import a built-in hook .br Export a built-in hook .br Print creation commands for a built-in hook .br Create a built-in hook .br Delete a built-in hook .br Set the type attribute for a built-in hook .RE .SH 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: .br .B \ \ \ Qmgr: help [] .br or .br .B \ \ \ Qmgr: ? [] For example, to print usage information for the set command: .RS 3 .B qmgr .br .B Qmgr: help set .br Syntax: set object [name][,name...] attribute[.resource] OP value .RE .SH 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. .SH 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. .SH Standard Error If you do not specify the -z option, the qmgr command writes a diagnostic message to standard error for each error occurrence. .SH Exit Status .IP 0 5 Success .IP 1 5 Error in parsing .IP 2 5 Error in execution .IP 3 5 Error connecting to server .IP 4 5 Error making object active .IP 5 5 Memory allocation error .SH See Also .I The PBS Professional Administrator's Guide, and pbs_server_attributes.7B, pbs_job_attributes.7B, pbs_hook_attributes.7B, pbs_node_attributes.7B, pbs_queue_attributes.7B, pbs_resv_attributes.7B, and pbs_sched_attributes.7B