pbs_ralter(1B)

💅 pbs_ralter — like, the manual page bestie

okay so this is pbs_ralter, part of the big PBS Professional family of manual pages, and it lives in section 1B (user commands, the "B" is for PBS-specific ones, iykyk). Think of it as the reservation glow-up command. Let's get into it 🎀

---

✨ NAME ✨

pbs_ralter — modify an existing reservation. that's it, that's the whole vibe: you have a reservation and you want to change it. slay.

---

🦋 SYNOPSIS 🦋

pbs_ralter [-D <duration>] [-E <end time>] [-G <auth group list>]
           [-I <block time>] [-l select=<select spec>]
           [-m <mail points>] [-M <mail list>]
           [-N <reservation name>] [-R <start time>]
           [-U <auth user list>] <reservation ID>
pbs_ralter -Wforce [-D <duration>] [-E <end time>] [-R <start time>]
           <reservation ID>
pbs_ralter --version

three whole ways to invoke her, depending on whether you're being a normal user or an all-powerful admin using -Wforce, or you just want the version number and nothing else. 💫

---

🌸 DESCRIPTION 🌸

so pbs_ralter is the command you use to alter an existing reservation. and when I say existing reservation I mean literally any of them — an individual job-specific one, an advance one, a maintenance one, or the next or current occurrence of a standing reservation. all of them. equal opportunity reservation-altering. 🙌

things you can change: the start time, the end time, the duration, the events that generate mail, the mail recipient list, the authorized groups, the authorized users, and the reservation name. that's a whole makeover. 💅

the PBS Administrator can also use the -Wforce option — that one lets them change the start time, end time, or duration of a reservation, and it overrides the scheduler's actions. admin said i'm the scheduler now. 👑

⭐ what happens after you ask

okay so after you request the change, it gets either confirmed or denied. that's the whole drama.

if it's denied, the reservation is not deleted — it's left exactly as it is — and this message shows up in the server's log:

Unable to alter reservation <reservation ID>

if it's confirmed, this one shows up in the server's log instead:

Reservation alter successful for <reservation ID>

🔍 how to find out if the change was allowed

three ways, bestie, take your pick:

• use the pbs_rstat command: check whether the reservation attribute(s) you altered actually changed
• use the interactive option: check for confirmation after the blocking time has run out
• check the server log for the confirmation or denial messages

💫 states, because of course there are states

before the change is confirmed or denied, the change is unconfirmed, and the reservation state is AL.

once a reservation change is confirmed, the reservation state is CO or RN.

if the reservation has not started and it can't be confirmed on the same vnodes, PBS goes looking for another set of vnodes. scavenger hunt but make it infrastructure. 🧚

if the reservation is altered, PBS logs a Y accounting record. noted. 🍓

🫶 Caveats and Restrictions

lowkey the important part, do not skip 🙈

• you cannot change the start time of a reservation if jobs are running in it.
• if you change the end time of a reservation so that it ends before a job running in the reservation finishes, the job is killed when the reservation ends. like, actually killed. no cap. 💀

💜 Required Privilege

without the Wforce option, this command can be used by the reservation owner or the PBS Administrator.

with the Wforce option, this command can be used only by the PBS Administrator. sorry bestie, that one's admin-only. 😭

---

🔥 Options to pbs_ralter 🔥

• -D <duration> — specifies the reservation's new duration. and here's the iconic part: you can use this even when the reservation is running and has jobs that are submitted to and/or are running in the reservation. yes really. can be specified with start and/or end time. PBS calculates anything not specified. when specified without start or end time, PBS keeps the previous start time. 🧮 if you change the duration to less than the time the reservation has already run, PBS deletes the reservation. okay so be careful with that one. ⚠️ Format: Duration, as seconds or hh:mm:ss
• -E <end time> — specifies the reservation's new end time. same deal as -D: usable even when the reservation is running and has jobs submitted to and/or running in it. 💖 Format: Datetime
• -G <auth group list> — a comma-separated list of names of groups who can or cannot submit jobs to this reservation. sets the 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 ones, because the list is read left-to-right and the first match determines access. order matters, bestie, it's giving priority list. 📋 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. important distinction ✨ see the Authorized_Groups reservation attribute in the pbs_resv_attributes(7B) man page. Syntax: [+|-]<group name>[,[+|-]<group name> ...] Default: no default; group names are unchanged
• -I <block time> — (capital I, do not confuse her with lowercase -l) specifies interactive mode. the pbs_ralter command will block, up to block time seconds, while waiting for the reservation's change request to be confirmed or denied. like it literally just sits there waiting. patient queen. ⏳ the value for block time must be positive. the pbs_ralter command returns either the status CONFIRMED or the status DENIED . Format: Integer Default: Not interactive
• -l select=<select spec> — (lowercase L) specifies a new select specification for the reservation. the new specification must be a subset of the same chunks requested by the original reservation. no inventing new chunks, that's not the vibe. if the reservation is started, it can't be used to release chunks where reservation jobs are running. if the reservation is started and degraded, you must release all unavailable chunks in order to alter the reservation select specification. all of them. not some. all. 😤
• -m <mail points> — specifies the set of events that cause mail to be sent to the list of users specified in the -M <mail list> option. Format: String Syntax: either of
  1. any combination of "a", "b", "c" or "e", or
  2. the single character "n"

🎀 Suboptions to -m

• a — Notify if reservation is terminated for any 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: No default; if not specified, mail events are unchanged

• -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 points> option. 📬 Format: <username>[@<hostname>][,<username>[@<hostname>]...] Default: No default; if not specified, user list is unchanged
• -N <reservation name> — specifies a name for the reservation. give her a little identity ✨ Format: String up to 15 characters in length. It must consist of printable, non-white space characters with the first character alphabetic. Default: No default; if not specified, reservation name is unchanged
• -R <start time> — specifies the reservation's new start time. this option can be used either when the reservation is not running or there are no jobs submitted to the reservation. you cannot use this option when a reservation is not empty and has started running. 🚫 the specifications for providing the time are the same as for pbs_rsub: 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 alter a reservation with the specification -R 1110 at 11:15 a.m., it is interpreted as being for 11:10 a.m. tomorrow. time travel but the disappointing kind 😭 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 <auth user list> — a comma-separated list of users who are and are not allowed to submit jobs to this reservation. sets the 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 ones, 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. you're always on the list, bestie, it's your reservation 🫶 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. see the Authorized_Users reservation attribute in the pbs_resv_attributes(7B) man page. Syntax: [+|-]<username>[@<hostname>][,[+|-]<username>[@<hostname>]...] Default: no default; user list is unchanged
• -Wforce — enforces changes made to the reservation start time, end time, or duration, regardless of the actions of the scheduler. can be used only by the PBS Administrator.

ok so real talk: with this option you can force PBS to oversubscribe resources, in which case you (the administrator) may need to manage them yourself. that's not a cute look if you weren't ready for it. 💀

cannot be used to change the start time of a reservation in which jobs are running.

• --version — the pbs_ralter command returns its PBS version information and exits. this option can only be used alone. she does not do plus-ones. 💅

---

🌈 OPERANDS 🌈

the pbs_ralter command takes a reservation ID.

for an advance or job-specific reservation this has the form:

R<sequence number>[.<server name>][@<remote server>]

for a standing reservation this has the form:

S<sequence number>[.<server name>][@<remote server>]

for a maintenance reservation this has the form:

M<sequence number>[.<server name>][@<remote server>]

@<remote server> specifies a reservation at a server other than the default server. so you can reach out across servers, iconic. 🌐

---

and that's the whole page, bestie 🎀 this edition is from Local, dated 28 February 2021, and it's the pbs_ralter(1B) page from PBS Professional. go forth and alter some reservations responsibly 💖✨🦋