pbsfs(8B)

💅 pbsfs — the fairshare tea-spiller

okay bestie, welcome to pbsfs(8B) from PBS Professional — the little command that shows you (and messes with) the PBS scheduler's fairshare usage data. she's giving backstage-pass-to-the-scheduler energy and honestly? iconic. 🎀

---

✨ NAME ✨

pbsfs — show or manipulate PBS fairshare usage data

---

🌸 SYNOPSIS 🌸

Showing usage data:

pbsfs [-c <entity1> <entity2>] [-g <entity>] [-I <scheduler name>]
      [-p] [-t]

Manipulating usage data:

pbsfs [-d] [-e] [-I <scheduler name>] [-s <entity> <usage value>]

Printing version:

pbsfs --version

---

🦋 DESCRIPTION 🦋

so the whole point of pbsfs: you use it to print or manipulate the PBS scheduler's fairshare usage data. you can print that usage data in a bunch of different formats, all described down below. 💖

and here's the slay part — changes you make with pbsfs take effect in the next scheduling cycle. you do not need to restart the scheduler or HUP it for your changes to land. no drama, no restart, periodt. ✨

⚠️ real talk though: if you're using the options that manipulate usage data, we recommend you do it when the scheduler is not scheduling jobs. lowkey important — scheduling while you're changing fairshare usage data may give you unwanted results. 😭

🧚 Prerequisites

the server has to be running for you to use the pbsfs command. no server, no vibes.

🔐 Permissions

you must be root to run pbsfs. if you're not, it prints the error message, "Unable to access fairshare data". that's the vibe check failing. 💀

---

🌈 OPTIONS 🌈

💜 the safe ones (fine to use while jobs are being scheduled)

you can safely use the following options while jobs are being scheduled:

• (no options) — same as pbsfs -p. literally just type the command, bestie.
• -c <entity1> <entity2> — compare two fairshare entities. head-to-head, side by side, 🫶
• -g <entity> — print a detailed listing for the specified entity, including the path from the root of the tree to the entity. the full origin story. 🌸
• -I <scheduler name> — specifies the name of the scheduler whose data is to be manipulated or shown. Required for multischeds; optional for the default scheduler. the default scheduler's name is "default". if you don't specify it, pbsfs operates on the default scheduler. 👑
• -p — print the fairshare tree as a table, showing, for each internal and leaf vertex: the group ID of the vertex's parent, the group ID of the vertex, vertex shares, vertex usage, and percent of shares allotted to the vertex. a whole spreadsheet moment. ✨
• -t — print the fairshare tree in a hierarchical format. the family tree reveal. 🌳
• --version — the pbsfs command returns its PBS version information and exits. this option can only be used alone. no plus-ones. 🙈

🍓 the "maybe don't schedule right now" ones

it is not recommended to be scheduling jobs when you use the following options:

• -d — decay the fairshare tree by the amount specified in the fairshare_decay_factor scheduler parameter. glow-down mode activated. 🍂
• -e — trim the fairshare tree to just the entities in the resource_group file. unknown entities and their usage are deleted; as a result, the unknown group has no usage and no children. it's giving spring cleaning but make it permanent. 💀
• -s <entity> <usage value> — set entity's usage value to usage value. editing a non-leaf entity is ignored. all non-leaf entity usage values are calculated each time you use the pbsfs command to make changes. 🫶

---

🎀 Output Formats for pbsfs 🎀

the pbsfs command can print output in three different formats:

💖 pbsfs -g <entity>

prints a detailed listing for the specified entity. example:

pbsfs -g pbsuser3
 fairshare entity: pbsuser3
 Resgroup: 20
 cresgroup: 22
 Shares: 40
 Percentage: 24.000000%
 fairshare_tree_usage: 0.832973
 usage: 1000 (cput)
 usage/perc: 4167
 Path from root:
 TREEROOT  :     0       1201 / 1.000 = 1201
 group2    :    20       1001 / 0.600 = 1668
 pbsuser3  :    22       1000 / 0.240 = 4167

💖 pbsfs or pbsfs -p

prints the entire tree as a table, with data in columns. example:

pbsfs
Fairshare usage units are in: cput
TREEROOT : Grp: -1  cgrp:  0  Shares: -1  Usage: 1201   Perc: 100.000%
group2   : Grp:  0  cgrp: 20  Shares: 60  Usage: 1001   Perc:  60.000%
pbsuser3 : Grp: 20  cgrp: 22  Shares: 40  Usage: 1000   Perc:  24.000%
pbsuser2 : Grp: 20  cgrp: 21  Shares: 60  Usage:    1   Perc:  36.000%
group1   : Grp:  0  cgrp: 10  Shares: 40  Usage:  201   Perc:  40.000%
pbsuser1 : Grp: 10  cgrp: 12  Shares: 50  Usage:  100   Perc:  20.000%
pbsuser  : Grp: 10  cgrp: 11  Shares: 50  Usage:  100   Perc:  20.000%
unknown  : Grp:  0  cgrp:  1  Shares:  0  Usage:    1   Perc:   0.000%

💖 pbsfs -t

prints the entire tree as a tree, showing group-child relationships. example:

pbsfs -t
  TREEROOT(0)
      group2(20)
           pbsuser3(22)
           pbsuser2(21)
      group1(10)
           pbsuser1(12)
           pbsuser(11)
      unknown(1)

---

🔥 Data Output by pbsfs 🔥

here's the glossary for everything pbsfs spits out, so you're never confused mid-scroll. iykyk:

• cresgroup or cgrp — group ID of the entity.
• fairshare entity — the specified fairshare tree entity.
• fairshare usage units — the resource for which the scheduler accumulates usage for fairshare calculations. this defaults to cput (CPU seconds) but can be set in the scheduler's configuration file. ⭐
• fairshare_tree_usage — the entity's effective usage.
• Path from root — the path from the root of the tree to the entity. the scheduler follows this path when comparing priority between two entities. it's the entity's lore. 🧚
• Percentage or perc — the percentage of the shares in the tree allotted to the entity, computed as fairshare_perc.
• Resgroup or Grp — group ID of the entity's parent group.
• Shares — the number of shares allotted to the entity.
• usage — the amount of usage by the entity.
• usage / perc — the value the scheduler uses to pick which entity has priority over another. the smaller the number, the higher the priority. so being small here? main character energy. 👑

---

💫 SEE ALSO 💫

pbs_sched(8B) — go read that one next, bestie 🫶

---

and that's the whole page, no cap! 💖✨🎀🦋🌸💅

mwah — this cutie was brought to you by Local, dated 6 May 2020, from PBS Professional (pbsfs(8B)). go forth and fairshare responsibly, queen. 👑💜