pbs_rsub(1B)

📦 version 23.06.06-unstable-2026-04, in nixos 26.05, nixpkgs unstable

💅 pbs_rsub — it's giving "make a reservation" (PBS Professional, pbs_rsub(1B))

okay so bestie, buckle up 🎀 this is pbs_rsub, the PBS Professional command that makes reservations. Yes like a restaurant reservation but for compute nodes and it's so much cooler. Let's go ✨

✨ NAME ✨

pbs_rsub — create a PBS reservation 🗓️💖

🌸 SYNOPSIS 🌸

For advance and standing reservations:

pbs_rsub [-D <duration>] [-E <end time>] [-g <group list>]
         [-G <auth group list>] [-H <auth host list>] [-I <block time>]
         ] [-l <placement>] [-l <resource request>] [-m <mail events>]
         [-M <mail list>] [-N <reservation name>] [-q <destination>] [-r
         <recurrence rule>] [-R <start time>]  [-u <user list>] [-U
         <auth user list>] [-W <attribute value list>]

For job-specific now reservations:

pbs_rsub [-I <block time>] [-m <mail events>] [-M <mail list>]
         --job <job ID>

For maintenance reservations:

pbs_rsub [-D <duration>] [-E <end time>] [--hosts <host list>]
         [-N <reservation name>] [-q <destination>] [-R <start time>]

For version information:

pbs_rsub --version

(yeah there's a lil stray ] in that first block, that's literally how it ships, we don't touch it 💀)

🔥 DESCRIPTION 🔥

The pbs_rsub command creates reservations. And not just one kind — it does advance, standing, job-specific now, job-specific ASAP, or maintenance reservations. Five flavors, all iconic 👑

  • An advance reservation reserves specific resources for the requested time period.
  • A standing reservation reserves specific resources for recurring time periods.
  • A job-specific now reservation reserves the resources being used by a specific job in case the job fails and needs to be re-submitted, allowing it to run again without having to wait to be scheduled. The reservation is created and starts running when a queued job starts running, or immediately when you use pbs_rsub --job <job ID> on a running job.
  • A job-specific ASAP reservation is created from a queued job via pbs_rsub -Wqmove=<job ID>. The reservation runs as soon as possible, and the job is moved into the reservation. The reservation is created using the same resources as the job requested.
  • A job-specific start reservation is created immediately using a running job's resources, and the job is moved into the reservation. You create job-specific start reservations using qsub -Wcreate_resv_from_job=true on a running job. See the qsub command.
  • A maintenance reservation reserves the specified hosts for the specified time regardless of other circumstances.

Advance, standing, and job-specific reservations are "job reservations", to distinguish them from maintenance reservations. When a reservation is created, it has an associated queue.

Wanna snoop on a reservation? Use the pbs_rstat command 🔍

Wanna delete one? Use pbs_rdel. Do not use qdel. Like, do not. 🙅‍♀️

⚠️ heads up: the behavior of the pbs_rsub command may be affected by any site hooks. Site hooks can modify the reservation's attributes.

🦋 Job Reservations 🦋

After an advance or standing reservation is requested, it is either confirmed or denied. A job-specific now reservation is created when the job is started and confirmed immediately. A job-specific ASAP reservation is scheduled as soon as possible. Once the reservation has been confirmed, authorized users submit jobs to the reservation's queue via qsub and qmove.

A confirmed job reservation will accept jobs at any time. The jobs in its queue can run only during the reservation period. Jobs in a single advance reservation or job-specific reservation can run only during the reservation's time slot, and jobs in a standing reservation can run only during the time slots of occurrences of the standing reservation.

When an advance reservation ends, all of its jobs are deleted, whether running or queued 😭. When an occurrence of a standing reservation ends, only its running jobs are deleted; those jobs still in the queue are not deleted. (weird but true, that's the rule 💅)

🧚 Maintenance Reservations 🧚

You can create maintenance reservations using pbs_rsub --hosts <host list>. Maintenance reservations are designed to make the specified hosts available for the specified amount of time, regardless of what else is happening:

  • You can create a maintenance reservation that includes or is made up of vnodes that are down or offline.
  • Maintenance reservations ignore the value of a vnode's resv_enable attribute.
  • PBS immediately confirms any maintenance reservation.
  • Maintenance reservations take precedence over other reservations; if you create a maintenance reservation that overlaps an advance or standing job reservation, the overlapping vnodes become unavailable to the job reservation, and the job reservation becomes degraded. PBS looks for replacement vnodes.

PBS will not start any new jobs on vnodes overlapping or in a maintenance reservation. However, jobs that were already running on overlapping vnodes continue to run; you can let them run or requeue them.

You cannot specify place or select for a maintenance reservation; these are created by PBS:

  • PBS creates the reservation's placement specification so that hosts are assigned exclusively to the reservation. The placement specification is always the following:
-lplace=exclhost
  • PBS sets the reservation's resv_nodes attribute value so that all CPUs on the reserved hosts are assigned to the maintenance reservation. The select specification is always the following:
-lselect = host=<host1>:ncpus= <number of CPUs at host1>
+host=<host2>:ncpus= <number of CPUs at host2>+...

Maintenance reservations are prefixed with M. A maintenance reservation ID has the format:

M<unique integer>.<server name>

Creating a maintenance reservation does not trigger a scheduling cycle. (it just vibes 😌)

👑 You must have manager or operator privilege to create a maintenance reservation.

🎀 REQUIREMENTS 🎀

When using pbs_rsub to request a standing, advance, or maintenance reservation, you must specify two of the following options: -R, -E, and -D. The resource request -l walltime can be used instead of the -D option.

If you want to run jobs in a reservation that will request exclusiveqsub placement, you must create the reservation with exclusive placement via -l place=excl.

🌈 OPTIONS 🌈

  • -D <duration> — Specifies reservation duration. If the start time and end time are the only times specified, this duration time is calculated. Format: Duration. See FORMATS. Default: none.
  • -E <end time> — Specifies the reservation end time. If start time and duration are the only times specified, the end time value is calculated. Format: Datetime. See FORMATS. Default: none.
  • -g <group list> — The group list is a comma-separated list of group names. The server uses entries in this list, along with an ordered set of rules, to associate a group name with the reservation. The reservation creator's primary group is automatically added to this list. Format: <group>@<hostname>[,<group>@<hostname> ...]
  • -G <auth group list> — Comma-separated list of names of groups who can or cannot submit jobs to this reservation. Sets reservation's Authorized_Groups attribute to auth group list. This list becomes the acl_groups list for the reservation's queue. More specific entries should be listed before more general, because the list is read left-to-right, and the first match determines access. If both the Authorized_Users and Authorized_Groups reservation attributes are set, a user must belong to both in order to be able to submit jobs to this reservation. Group names are interpreted in the context of the server's host, not the context of the host from which the job is submitted. See the Authorized_Groups reservation attribute in the pbs_resv_attributes(7B) man page. Syntax: [+|-]<group name>[,[+|-]<group name> ...] Default: No groups are authorized to submit jobs 😬
  • --hosts <host list> — Space-separated list of hosts to be included in maintenance reservation. Cannot be used with the -l <placement> or -l <resource request> options. PBS creates placement and resource requests. Placement is always exclhost, and all CPUs of requested hosts are assigned to maintenance reservation.
  • -H <auth host list> — Comma-separated list of hosts from which jobs can and cannot be submitted to this reservation. This list becomes the acl_hosts list for the reservation's queue. More specific entries should be listed before more general, because the list is read left-to-right, and the first match determines access. If the reservation creator specifies this list, the creator's host is not automatically added to the list. See the Authorized_Hosts reservation attribute in the pbs_resv_attributes(7B) man page. Format: [+|-]<hostname>[,[+|-]<hostname> ...] Default: All hosts are authorized to submit jobs
  • -I <block time> — Specifies interactive mode. The pbs_rsub command will block, up to block time seconds, while waiting for the reservation request to be confirmed or denied. If block time is positive, and the reservation isn't confirmed or denied in the specified time, the ID string for the reservation is returned with the status "UNCONFIRMED". If block time is negative, and a scheduler doesn't confirm or deny the reservation in the specified time, the reservation is deleted. 💀 Cannot be used with --hosts option. Has no effect when used with --job option. Format: Integer Default: Not interactive
  • --job <job ID> — Immediately creates and confirms a job-specific now reservation on the same resources as the job (including resources inherited by the job), and places the job in the job-specific now reservation queue. Sets the job's create_resv_from_job attribute to True. Sets the now reservation's reserve_job attribute to the ID of the job from which the reservation was created, sets the reservation's Reserve_Owner attribute to the value of the job's Job_Owner attribute, sets the reservation's resv_nodes attribute to the job's exec_vnode attribute, sets the reservation's resources to match the job's schedselect attribute, and sets the reservation's Resource_List attribute to the job's Resource_List attribute. 🫶

…aaand back to --job for one last sip of tea 🍵 — the now reservation's duration and start time are literally the same as the job's walltime and start time. And if the job is peer scheduled, the now reservation gets created in the pulling complex. Iconic, no notes. 👑

  • Format: Boolean
  • Default: no default 🙈
  • Example: pbs_rsub --job 1234.myserver
Heads up bestie: this one works on running jobs only — jobs in the R state, with substate 42. And it is not the vibe for job arrays, jobs that are already in reservations, or other people's jobs. Nope, nope, and absolutely not. 💀
  • -l <placement> — this is the how do we place the vnodes knob 🎀 The place statement can hold these elements, in any order:
-l place=[ <arrangement> ][: <sharing> ][: <grouping> ]

where:

  • arrangement — whether this reservation chunk is willing to share this vnode or host with other chunks from this reservation. One of free | pack | scatter | vscatter ✨
  • sharing — whether this reservation chunk is willing to share this vnode or host with other reservations or jobs. One of excl | share | exclhost 🔒
  • grouping — whether the chunks from this reservation should be placed on vnodes that all have the same value for a resource. Can have only one instance of group=resource. 🧺

and where:

  • free — place reservation on any vnode(s). 🦋
  • pack — all chunks are taken from one host. 🎒
  • scatter — only one chunk with any MPI processes is taken from a host. A chunk with no MPI processes may be taken from the same vnode as another chunk. 🌸
  • vscatter — only one chunk is taken from any vnode. Each chunk must fit on a vnode. 💅
  • excl — only this reservation uses the vnodes chosen. 🙅‍♀️
  • exclhost — the entire host is allocated to the reservation. 🏰
  • shared — this reservation can share the vnodes chosen. 🫶
  • group=<resource> — chunks are grouped according to a resource. All vnodes in the group must have a common value for resource, which can be either the built-in resource host or a custom vnode-level resource. resource must be a string or a string array. ⭐

So if you want to run jobs inside the reservation that will request exclusive placement, you must create the reservation with exclusive placement via -l place=excl. That's the rule, periodt.

The place statement cannot begin with a colon. Colons are delimiters — use them only to separate parts of a place statement, unless they're quoted inside resource values. Do not come for the colons. 🚫

Also, note that nodes can have sharing attributes that override job placement requests — go read the pbs_node_attributes(7B) man page for that lore. 📖

  • -l resource request — this one says what resources the reservation actually needs 🔥

These resources are used for the limits on the queue that is dynamically created for the reservation. The aggregate amount of resources for currently running jobs from this queue will not exceed these resource limits. Jobs in the queue that request more of a resource than the queue limit for that resource are not allowed to run. Also, the queue inherits the value of any resource limit set on the server, and these are used for the job if the reservation request itself is silent about that resource. A non-privileged user cannot submit a reservation requesting a custom resource which has been created to be invisible or read-only for users. 👀

Resources are requested by using the -l option, either in chunks inside of selection statements, or in job-wide requests using <resource name>=<value> pairs.

Requesting resources in chunks:

-l select=[N:]<chunk>[+[N:]<chunk> ...]

where N specifies how many of that chunk, and a chunk is of the form:

<resource name>=<value>[:<resource name>=<value> ...]

Requesting job-wide resources:

-l <resource name>=<value>[,<resource name>=<value> ...]
  • -m <mail events> — the when do we email you setting 💌 It picks the set of events that cause mail to be sent to the list of users specified in the -M mail list option.

Format: string consisting of one of the following:

  1. any combination of "a", "b", "c" or "e"
  2. the single character "n"
  • a — notify if the reservation is terminated for whatever reason. 😭
  • b — notify when the reservation period begins. 🌅
  • c — notify when the reservation is confirmed. ✅
  • e — notify when the reservation period ends. 🌙
  • n — send no mail. Cannot be used with any of a, b, c or e. 🙈
  • Default: ac
  • -M <mail list> — the list of users to whom mail is sent whenever the reservation transitions to one of the states specified in the -m mail events option. 📬
  • Format: <username>[@<hostname>][,<username>[@<hostname>]...]
  • Default: reservation owner.
  • -N <reservation name> — gives the reservation a name. Because she deserves one. 🎀
  • Format: Reservation name. See FORMATS.
  • Default: None.
  • -q <destination> — tells it which destination server to create the reservation at. 🗺️
  • Default: The default server is used if this option is not selected.
  • -r <recurrence rule> — the standing-reservation recurrence rule, aka the she does this every week option 🔁 Rule must conform to iCalendar syntax, and is specified using a subset of parameters from RFC 2445.

Valid syntax for recurrence rule takes one of two forms:

FREQ=<freq spec>;COUNT=<count spec>;<interval spec>

or

FREQ=<freq spec>;UNTIL=<until spec>; <interval spec>

where:

  • freq spec — frequency with which the standing reservation repeats. Valid values are: WEEKLY|DAILY|HOURLY 📅
  • count spec — the exact number of occurrences. Number up to 4 digits in length. Format: integer. 🔢
  • interval spec — specifies interval. Format is one or both of:
BYDAY = MO|TU|WE|TH|FR|SA|SU

or

BYHOUR = 0|1|2|...|23

When using both, separate them with a semicolon. Elements specified in the recurrence rule override those specified in the arguments to the -R and -E options. For example, the BYHOUR specification overrides the hourly part of the -R option. For example, -R 0730 -E 0830 ... BYHOUR=9 results in a reservation that starts at 9:30 and runs for 1 hour. 😮‍💨

  • until spec — occurrences will start up to but not after date and time specified. Format: YYYYMMDD[THHMMSS]. Note that the year-month-day section is separated from the hour-minute-second section by a capital T. 🅃

Requirements (do not skip, bestie 🙏):

  • The recurrence rule must be on one unbroken line and must be enclosed in double quotes.
  • A start and end date must be used when specifying a recurrence rule. See the R and E options.
  • The PBS_TZID environment variable must be set at the submission host. The format for PBS_TZID is a timezone location. Examples: America/Los_Angeles, America/Detroit, Europe/Berlin, Asia/Calcutta. 🌍

Examples of Standing Reservations 🌈

For a reservation that runs every day from 8am to 10am, for a total of 10 occurrences:

pbs_rsub -R 0800 -E 1000 -r "FREQ=DAILY;COUNT=10"

Every weekday from 6am to 6pm until December 10 2008:

pbs_rsub -R 0600 -E 1800
-r "FREQ=WEEKLY; BYDAY=MO,TU,WE,TH,FR; UNTIL=20081210"

Every week from 3pm to 5pm on Monday, Wednesday, and Friday, for 9 occurrences, i.e., for three weeks:

pbs_rsub -R 1500 -E 1700
-r "FREQ=WEEKLY;BYDAY=MO,WE,FR; COUNT=3"
  • -R <start time> — specifies the reservation starting time ⏰ If the reservation's end time and duration are the only times specified, this start time is calculated.

If the day, DD, is not specified, it defaults to today if the time hhmm is in the future. Otherwise, the day is set to tomorrow. For example, if you submit a reservation with the specification -R 1110 at 11:15 a.m., it is interpreted as being for 11:10am tomorrow. 🕚

If the month portion, MM, is not specified, it defaults to the current month, provided that the specified day DD, is in the future. Otherwise, the month is set to next month. Similar rules apply to the two other optional, left-side components. 🗓️

  • Format: Datetime
  • -u <user list> — not used. Comma-separated list of user names. 💤 (she's retired, leave her be)
  • Format: <username>[@<hostname>][,<username>[@<hostname>] ...]
  • Default: None
  • -U <auth user list> — comma-separated list of users who are and are not allowed to submit jobs to this reservation. Sets reservation's Authorized_Users attribute to auth user list. 🔐

This list becomes the acl_users attribute for the reservation's queue.

More specific entries should be listed before more general, because the list is read left-to-right, and the first match determines access. The reservation creator's username is automatically added to this list, whether or not the reservation creator specifies this list. (Yes, you're always invited to your own party. 💅)

If both the Authorized_Users and Authorized_Groups reservation attributes are set, a user must belong to both in order to be able to submit jobs to this reservation. Both. Not one. Both. 🫶

See the Authorized_Users reservation attribute in the pbs_resv_attributes(7B) man page.

Syntax:

[+|-]<username>[@<hostname>][,[+|-]<username>[@<hostname>]...]
  • Default: Reservation owner only
  • -W attribute value list — this lets you define other attributes for the reservation. 🛠️

Supported attributes:

  • qmove=<job ID> — okay so this one is lowkey magic, bestie ✨ It takes a queued job as input, creates a job-specific ASAP reservation for the same resources the job requests, and moves the job into the reservation’s queue. The reservation is scheduled to run as soon as possible.

When the reservation is created, it inherits its resources from the job, not from the resources requested through the pbs_rsub command. No cap.

You can use the -I option to specify a timeout for the conversion. If you use the qmove option to convert a job to a reservation, and the reservation is not confirmed within the timeout period, the reservation is deleted. The default timeout period is 10 seconds. There is no option for this kind of reservation to be unconfirmed. 🙈

To specify the timeout, you must give a negative value for the -I option. For example, to specify a timeout of 300 seconds:

pbs_rsub -Wqmove=<job ID> -I -300

The default value for the delete_idle_time attribute for an ASAP reservation is 10 minutes.

The -R and -E options to pbs_rsub are disabled when using the qmove=<job ID> option. Periodt.

Some shells require that you enclose a job array ID in double quotes. Shells are dramatic, iykyk.

Can be used on queued jobs only. 💅
  • --version — the pbs_rsub command returns its PBS version information and exits. This option can only be used alone. 👑

📤 OUTPUT

The pbs_rsub command returns the reservation identifier.

Format for an advance or job-specific reservation:

R<sequence number>.<server name>

The associated queue’s name is the prefix, R<sequence number>.

Format for a standing reservation:

S<sequence number>.<server name>

The associated queue’s name is the prefix, S<sequence number>.

Format for a maintenance reservation:

M<sequence number>.<server name>

🧾 FORMATS

⏰ Datetime format

[[[[CC]YY]MM]DD]hhmm[.SS]

⏳ Duration format

A period of time, expressed either as:

  • An integer whose units are seconds

or

  • [[hours:]minutes:]seconds[.milliseconds] in the form [[HH:]MM:]SS[.milliseconds]

Milliseconds are rounded to the nearest second.

🎀 Reservation name format

String up to 230 characters in length. It must consist of printable, non-white space characters. It can contain alphabetic and numeric characters, and plus sign, dash or minus, underscore, and dot or period.

👀 SEE ALSO

Go vibe with pbs_resv_attributes(7B), pbs_rdel(1B), pbs_rstat(1B), qmove(1B), and qsub(1B).

That’s the whole page, bestie 🫶 Footer tea: Local, dated 24 September 2020, for pbs_rsub(1B) — slay and goodbye 💅✨

📦 where this page comes from