NAME pshare - Displays resource allocation and usage information from the Resource Allocation & Control data base within the DPCS system. SYNOPSIS pshare [-b bank-list] [-u user-list] [-0|O] [-H] [-%] [-m hostname] pshare -[t|T] bank [-l n] [-0|O] [-H] [-%] [-m hostname] pshare -r bank [-0|O] [-H] [-%] [-m hostname] pshare -h DESCRIPTION pshare reads the RAC data base file and writes ascii records from it to stdout. Information written depends on options specified on the command line. If the -b option is used, information about banks is written. If the -u option is used, information about user allocations is written. If the -t or -T option is used, information about banks and (in the case of the -t option) user allocations is written in such a manner as to show the tree structure of the data base. If the -r option is used, information about the specified bank and all its parents up through and including the root bank is written. If none of the above options are used, then information about the calling user's allocations is written. In addition to a Resource Quota allocation scheme, the DPCS also implements a "Fair Share" allocation scheme. These two allocation schemes are independent from each other and work to accomplish dif- ferent goals. The fair share system attempts to regulate short term "rate-of-delivery" to help assure that users get good response time and turn-around to the extent that they have been allocated access to compute resources. Users and groups of users (that is, within the context of banks) are granted shares that represent their "claim" on the resources of computers being managed by DPCS. Each machine within the DPCS domain is a member of one and only one resource partition. That is, computers are partitioned into resource partitions. A resource partition may have one member computer or it may have many. Shares are allocated to each user and bank for each resource partition. A share represents a user's or a bank's claim on the computational resources capable of being generated at a resource partition such as memory and cpu time. A user or bank may apply the shares allocated to it for a resource partition on any of the hosts in a resource partition. When a bank is created or a user is permitted to use the resources granted to a bank, shares are allocated to that bank or user for each existing resource partition. The shares a user or bank has, when divided by the total number of shares allocated to all its siblings, represents the portion of the shares granted to the parent bank that are claimed by the user or bank. The number of shares assigned by an administrator to a user or bank is called the "raw shares". The portion of a parent bank's raw shares that can be claimed by a user or bank is called the "effective share". Raw shares are assigned but effective shares are computed from the assigned raw shares. For instance, assume there is a bank named TOP that has been assigned some number of raw shares. Assume further that TOP's effective share of its parent bank has been calcu- lated to be .3 (or 30%). Now, assume that TOP has 2 subbanks and 1 user allocation named RIGHT, LEFT and bob, respectively. If RIGHT has 50 raw shares, LEFT has 20 raw shares and bob has 30 raw shares, then RIGHT would have a .5 effective share of TOP's share (or a .15 effective share of TOP's parent's share), LEFT would have a .2 effec- tive share of TOP's share (or a .06 effective share of TOP's parent's share), and bob would have a .3 effective share TOP's share. Note that if RIGHT, LEFT and bob had been assigned 20, 8 and 12 raw shares, respectively, then their effective shares would remain the same because the ratios of their raw shares would still be 5:2:3. Shares are "normalized" with respect to users who are requesting that resources be delivered to them. (In other words, are logged onto some machine or have a batch job that can run.) So, even though a user may be granted only a 0.01% effective share; if that user is the only user requesting resources, then his/ her normalized effective share of the machine is 1.0. If two users are requesting resources and one use has a global effective share of .03 and the other has an global effective share of .12, then their normalized shares are DPCS would try to deliver 20% of the machine's resources to the first user and 80% of the machine's resources to the other user. DPCS attempts to direct resource usage by measuring actual usage, comparing the results against the normalized shares and adjusting "nice" values of sessions and scheduling jobs so as to make usage patterns conform to normalized share values. Each user allocation and bank has associated with it a "usage" value. This value, in the banks and user allocation which authorizes usage, is incremented whenever a user uses the resources of a computer. It is also "decayed" on a regular basis. The decay algorithm is called a "half-life decay" algorithm. The algorithm is written such that if a usage value is not incremented during the half-life decay period, its value will be cut in half in that period. The information written is displayed in multi-column format. The headings for the columns are as follows (depending on whether the -u, the -b or -r, or the -t or -T option is used, respectively): RESOURCE PARTITION: partition_name USERNAME BANKNAME --------SHARES-------- ------USAGE------ ALLOCATED NORMALIZED NORMALIZED RAW BANKNAME PARENT --------SHARES-------- ------USAGE------ ALLOCATED NORMALIZED NORMALIZED RAW U/B NAME B/P NAME --------SHARES-------- ------ USAGE------ ALLOCATED NORMALIZED NORMAL- IZED RAW The columns are relatively self-explanatory: SHARES ALLOCATED the nominal share granted to the user or bank which may be applied to the resource partition of which the specified or implied hostname is a member. This value must be interpreted by dividing it by the sum of all nominal shares allocated to sibling banks or user allocations. If you use the -% option, this calculation is done for you. SHARES NORMALIZED the instantaneous share of the resource partition of which the specified or implied hostname is a member which is being applied for the user or the bank expressed as a portion of the total shares which can be applied to the resource partition. USAGE NORMALIZED the half-life decayed usage value expressed as a por- tion of the total usage on the resource partition being reported. USAGE RAW the half-life decayed raw usage value. This value is incremented as the user or bank uses resources on a host in the resource partition. It is decremented periodically according to the function u(now) = u(last) / {2 ^ [{T(now) - T(last)} / decay_rate]) The decay rate is set by a pcs manager and represents the amount of time which if a bank or user allocation is not used, it will decay to half its starting value. OPTIONS -% Show allocated shares as a percentage of the parent's shares. -0 or -O Do not list records that have 0 raw usage. -H The reports are issued without a header line that explains the columns. If not used, the header line is written to standard output. -T bank Records are written for the bank specified and, if the -l option is not specified or has a value greater than 0, then all of the bank's sub-banks. The tree is traversed as far as specified by the -l option. If the -l option is not specified, all levels are written. This option may not be used with the -b, -r, -t or -u options. -b bank-list Information about the banks in the list is displayed. The list must be comma separated. This option may not be used with the -T, -r or -t options. -h A friendly usage message is displayed, and pshare terminates. -l levels The number of levels of a sub-tree to display if the -T or -t option is used. This option may not be used if neither the -t option nor the -T option is used. The number of levels must be greater than or equal to 0. -m hostname Will show allocation information for the resource partition of which hostname is a member. If this option is not used, the value for hostname is the host on which pshare is being executed. To see allo- cation information for all resource partitions in the DPCS domain, use an escaped asterisk (\*) as the hostname. (Beware of shell interpretation of the * character.) -r bank Records are written for the specified bank and each of its parents up through and including the root bank. This option may not be used with the -T, -b, -t or -u options. -t bank This option is identical to the -T option except that, in addition, user allocations to the listed banks are also listed. This option may not be used with the -T, -b, -r or -u options. -u user-list Information about the users in the list is displayed. The list must be comma separated. This option may not be used with the -T, -r or -t options. EXAMPLES pshare report the status of the calling user's allocations to his/her current bank on the resource partition of which the host on which pshare is being executed is a member. pshare -u joan,steve,mary report the status of users steve, joan and mary access to all their banks pshare -b sab,fll report the status of the banks sab and fll. pshare -t fll -l 3 report the status of all child nodes of fll down three genera- tion levels. pshare -l 3 -T root report the status of the top three levels of the rdb but report only banks. Do not report user allocations. pshare -t root -0 report the status of all banks and user allocations from which some time has been used. pshare -T root -0 report the status of all banks from which some time has been used. Do not report user allocations. pshare -t root -0 report the status of all banks and user allocations from which some time was used. pshare -r sab report the status of bank sab and all of its parents up through the root bank. pshare -u joan -b sab report all allocations for user joan and report the status of bank sab FILES /usr/local/adm/pcs/rdb RAC data base EXIT CONDITIONS If there is an error, pshare returns an exit status of 1. AUTHOR Robert Wood, Lawrence Livermore National Laboratory, bwood@llnl.gov SEE ALSO bac, defbank, newbank, pquota, pcsmgr