Configure FairShare via the vovfsgroup Utility

The vovfsgroup utility is used to manage FairShare groups (fsgroups) from the command line. This includes creating, deleting and listing them with attributes and ownership.

Fsgroups have an associated owner and an Access Control List (ACL) to describe the operations that may be performed on the group. ACLs permit management of fsgroups to be delegated and distributed among multiple users.

The vovfsgroup command is also used to manage the ACLs of fsgroups. (see also ).

vovfsgroup

Create, show, and modify attributes of FairShare groups. The script also controls Access Control Lists (ACL) for FairShare groups.


vovfsgroup: Usage Message
  
      DESCRIPTION:
      Create, show, and modify attributes of FairShare Groups.
      The script also controls Access Control Lists (ACL) for
      FairShare groups. See information on ACL for additional detail.
  
      SYNOPSIS:
      % vovfsgroup <action> <group> ...
  
      WHERE:
      <action>      is one of "acl, aclrec, create, exists, delete, genconfig,
                               loadconfig, modify, modrec, normalize, show"
      and is case-insensitive
      <group>       is the name of the FairShare group
  
      USAGE:
      vovfsgroup acl <group> GET
                    // Retrieve FairShare Group ACLs
      vovfsgroup acl <group> RESET
                    // Reset FairShare Group ACLs to Default
      vovfsgroup acl <group> APPEND OWNER "Privilege List"
                    // Append Privs to FairShare Group
      vovfsgroup acl <group> APPEND EVERYBODY "Privilege List"
                    // Append Privs to FairShare Group
      vovfsgroup acl <group> APPEND USER <user> "Privilege List"
                    // Append Privs to FairShare Group
  
      Same as above, but apply setting recursively
      to all nodes in the FairShare group:
      vovfsgroup aclrec <group> GET
                    // Retrieve FairShare Group ACLs
      vovfsgroup aclrec <group> RESET
                    // Reset FairShare Group ACLs to Default
      vovfsgroup aclrec <group> APPEND OWNER "Privilege List"
                    // Append Privs to FairShare Group
      vovfsgroup aclrec <group> APPEND EVERYBODY "Privilege List"
                    // Append Privs to FairShare Group
      vovfsgroup aclrec <group> APPEND USER <user> "Privilege List"
                    // Append Privs to FairShare Group
  
      vovfsgroup create <group>
                    // Create a new FairShare group
  
      If the owner-user of the product instance is performing the clone:
        vovfsgroup clone -take <group> <new group>
                    // Clone an existing group and all subgroups to a new group,
                    //   with the current user taking ownership of the new group
                    //   and all subgroups
        vovfsgroup clone -preserve <group> <new group>
                    // Clone an existing group and all subgroups to a new group,
                    //   with ownership of the new group and all subgroups
                    //   copied from the original group
      If any other user is performing the clone:
        vovfsgroup clone <group> <new group>
                    // Clone an existing group and all subgroups to a new group,
                    //   with the current user taking ownership of the new group
                    //   and all subgroups
  
      NOTE: the owner-user of the product instance MUST specify either -take
            or -preserve with the clone command.  Users other than the
            owner-user cannot use the -preserve argument.  Only subgroups to
            which the user has access will be cloned.
  
      vovfsgroup exists <group>
                    // Exit status = 0 if group exists
      vovfsgroup delete <group>
                    // Delete a FairShare group
      vovfsgroup delete -unused
                    // Remove unutilized FairShare groups
  
      vovfsgroup modify <group> weight <integer-value>
                    // Change the weight of a FairShare group
      vovfsgroup modify <group> window <time-spec>
                    // Change the window size of a FairShare group
      vovfsgroup modify <group> owner  <owner-name>
                    // Change owner (requires SERVER status)
      vovfsgroup modify <group> flatten <0|1>
                    // Changed the flattened/non-flattened state of the group
                    //  (0 by default). If a group is flattened, its target
                    //  share is calculated differently; instead of the usual
                    //  hierarchical weighting, all non-leaf node weights are
                    //  ignored and leaf nodes are weighted against each other
                    //  as though they were all part of the same level of
                    //  hierarchy.  Note that vovfsgroup modrec should not be
                    //  used with flatten; it will work but is inefficient,
                    //  as vovfsgroup modify will already propagate the flag
                    //  to any child groups.
  
  
      Same as above, but apply setting recursively
      to all nodes in the FairShare group:
      vovfsgroup modrec <group> weight <integer-value>
                    // Change the weight of a FairShare group.
      vovfsgroup modrec <group> window <time-spec>
                    // Change the window size of a FairShare group.
      vovfsgroup modrec <group> owner  <owner-name>
                    // Change owner (requires SERVER status).
      vovfsgroup genconfig <NEW_CONFIG_FILE>
                    // Generate config file (name specified)
  
      EXAMPLES:
      % vovfsgroup help
      % vovfsgroup create /class/sim
      % vovfsgroup modify /time/users weight 121
      % vovfsgroup modify /time/users window 8h
      % vovfsgroup modify /time/users owner  mary
      % vovfsgroup modify /time/users flatten 1
      % vovfsgroup modrec /time/users window 8h
      % vovfsgroup exists /time
      % vovfsgroup show
      % vovfsgroup show   /time/users
      % vovfsgroup delete /class/sim /class/verilog
      % vovfsgroup delete -unused
      % vovfsgroup acl    /class/sim  GET
      % vovfsgroup acl    /class/sim  RESET
      % vovfsgroup acl    /class/sim  APPEND EVERYBODY "ATTACH VIEW"
      % vovfsgroup acl    /class/sim  APPEND USER jong "ATTACH VIEW"
      % vovfsgroup acl    /class/sim  APPEND USER jong "ATTACH VIEW"
      % vovfsgroup acl    /           SET    OWNER "ALL"
      % vovfsgroup normalize /time/projects 1000
      % vovfsgroup genconfig
      % vovfsgroup genconfig -leaf MyGroupsIncludingLeafNodes.tcl
      %
      % vovfsgroup genconfig myconfig.tcl
      % vovfsgroup loadconfig myconfig.tcl
      %
      % vovfsgroup genconfig -serial myconfig.txt
      % vovfsgroup loadconfig myconfig.txt

vovfsgroup Examples

This section provides examples of using vovfsgroup.

Show the existing FairShare groups
Show details of an existing FairShare groups
Create a new FairShare group
Modify a FairShare group
Delete a FairShare group
Set default for FairShare group
Set ACL for a FairShare group
All children inherit the values of Window and Weight.

In all examples below, the command nc cmd as a prefix to make it clear that we want the command to be executed in the Accelerator project. The prefix can be omitted if you first do a vovproject enable vnc. You also need to have ADMIN privileges for most of these commands to work.

Note: Configuration files can be viewed in various scripting languages. By default, the scripting language is Tcl. The option -serial allows using serial text languages such as Perl. Example:

% vovfsgroup genconfig -serial    #content is saved in serial text format, one group per line
% vovfsgroup genconfig            #content is saved in hierarchical  tcl format

The vovfsgroup create command will now copy the parent ACL when creating a subgroup:

vovfsgroup create /abc/def

The above command will create a new group /abc/def, with ACL permissions copied from the group /abc. If there is no applicable parent group, the default ACLs will be used.

Show the Existing FairShare Groups

The following example shows the summary of the existing fsgroups, with their owner, weight, and time window. The /time and /system FairShare trees are built-in. The /system tree is used by Accelerator and should not be modified or extended.

% nc cmd vovfsgroup show
ID       GROUP                                           OWNER WEIGHT   WINDOW
00001142 /system                                       cadmgr     100    1m00s
00001140 /time                                         cadmgr     100    1h00m
00001144 /time/production                              cadmgr     700    1h00m
00001145 /time/production.joe                          cadmgr       1    1h00m
00001147 /time/regression                              cadmgr     300    1h00m
00001141 /time/users                                   cadmgr      10    2h00m
00001185 /time/users.joe                               cadmgr     100    1h00m

Show Details of Existing FairShare Groups

The following example shows the details of the /time/users FairShare group. It shows that the owner has all ACL privileges, and that everybody has the ATTACH and VIEW privileges. These privileges are needed to automatically create the default /time/users.<user-name> group the first time a user submits a job without specifying a group name.

 % nc cmd vovfsgroup show /time/users
     OWNER "" {ATTACH DETACH EDIT VIEW RETRACE STOP SUSPEND FORGET DELEGATE}
 EVERYBODY "" {ATTACH VIEW}
 00001185 /time/users.joe                             100         joe

Create a New FairShare Tree

This command creates the new fsgroup /division/project/block. The intermediate level /division/project is created automatically. You must be logged in as a user with ADMIN privilege level in Accelerator's security.tcl file.

% nc cmd vovfsgroup create /division/project/block

When you create a new fsgroup, you become its owner. At present, there is no way to change ownership except to delete the fsgroup, then re-create it as the desired owner. See DELEGATE.

The initial ACLs assigned to an fsgroup when it is created are:

DEFAULT_ACL  1: OWNER      ""   ATTACH DETACH EDIT VIEW FORGET DELEGATE EXISTS
DEFAULT_ACL  2: ADMIN      ""   ATTACH DETACH EDIT VIEW FORGET
DEFAULT_ACL  3: EVERYBODY  ""   ATTACH DETACH VIEW

Modify a FairShare Group

The first command modifies the fsgroup /division/project/block. The weight is set to 200. The share assigned to this group will be the weight divided by the sum of the weights of other active fsgroups at this level (i.e. all other groups that have running or queued jobs).

The second command modifies the fsgroup /division/project/block and sets its time window to 4 hours. This is the interval over which recent jobs continue to contribute to FairShare rank.

% nc cmd vovfsgroup modify /division/project/block weight 200
% nc cmd vovfsgroup modify /division/project/block window 4h

Append or Delete an ACL Element from a Group

APPEND can be used to append the defined privileges to the ACL list. DELETE is used to do the exact opposite of it, deleting only what is specified.

For example, an fsgroup /mygroup with one of the ACLs being

USER "john"   ATTACH DETACH VIEW

and then executing

$ nc cmd vovfsgroup /mygroup APPEND USER john EDIT

will append "EDIT" to this ACL and leads to

USER "john"   ATTACH DETACH EDIT VIEW

Now executing

$ nc cmd vovfsgroup /mygroup DELETE USER john "EDIT"

will DELETE the "EDIT" privilege from the ACL again and leads to

USER "john"   ATTACH DETACH VIEW

Set Default Weight for a FairShare Group

The following creates the fsgroup /division/project/default, and assigns it a weight of 200. When another fsgroup is created at the same level, that is, a sibling of default, it automatically is assigned the weight from the default group at that level.

% nc cmd vovfsgroup create /division/project/default
% nc cmd vovfsgroup modify /division/project/default weight 200

Set Access Control Lists for a FairShare Group

The following sequence of commands first gets the current ACL of the group /time/regression for inspection. The second command resets the ACL to its default value.

% nc cmd vovfsgroup acl /time/regression GET
% nc cmd vovfsgroup acl /time/regression RESET
% nc cmd vovfsgroup acl /time/regression APPEND  EVERYBODY "ATTACH VIEW"
% nc cmd vovfsgroup acl /time/regression APPEND  USER regrmgr "ATTACH DETACH VIEW EDIT FORGET DELEGATE"

The third and fourth commands add the ACL for EVERYBODY and regrmgr.

ACL  1: OWNER      ""   ATTACH DETACH EDIT VIEW FORGET DELEGATE EXISTS
ACL  2: EVERYBODY  ""   ATTACH VIEW