openpbs/doc/man8/pbsfs.8B

.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro 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 Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH pbsfs 8B "15 February 2018" Local "PBS Professional"
.SH NAME
.B pbsfs 
\- show or manipulate PBS fairshare usage data
.SH SYNOPSIS

Showing usage data:
.br
.B pbsfs 
[-c <entity1> <entity2>] [-g <entity>] [-I <scheduler name>] 
      [-p] [-t]

.br
Manipulationg usage data:
.br
.B pbsfs 
[-d] [-e] [-I <scheduler name>] [-s <entity> <usage value>]

.br
Printing version:
.br
.B pbsfs 
--version

.SH DESCRIPTION

You can use the 
.B 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 
.B 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.  

.B Prerequisites
.br
The server must be running in order to use the 
.B pbsfs
command.

.B Permissions 
.br
You must be root to run the 
.B pbsfs 
command; if not, it will print the error message, 
"Unable to access fairshare data".

.SH OPTIONS

.B You can safely use the following options while jobs are being scheduled:
.IP "(no options)" 10
Same as 
.B pbsfs -p
.IP "-c <entity1> <entity2>" 10
Compare two fairshare entities
.IP "-g <entity>" 10
Print a detailed listing for the specified entity, including the path 
from the root of the tree to the entity.
.IP "-I <scheduler name>" 10
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, 
.B pbsfs
operates on default scheduler.
.IP "-p" 10
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.
.IP "-t" 10
Print the fairshare tree in a hierarchical format.
.IP "--version" 10
The 
.B pbsfs
command returns its PBS version information and exits.
This option can only be used alone.
.LP

.B It is not recommended to be scheduling jobs when you use the following options:
.IP "-d" 10
Decay the fairshare tree by the amount specified in the 
.I fairshare_decay_factor
scheduler parameter.
.IP "-e" 10
Trim fairshare tree to just the entities in the 
.I resource_group 
file.  Unknown entities and their usage are deleted; as a result the unknown
group has no usage and no children.
.IP "-s <entity> <usage value>" 10
Set 
.I entity's 
usage value to 
.I 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.
.LP

.SH Output Formats for pbsfs

The pbsfs command can print output in three different formats:

.B pbsfs -g <entity>
.br
Prints a detailed listing for the specified entity.  Example:
.br
.B 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

.B pbsfs or pbsfs -p
.br
Prints the entire tree as a table, with data in columns.  Example:
.br
.B pbsfs
.br
Fairshare usage units are in: cput
.br
TREEROOT\ : Grp:\ -1\ \ cgrp:\ \ 0  Shares:\ -1  Usage:\ 1201   Perc:\ 100.000%
.br
group2\ \ \ : Grp:\ \ 0\ \ cgrp:\ 20  Shares:\ 60  Usage:\ 1001   Perc:\ \ 60.000%
.br
pbsuser3\ : Grp:\ 20\ \ cgrp:\ 22  Shares:\ 40  Usage:\ 1000   Perc:\ \ 24.000%
.br
pbsuser2\ : Grp:\ 20\ \ cgrp:\ 21  Shares:\ 60  Usage:\ \ \ \ 1   Perc:\ \ 36.000%
.br
group1\ \ \ : Grp:\ \ 0\ \ cgrp:\ 10  Shares:\ 40  Usage:\ \ 201   Perc:\ \ 40.000%
.br
pbsuser1\ : Grp:\ 10\ \ cgrp:\ 12  Shares:\ 50  Usage:\ \ 100   Perc:\ \ 20.000%
.br
pbsuser\ \ : Grp:\ 10\ \ cgrp:\ 11  Shares:\ 50  Usage:\ \ 100   Perc:\ \ 20.000%
.br
unknown\ \ : Grp:\ \ 0\ \ cgrp:\ \ 1  Shares:\ \ 0  Usage:\ \ \ \ 1   Perc:\ \ \ 0.000%

.B pbsfs -t
.br
Prints the entire tree as a tree, showing group-child relationships.  Example:
.br
.B pbsfs -t
  TREEROOT(0)
      group2(20)
           pbsuser3(22)
           pbsuser2(21)
      group1(10)
           pbsuser1(12)
           pbsuser(11)
      unknown(1)

.SH Data Output by pbsfs
.IP "cresgroup or cgrp" 10
Group ID of the entity.
.IP "fairshare entity" 10
The specified fairshare tree entity.
.IP "fairshare usage units" 10
The resource for which the scheduler accumulates usage for fairshare
calculations.  This defaults to 
.I cput 
(CPU seconds) but can be set in
the scheduler's configuration file.
.IP "fairshare_tree_usage" 10
The entity's effective usage.  See "Computing Effective
Usage (fairshare_tree_usage)" in the PBS Professional
Administrator's Guide.
.IP "Path from root" 10
The path from the root of the tree to the entity.  The scheduler
follows this path when comparing priority between two entities.
.IP "Percentage or perc" 10
The percentage of the shares in the tree allotted to the entity,
computed as 
.I fairshare_perc.  
See "Computing Target Usage for Each
Vertex (fairshare_perc)" in the PBS Professional
Administrator's Guide.
.IP "Resgroup or Grp" 10
Group ID of the entity's parent group.
.IP "Shares" 10
The number of shares allotted to the entity.
.IP "usage" 10
The amount of usage by the entity.
.IP "usage / perc" 10
The value the scheduler uses to the pick which entity has priority
over another.  The smaller the number the higher the priority.

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