pbsfs(8B)

NAME
pbsfs - show or manipulate PBS fairshare usage data

SYNOPSIS
Showing usage data:
pbsfs [-c <entity1> <entity2>] [-g <entity>] [-I <scheduler name>]
      [-p] [-t]
Manipulationg usage data:
pbsfs [-d] [-e] [-I <scheduler name>] [-s <entity> <usage value>]
Printing version:
pbsfs --version

DESCRIPTION
You can use the pbsfs command to print or manipulate the PBS scheduler's fairshare usage data. You can print the usage data in various formats, described below. Changes made using pbsfs take effect in the next scheduling cycle; you do not need to restart or HUP the scheduler for changes to take effect. We recommend that if you use the options that manipulate usage data, you should do this when the scheduler is not scheduling jobs, because scheduling while changing fairshare usage data may give unwanted results. Prerequisites
The server must be running in order to use the pbsfs command. Permissions
You must be root to run the pbsfs command; if not, it will print the error message, "Unable to access fairshare data".

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

(no options)
    Same as pbsfs -p

-c <entity1> <entity2>
    Compare two fairshare entities

-g <entity>
    Print a detailed listing for the specified entity, including the path from the root of the tree to the entity.

-I <scheduler name>
    Specifies name of scheduler whose data is to be manipulated or shown. Required for multischeds; optional for default scheduler. Name of default scheduler is "default". If not specified, pbsfs operates on 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, group ID of the vertex, vertex shares, vertex usage, and percent of shares allotted to the vertex.

-t  Print the fairshare tree in a hierarchical format.

--version
    The pbsfs command returns its PBS version information and exits. This option can only be used alone.

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.

-e  Trim 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.

-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

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. See "Computing Effective Usage (fairshare_tree_usage)" in the PBS Professional Administrator's Guide.

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.

Percentage or perc
    The percentage of the shares in the tree allotted to the entity, computed as fairshare_perc. See "Computing Target Usage for Each Vertex (fairshare_perc)" in the PBS Professional Administrator's Guide.

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 the pick which entity has priority over another. The smaller the number the higher the priority.

SEE ALSO
The PBS Professional Administrator's Guide, pbs_sched(8B)