bionic (5) sge_complex.5.gz

Provided by: gridengine-common_8.1.9+dfsg-7build1_all bug

NAME

       complex - Grid Engine complexes configuration file format

DESCRIPTION

       Complex  reflects  the  format  of  the  Grid  Engine  complex  configuration.  The definition of complex
       attributes provides all pertinent information concerning the resource attributes a user may request for a
       Grid Engine job via the qsub(1) -l option, and for the interpretation of these parameters within the Grid
       Engine system.

       The Grid Engine complex object defines all entries which are used for configuring the global,  host,  and
       queue  objects.  The  system  has  a set of pre-defined entries, which are assigned to a host or queue by
       default.  In addition, the user can define new entries and assign them to one or more objects. Each  load
       value  has  to  have  a  corresponding  complex  entry  object, which defines the type and the relational
       operator for it.

   Defining resource attributes
       The complex configuration should not be accessed directly.  In order to add or  modify  complex  entries,
       the  qconf(1)  options  -Mc  and  -mc  should  be  used  instead.   While  the -Mc option takes a complex
       configuration file as an argument and overrides the current configuration, the -mc option  brings  up  an
       editor filled in with the current complex configuration.

       The provided list contains all definitions of resource attributes in the system. Adding a new entry means
       to provide: name, shortcut, type, relop, requestable, consumable, default, and urgency.  The  fields  are
       described  below.  Changing  one is easily done by updating the field to change, and removing an entry by
       deleting its definition. An attribute can only be removed when it is not referenced in a  host  or  queue
       object  anymore.  Also the system has a set of default resource attributes which are always attached to a
       host or queue. They cannot be deleted, nor can the type of such an attribute be changed.

   Working with resource attributes
       Before a user can request a resource attribute it has to be  attached  to  the  global,  host,  or  queue
       object.  The  resource attribute exists only for the objects to which it was attached.  If it is attached
       to the global object (qconf -me global), it exists system-wide.  Attached to a  host  object  (qconf  -me
       host), it exists only on that host, and attached to queue object (qconf -mq queue), only on that queue.

       When an administrator attaches a resource attribute to an object, they also have to assign a value to it:
       the resource limit.  A load sensor may be run to adjust the value presented by  a  host  down  from  that
       limit.   For instance, to support requests for free space in the /tmp filesystem, set up a load sensor to
       report the value (probably using df(1)) and attach a sufficiently high limit to each host, e.g.
       qconf -aattr exechost complex_values tmp_free=10T $(qconf -sel)

   Default queue resource attributes
       By default there is a selection of parameters in the queue configuration  as  defined  in  queue_conf(5).
       The principal queue configuration parameters requestable for a job by the user are:

              qname
              hostname
              notify
              calendar
              min_cpu_interval
              tmpdir
              seq_no
              s_rt
              h_rt
              s_cpu
              h_cpu
              s_data
              h_data
              s_stack
              h_stack
              s_core
              h_core
              s_rss
              h_rss

   Default host resource attributes
       The  standard  set  of host-related attributes consists of two categories. The first category is built by
       several queue configuration attributes which are particularly suitable to be managed  on  a  host  basis.
       These attributes are:

              slots
              s_vmem
              h_vmem
              s_fsize
              h_fsize

       (Please refer to queue_conf(5) for details.)

       Note:  Defining these attributes in the host complex is no contradiction to having them also in the queue
       configuration. It allows maintaining the corresponding resources on a host level, and at the same time on
       a queue level. Total virtual free memory (h_vmem) can be managed for a host, for example, and a subset of
       the total amount can be associated with a queue on that host.

       The second attribute category in the standard host complex is that  of  the  default  load  values  every
       sge_execd(8)  periodically  reports  load  to  sge_qmaster(8).   The  reported load values are either the
       standard Grid Engine load values, such as the CPU load average (see uptime(1)), or load values defined by
       the  Grid  Engine administration (see the load_sensor parameter in the cluster or host configuration (see
       sge_conf(5) for details).  The definition of characteristics for the standard load values is part of  the
       default  host  complex,  while  administrator-defined  load values require extension of the host complex.
       Please refer to load_parameters(5) for detailed information on the standard set of load values.

   Overriding attributes
       An attribute can be assigned to the global object, host object, and queue object at the same time. On the
       host  level  it  might  get  its  value  from  the  user-defined resource limit and a load sensor. If the
       attribute is a consumable, we have, in addition to the resource limit and its load report at host  level,
       also the internal usage which the system keeps track of. The merge is done as follows:

       In general an attribute can be overridden on a lower level
          - global by hosts and queues
          - hosts by queues and load values or resource limits on the same level.

       We have one limitation for overriding attributes based on their relational operator:

       !=  and  ==  operators  can  only be overridden on the same level, not on a lower level. The user-defined
       value always overrides the load value.

       >=, >, <=, and < operators can only be overridden when the new value is more  restrictive  than  the  old
       one.

       In the case of a consumable at host level which has also a load sensor, the system checks for the current
       usage, and if the internal accounting is more restrictive than the load sensor report, the internal value
       is kept; if the load sensor report is more restrictive, that one is kept.

FORMAT

       The  principal  format  of a complex configuration is that of a tabulated list. Each line starting with a
       '#' character is a comment line. Each non-comment line defines one element of the  complex.   Backslashes
       (\)  be  used  to  escape  newline  characters.  The  backslash and the newline are replaced with a space
       character before any interpretation.

       An element definition line consists of the following 8 column entries per line (in order of appearance):

   name
       The name of the complex element to be used to request this attribute for a job in the qsub(1) -l  option.
       A  complex  attribute  name (see complex_name in sge_types(5)) may appear only once across all complexes,
       i.e. the complex attribute definition is unique.

   shortcut
       A shortcut for name which may also be used to request this attribute for a job in the qsub(1) -l  option.
       A  given  shortcut may appear only once across all complexes, so as to avoid the possibility of ambiguous
       complex attribute references.

   type
       This setting determines how the corresponding values are to be  treated  by  Grid  Engine  internally  in
       comparisons or in load scaling for the load complex entries:

       •  With INT only raw integers are allowed.

       •  With  DOUBLE  floating  point  numbers  in  double  precision (decimal and scientific notation) can be
          specified.

       •  With TIME time specifiers are allowed. Refer to sge_types(5) for a format description.

       •  With MEMORY memory size specifiers are allowed. Refer to sge_types(5) for a format description.

       •  With BOOL  the  strings  TRUE  and  FALSE  are  allowed.  When  used  in  a  load  formula  (refer  to
          sched_conf(5)), TRUE and FALSE get mapped into '1' and '0'.

       •  With  STRING  all  strings  are allowed and are used for wildcard regular boolean expression matching.
          Please see the sge_types(5) man page for expression definition.

          Examples:
           -l arch="*x*|sol*"  :
                results in "arch=lx-x86" OR "arch=lx-amd64"
                   OR "arch=sol-amd64" OR ...
           -l arch="sol-x??"  :
                results in "arch=sol-x86" OR "arch=sol-x64" OR ...
           -l arch="lx2[246]-x86"  :
                results in "arch=lx22-x86" OR "arch=lx24-x86"
                   OR "arch=lx26-x86"
           -l arch="lx2[4-6]-x86"  :
                results in "arch=lx24-x86" OR "arch=lx25-x86"
                   OR "arch=lx26-x86"
           -l arch="lx2[24-6]-x86"  :
                results in "arch=lx22-x86" OR "arch=lx24-x86"
                   OR "arch=lx25-x86" OR "arch=lx26-x86"
           -l arch="!lx-x86&!sol-amd64"  :
                results in NEITHER "arch=lx-x86" NOR "arch=sol-amd64"
           -l arch="lx2[4|6]-amd64"  :
                results in "arch=lx24-amd64" OR "arch=lx26-amd64"

       •  CSTRING is like STRING except comparisons are case insensitive.

       •  RESTRING is the same as STRING for historical compatibility, but is deprecated and may be  removed  in
          future..

       •  HOST is like CSTRING but the expression must match a valid host name.

   relop
       The relation operator is used when the value requested by the user for this parameter is compared against
       the corresponding value configured for the considered queues. If the result of the comparison  is  false,
       the  job cannot run in this queue. Possible relation operators are "==", "<", ">", "<=", ">=" and "EXCL".
       The only valid operator for string type attributes is "==".

       The "EXCL" relation operator implements exclusive scheduling and is only  valid  for  consumable  boolean
       type  attributes.  Exclusive  means  the  result  of  the comparison is only true if a job requests to be
       exclusive, and no other exclusive or non-exclusive job uses the complex. If the job does not  request  to
       be exclusive and no other exclusive job uses the complex the comparison is also true.

   requestable
       The  entry can be used in a qsub(1) resource request if this field is set to 'y' or 'yes'.  If set to 'n'
       or 'no' this entry cannot be used by a user in order to request a queue or a class  of  queues.   If  the
       entry is set to 'forced' or 'f' the attribute has to be requested by a job, or it is rejected.

       To  enable resource request enforcement the existence of the resource has to be defined. This can be done
       on a cluster global, per host and per queue basis. The definition of resource availability  is  performed
       with the complex_values entry in host_conf(5) and queue_conf(5).

   consumable
       The  consumable parameter can be set to either 'yes' ('y' abbreviated), 'no' ('n') or 'JOB' ('j'). It can
       be set to 'yes' and 'JOB' only for numeric attributes (INT, DOUBLE, MEMORY, TIME - see  type  above).  If
       set  to  'yes'  or  'JOB'  the  consumption  of  the corresponding resource can be managed by Grid Engine
       internal bookkeeping. In this case Grid Engine accounts for the consumption  of  this  resource  for  all
       running  jobs and ensures that jobs are only dispatched if the Grid Engine internal bookkeeping indicates
       enough available consumable resources. Consumables are an efficient means  to  manage  limited  resources
       such as available memory, free space on a file system, network bandwidth or floating software licenses.

       A  consumable  defined by 'y' is a per-slot consumable, which means the limit is multiplied by the number
       of slots being used by the job before being applied.   In  case  of  'j'  the  consumable  is  a  per-job
       consumable.  This  resource  is  debited  as requested (without multiplication) from the allocated master
       queue. The resource need not be available for the slave task queues.

       Consumables  can  be  combined  with  default  or  user-defined  load  parameters  (see  sge_conf(5)  and
       host_conf(5)),  i.e. load values can be reported for consumable attributes, or the consumable flag can be
       set for load attributes. The Grid Engine consumable resource management takes both  the  load  (measuring
       availability of the resource) and the internal bookkeeping into account in this case, and makes sure that
       neither exceeds a given limit.

       To enable consumable resource management, the basic availability of a resource has to  be  defined.  This
       can  be  done  on a cluster global, per host and per queue basis, and these categories may supersede each
       other in the given order (i.e. a host can restrict availability of a cluster resource  and  a  queue  can
       restrict  host  and  cluster  resources).  The  definition of resource availability is performed with the
       complex_values entry in host_conf(5) and queue_conf(5).  The complex_values definition  of  the  "global"
       host   specifies  cluster  global  consumable  settings.  To  each  consumable  complex  attribute  in  a
       complex_values list, a value is assigned which denotes the maximum available amount  for  that  resource.
       The  internal  bookkeeping  will subtract from this total the assumed resource consumption by all running
       jobs as expressed through the jobs' resource requests.

       Note: Jobs can be forced to request a resource and thus to specify their assumed consumption via a forced
       value of the requestable parameter (see above).

       Note  also:  A  default resource consumption value can be pre-defined by the administrator for consumable
       attributes not explicitly requested by the job (see the default parameter below). This is meaningful only
       if requesting the attribute is not enforced as explained above.

   default
       Meaningful  only for consumable complex attributes (see consumable parameter above) and must be specified
       as 0 otherwise.  Grid Engine assumes the resource amount denoted in the default parameter  implicitly  to
       be  consumed  by  jobs  being  dispatched  to  a  host  or  queue managing the consumable attribute. Jobs
       explicitly requesting the attribute via the -l option to qsub(1) override this default value.

   urgency
       The urgency value allows influencing job priorities on a per-resource base. The urgency value effects the
       addend  for each resource when determining the resource request-related urgency contribution. For numeric
       type resource requests the addend is the product of the urgency value, the job's assumed slot allocation,
       and  the  per-slot  request  as  specified  via  the  -l option to qsub(1).  For string type requests the
       resource's urgency value is directly used  as  addend.  Urgency  values  are  of  type  real.  See  under
       sge_priority(5) for an overview of job priorities.

SEE ALSO

       sge_intro(1),    sge_types(1),    qconf(1),   qsub(1),   uptime(1),   host_conf(5),   load_parameters(5),
       queue_conf(5), sge_execd(8), sge_qmaster(8)

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