Provided by: gridengine-common_8.1.9+dfsg-9build2_all bug

NAME

       sge_resource_quota - Grid Engine resource quota file format

DESCRIPTION

       Resource quota sets (RQS) are a flexible way to set a maximum resource consumption for any
       job requests. They are used by the scheduler to select the next possible jobs for running.
       The  job  request  quota  application is done according to a set of user, project, cluster
       queue, host and  PE  filter  criteria.   RQS  are  applied  to  resource  requests  before
       considering  the  amount  of  resources  defined (in order) at the global, host, and queue
       levels.  If an RQS denies the request the other levels are not considered.

       By  using  resource  quota  sets,  administrators  can   define   a   fine-grained   quota
       configuration,  restricting some job requests to lesser resource usage and granting others
       higher usage.

       Note: Jobs requesting an Advance Reservation (AR) are not honored by RQS, and are  neither
       subject to the resulting limit, nor debited in the usage consumption.

       A  list  of  currently configured RQS can be displayed via the qconf(1) -srqsl option. The
       contents of each listed rqs definition can be shown  via  the  -srqs  switch.  The  output
       follows  the  format  described below. New RQS can be created, and existing ones modified,
       via the -arqs, -mrqs and -drqs options to qconf(1).

       A resource quota set defines a maximum resource quota for a particular job request. All of
       the  configured  and  enabled rule sets apply all of the time. This means that if multiple
       resource quota sets are defined, the most restrictive set is used.

       Every resource quota set consists of one or more resource quota  rules.  These  rules  are
       evaluated  in  order,  and  the first rule that matches a specific request will be used. A
       resource quota set always results in at most one  effective  resource  quota  rule  for  a
       specific request.

       Note,  Grid  Engine  allows  backslashes  (\)  be  used  to escape newline characters. The
       backslash and the newline are replaced with a space character before any interpretation.

FORMAT

       A resource quota set definition contains the following parameters one per-line  in  braces
       which enclose the whole set.  See below for the formal syntax.

   name
       The resource quota set name.

   enabled
       If  set  to  true  the  resource quota set is active and will be considered for scheduling
       decisions. The default value is false.

   description
       This description field is optional and can be set to  an  arbitrary  string.  The  default
       value is NONE.

   limit
       Every resource quota set needs at least one resource quota rule definition, started by the
       limit field. It is possible to define multiple resource quota rules, separated  by  a  new
       line, processed in order top to bottom.

       A  resource  quota  rule  consists  of  an  optional  name, the filters for a specific job
       request, and the resource quota limit.

       The tags for expressing a resource quota rule are:

       name   The name of the rule (optional). The rule name must be  unique  within  a  resource
              quota set.

       users  Contains  a  comma-separated list of user names or ACLs (see access_list(5)).  This
              parameter filters jobs by user or ACL in the list. Any user not in  the  list  will
              not  be  considered  for  the  resource quota rule. The default value is '*', which
              means all users. An ACL is differentiated from a user name  by  prefixing  the  ACL
              name  with  '@'.  To  exclude a user or ACL from the rule, the name can be prefixed
              with '!'. The defined user  or  ACL  names  need  not  exist  in  the  Grid  Engine
              configuration.

       projects
              Contains  a  comma-separated  list  of  projects  (see project(5)).  This parameter
              filters jobs requesting a project in the list. Any project not in the list will not
              be  considered  for the resource quota rule. If no project filter is specified, all
              projects, and jobs with no requested project, match the rule. The value  '*'  means
              all  jobs with requested projects. To exclude a project from the rule, the name can
              be prefixed with '!'.  The value '!*' means only jobs with no project requested.

       pes    Contains a comma-separated list of PEs (see  sge_pe(5)).   This  parameter  filters
              jobs requesting a PE in the list. Any PE not in the list will not be considered for
              the resource quota rule. If no PE filter is specified, all PEs, and  jobs  with  no
              requested  PE,  match  the  rule.  The value '*' means all jobs requesting a PE. To
              exclude a PE from the rule, the name can be prefixed with '!'. The value '!*' means
              only jobs with no PE requested.

       queues Contains  a  comma-separated  list  of  cluster  queues  (see queue_conf(5)).  This
              parameter filters jobs that may be scheduled in a queue in the list.  Any queue not
              in  the  list will not be considered for the resource quota rule. The default value
              is '*', which means all queues. To exclude a queue from the rule, the name  can  be
              prefixed with '!'.

       hosts  Contains   a   comma-separated  list  of  hosts  or  hostgroups  (see  host(5)  and
              hostgroup(5)).  This parameter filters jobs that may be scheduled to a host in  the
              list  or a host contained in a hostgroup in the list. Any host not in the list will
              not be considered for the resource quota rule. The  default  value  is  '*',  which
              means  all  hosts.  To  exclude  a host or hostgroup from the rule, the name can be
              prefixed with '!'.

       to     This mandatory field defines the quota for resource attributes for this  rule.  The
              quota  is  expressed  by one or more comma-separated limit definitions referring to
              fixed or consumable resources (not load values).  Two kinds of limit definition may
              be used:

              static limits
                     Static  limits set static values as quotas. Each limit consists of a complex
                     attribute followed by an "=" sign and a value specification consistent  with
                     the complex attribute's type (see complex(5)).

              dynamic limits
                     A  dynamic  limit  is a simple algebraic expression used to derive the limit
                     value. The formula can reference complex attributes, whose value is used for
                     the  calculation  of  the resulting limit.  The formula expression syntax is
                     that of a sum of weighted complex values, that is:

                     {w1|$complex1[*w1]}[{+|-}{w2|$complex2[*w2]}[{+|-}...]]

                     The weighting factors (w1, ...) are  positive  integers  or  floating  point
                     numbers  in double precision. The complex values (complex1, ...)  must be of
                     numerical type (INT, DOUBLE, MEMORY, or TIME), as specified by the complex's
                     type  in  the  complex  list  (see complex(5)) and defined either on global,
                     queue, or host level to resolve the value.
                     Note: Dynamic limits can only be configured for a  host-specific  rule,  and
                     must  be defined for an expanded host list (or individual host).  Also, if a
                     load value corresponding to a complex used is not available, a  large  value
                     is  used for it to suggest an overloaded condition.  Dynamic limits may slow
                     the scheduler significantly.

       A complex form of limit may be used:  "expanded" filters with the consumer  list  enclosed
       in  braces  ('{'  '}').   This  may  be thought of as applying for each member of the list
       individually,  as  opposed  to  for  all  elements  of  a  non-braced   list   in   total.
       Alternatively,  it  is equivalent to an expansion into multiple instances of the rule, per
       the syntax which inspired it in shells such as bash(1).  Thus
              limit users {a, b} ... to ...
       is equivalent to
              limit users a ... to ...
              limit users b ... to ...
       where the text represented by the ellipses  in  each  position  is  carried  over  to  the
       expansion,  and  could  be expanded itself.  '{*}' represents a limit for each consumer of
       that type, as opposed to '*', which limits all the consumers together.  E.g.
              limit users * to slots=100
       limits the total number of slots in use to 100, whereas
              limit users {*} to slots=100
       limits each user to 100 slots.  ACLs and hostgroups in expanded lists are  treated  as  if
       they  are  expanded  into a list of their constituents before expanding the whole list.  A
       '!' prefix is distributed through the expansion of ACLs or hostgroups, i.e.
              limit users {!@acl,...} ...
       where @acl has members user1, user2, ..., expands to
              limit users {!user1,!user2,...} ...
       and thus
               limit users !user1 ...
               limit users !user2 ...
               ...

   Formal Syntax
       ALL:                   '*'
       SEPARATOR:             ','
       STRING:                [^\n]*
       QUOTE:                 '"'
       S_EXPANDER:            '{'
       E_EXPANDER:            '}'
       NOT:                   '!'
       BOOL:                  [tT][rR][uU][eE]
                              | 1
                              | [fF][aA][lL][sS][eE]
                              | 0
       NAME:                  [a-zA-Z][a-zA-Z0-9_-]*
       LISTVALUE:             ALL | [NOT]STRING
       LIST:                  LISTVALUE [SEPARATOR LISTVALUE]*
       FILTER:                LIST | S_EXPANDER LIST E_EXPANDER
       RESOURCEPAIR:          STRING=STRING
       RESOURCE:              RESOURCEPAIR [SEPARATOR RESOURCEPAIR]*

       rule:                  "limit" ["name" NAME] ["users" FILTER]
                              ["projects" FILTER] ["pes" FILTER] ["queues" FILTER]
                              ["hosts" FILTER] "to" RESOURCE NL

       ruleset_attributes:    "name" NAME NL
                              ["enabled" BOOL NL]
                              ["description" QUOTE STRING QUOTE NL]

       ruleset:               "{"
                              ruleset_attributes
                              rule+
                              "}" NL

       rulesets:              ruleset*

NOTES

       Please note that resource quotas are not enforced as job resource limits.   Limiting,  for
       example,  h_vmem  in  a resource quota set does not result in a memory limit being set for
       job execution; it is necessary to specify such a limit on  the  job  request,  or  as  the
       complex's default value.  Thus
              limit users {*} to h_vmem=2G
       will  not restrict the memory a job can actually allocate to 2G, only what it can request,
       with the request actually enforcing the allocation.

       The most restrictive rule in a set should be first in the limit List so that the scheduler
       can  dispatch  jobs efficiently by rejecting queues to consider as early as possible since
       subsequent rules in the list are not considered after one matches.  This can be  important
       in large clusters, in which RQS can significantly slow down scheduling.

EXAMPLES

       The  following  is  the  simplest  form  of  a  resource quota set. It restricts all users
       together to a maximal use of 100 slots in the whole cluster.  Similarly,  "slots=0"  could
       be used to prevent new jobs starting for draining the system.

       =======================================================================
       {
          name         max_u_slots
          description  "All users max use of 100 slots"
          enabled      true
          limit        to slots=100
       }
       =======================================================================

       The  next  example  restricts user1 and user2 to requesting 6g virtual_free, and all other
       users to requesting 4g virtual_free, on each host in hostgroup lx_hosts.

       =======================================================================
       {
          name         max_virtual_free_on_lx_hosts
          description  "resource quota for virtual_free restriction"
          enabled      true
          limit        users {user1,user2} hosts {@lx_host} to virtual_free=6g
          limit        users {*} hosts {@lx_host} to virtual_free=4g
       }
       =======================================================================

       The next example shows the use of a dynamic limit.  It restricts the total slot  usage  by
       all  users  on each host to twice the value of num_proc (the number of processor units) on
       the host.  (It would be more usual to use "slots=$num_proc" to  prevent  over-subscription
       of nodes.)

       =======================================================================
       {
          name         max_slots_on_every_host
          enabled      true
          limit        hosts {*} to slots=$num_proc*2
       }
       =======================================================================

SEE ALSO

       sge_intro(1),  access_list(5),  complex(5),  host(5),  hostgroup(5),  qconf(1), qquota(1),
       project(5).

COPYRIGHT

       See sge_intro(1) for a full statement of rights and permissions.