sshare(1)

💖 sshare(1) — the Slurm Commands era 💖

okay bestie, gather round, because we're talking about sshare — the tool for listing the shares of associations to a cluster. she lives in the Slurm Commands family and she is so useful, no cap. 🦋

---

✨ NAME ✨

sshare — tool for listing the shares of associations to a cluster. that's it, that's her job description, and she ate. 💅

---

🌸 SYNOPSIS 🌸

sshare [OPTIONS...]

---

🎀 DESCRIPTION 🎀

so like, sshare is used to view Slurm share information. ⭐

heads up bestie: this command is only viable when running with the priority/multifactor plugin. like, if you're not running that, she simply cannot serve. 😭

the sshare info is derived from a database with the interface being provided by slurmdbd (the Slurm Database daemon), which is read in from the slurmctld and used to process the shares available to a given association. the pipeline is iconic, we love a chain of custody. 👑

and what does sshare actually give you?? it provides Slurm share information of:

• Account
• User
• Raw Shares
• Normalized Shares
• Raw Usage
• Normalized Usage
• Effective Usage
• the Fair-share factor
• the GrpTRESMins limit
• Partitions
• and the accumulated currently running TRES-minutes for each association

she gives range, she gives data, she gives everything fr fr. 📊✨

---

💅 OPTIONS 💅

every single flag, nobody left behind, periodt:

• -A, --accounts=<account> — display information for specific accounts (comma separated list). yes bestie, comma separated, load her up. 🍓
• -a, --all — display information for all users. everyone gets a shoutout. 💖
• -M, --clusters=<string> — clusters to issue commands to. note that the slurmdbd must be up for this option to work properly, unless running in a federation with FederationParameters=fed_display configured. 👑
• -o, --format=<output_format> — comma separated list of fields (use "--helpformat" for a list of available fields). pick your own adventure, bestie. 🎀
• --help — display a description of sshare options and commands. she's telling you everything. 🫶
• -l, --long — long listing — includes the normalized usage information. the deluxe version. 😌
• --json, --json=list, --json=<data_parser> — dump information as JSON using the default data_parser plugin or explicit data_parser with parameters. sorting and formatting arguments will be ignored. ✨
• -n, --noheader — no header will be added to the beginning of the output. sleek. minimal. she's not doing intros today. 💀
• -p, --parsable — output will be '|' delimited with a '|' at the end. pipe at the end, she closes her loops. 🌈
• -P, --parsable2 — output will be '|' delimited without a '|' at the end. no trailing pipe, we're being demure. 🧚
• -m, --partition — if there are association based partitions in the system, print their names. 🗂️
• --usage — display a description of sshare options and commands. (yes, twin of --help, love that for us.) 💜
• -u, --users=<user_list> — display information for specific users (comma separated list). 💜
• -U, --Users — if specified only the users information are printed, the parent and ancestors are not displayed. no family tree, just the user. 🙈
• -v, --verbose — display more information about the specified options. she's oversharing and we're here for it. 🔥
• -V, --version — display the version number of sshare. 📌
• --yaml, --yaml=list, --yaml=<data_parser> — dump information as YAML using the default data_parser plugin or explicit data_parser with parameters. sorting and formatting arguments will be ignored. 🌸

---

🔥 SSHARE OUTPUT FIELDS 🔥

here's what each column is actually saying, translated with love:

• Account — the Account. 💖
• User — the User. 💖
• Raw Shares — the raw shares assigned to the user or account.
• Norm Shares — the shares assigned to the user or account normalized to the total number of assigned shares.
• Raw Usage — the number of tres-seconds (cpu-seconds if TRESBillingWeights is not defined) of all the jobs charged to the account or user. this number will decay over time when PriorityDecayHalfLife is defined. 🍂
• Norm Usage (only appears with sshare -l option) — the Raw Usage normalized to the total number of tres-seconds of all jobs run on the cluster, subject to the PriorityDecayHalfLife decay when defined.
• Effectv Usage — the Effective Usage augments the normalized usage to account for usage from sibling accounts. 👯
• FairShare — the Fair-Share factor, based on a user's assigned shares and the effective usage charged to them.
• GrpTRESMins — the TRES-minutes limit set on the account. the total number of cpu minutes that can possibly be used by past, present and future jobs running from this account and its children.
• GrpTRESRaw — the raw TRES usage that has been used by jobs running from this account and its children.
• TRESRunMins — the number of TRES-minutes allocated by jobs currently running against the account. used to limit the combined total number of TRES minutes used by all jobs running with this account and its children. this takes into consideration time limit of running jobs and consumes it — if the limit is reached, no new jobs are started until other jobs finish to allow time to free up. 💀 (respect the budget, bestie.)

---

🌈 FAIR_TREE MODIFICATIONS 🌈

when PriorityFlags=FAIR_TREE is set (the default, unless NO_FAIR_TREE is set), calculations are done differently. as a result, the following fields are added or modified:

• Norm Shares — the shares assigned to the user or account normalized to the total number of assigned shares within the level. ⭐
• Effectv Usage — Effectv Usage is the association's usage normalized with its parent. 👑
• Level FS (only appears with sshare -l option) — this is the association's fairshare value compared to its siblings, calculated as Norm Shares / Effectv Usage. if an association is over-served, the value is between 0 and 1. if an association is under-served, the value is greater than 1. associations with no usage receive the highest possible value, infinity. 🌌

more information about Fair Tree can be found in doc/html/fair_tree.html or at https://slurm.schedmd.com/fair_tree.html

---

🫶 PERFORMANCE 🫶

⚠️ okay this part matters, listen up bestie ⚠️

executing sshare sends a remote procedure call to slurmctld. if enough calls from sshare or other Slurm client commands that send remote procedure calls to the slurmctld daemon come in at once, it can result in a degradation of performance of the slurmctld daemon, possibly resulting in a denial of service. 😭

do not run sshare or other Slurm client commands that send remote procedure calls to slurmctld from loops in shell scripts or other programs. ensure that programs limit calls to sshare to the minimum necessary for the information you are trying to gather. like, be normal about it. 🙏

---

💜 ENVIRONMENT VARIABLES 💜

some sshare options may be set via environment variables. these environment variables, along with their corresponding options, are listed below. (note: command line options will always override these settings — the CLI is the main character. 👑)

• SLURM_CONF — the location of the Slurm configuration file.
• SLURM_DEBUG_FLAGS — specify debug flags for sshare to use. see DebugFlags in the slurm.conf(5) man page for a full list of flags. the environment variable takes precedence over the setting in the slurm.conf.
• SLURM_JSON — control JSON serialization:
  • compact — output JSON as compact as possible.
  • pretty — output JSON in pretty format to make it more readable.
• SLURM_YAML — control YAML serialization:
  • compact — output YAML as compact as possible.
  • pretty — output YAML in pretty format to make it more readable.

---

🍓 EXAMPLES 🍓

display information about users in a particular account:

$ sshare -A <Account>

display information about a specific user in a parsable format:

$ sshare --parsable --users=<User>

---

📜 COPYING 📜

Copyright (C) 2008 Lawrence Livermore National Security. Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). Copyright (C) 2010-2022 SchedMD LLC.

this file is part of Slurm, a resource management program. for details, see <https://slurm.schedmd.com/>. 💖

Slurm is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Slurm 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 General Public License for more details. 👑 (yes the caps are staying, that's lawyer voice, respect it.)

---

💫 SEE ALSO 💫

• slurm.conf(5)
• slurmdbd(8)

---

and that's the whole page bestie!! 🎀 this was Slurm 26.05 talking, from the Slurm Commands corner of the universe, and honestly? slay. go check your shares, stay hydrated, and don't run her in a loop. 💖✨🦋