complex - Grid Engine complexes configuration file format
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
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.
The complex configuration should not be accessed directly. In order to add or
modify complex entries, the 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
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.
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
), 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 and attach a sufficiently high limit to
each host, e.g.
qconf -aattr exechost complex_values tmp_free=10T $(qconf -sel)
By default there is a selection of parameters in the queue configuration as
defined in The principal queue configuration parameters requestable for a job
by the user are:
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:
(Please refer to for details.)
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
The second attribute category in the standard host complex is that of the
default load values every periodically reports load to The reported load
values are either the standard Grid Engine load values, such as the CPU load
average (see or load values defined by the Grid Engine administration (see the
parameter in the cluster or host configuration (see 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 for detailed
information on the standard set of load values.
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
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.
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):
The name of the complex element to be used to request this attribute for a job
in the -l
option. A complex attribute name (see complex_name
may appear only once across all complexes, i.e. the complex attribute
definition is unique.
A shortcut for name
which may also be used to request this attribute for
a job in the -l
option. A given shortcut may appear only once across
all complexes, so as to avoid the possibility of ambiguous complex attribute
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
- 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 for
a format description.
- With MEMORY memory size specifiers are allowed.
Refer to for a format description.
- With BOOL the strings TRUE and FALSE are allowed.
When used in a load formula (refer to TRUE and FALSE get mapped into '1'
- With STRING all strings are allowed and are used for
wildcard regular boolean expression matching. Please see the man page for
-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-x86" :
results in "arch=lx22-x86" OR "arch=lx24-x86"
-l arch="lx2[4-6]-x86" :
results in "arch=lx24-x86" OR "arch=lx25-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
- 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.
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
The entry can be used in a 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 and
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
and 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 and The
definition of the "global" host specifies
cluster global consumable settings. To each consumable complex attribute in a
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.
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).
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.
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
to override this default value.
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 For string type requests the resource's urgency value is directly
used as addend. Urgency values are of type real. See under for an overview of
See for a full statement of rights and permissions.