lsb.serviceclasses

The lsb.serviceclasses file defines the service-level agreements (SLAs) in an LSF cluster as service classes, which define the properties of the SLA.

This file is optional.

You can configure as many service class sections as you need.

Use bsla to display the properties of service classes configured in lsb.serviceclasses and dynamic information about the state of each configured service class.

By default, lsb.serviceclasses is installed in LSB_CONFDIR/cluster_name/configdir.

Changing lsb.serviceclasses configuration

After making any changes to lsb.serviceclasses, run badmin reconfig to reconfigure mbatchd.

lsb.serviceclasses structure

Each service class definition begins with the line Begin ServiceClass and ends with the line End ServiceClass.

Syntax

Begin ServiceClass
NAME           = string
PRIORITY       = integer
GOALS          = [throughput | velocity | deadline] [\...]
CONTROL_ACTION = VIOLATION_PERIOD[minutes] CMD [action]
USER_GROUP     = all | [user_name] [user_group] ...
DESCRIPTION    = text

End ServiceClass

Begin ServiceClass

NAME           = string
GOALS          = guarantee
ACCESS_CONTROL = [QUEUES[ queue ...]] [USERS[ [user_name] [user_group] ...]] 
[FAIRSHARE_GROUPS[user_group ...]] [APPS[app_name ...]] 
[PROJECTS[proj_name...]] 
AUTO_ATTACH = Y | y | N | n
DESCRIPTION    = text

End ServiceClass
You must specify:
  • Service class name
  • Goals

Service classes with guarantee goals cannot have PRIORITY, CONTROL_ACTION or USER_GROUP defined.

To configure EGO-enabled SLA scheduling, you must specify an existing EGO consumer name to allow the SLA to get host allocations from EGO.

All other parameters are optional.

Example

Begin ServiceClass 

NAME=Sooke
PRIORITY=20
GOALS=[DEADLINE timeWindow (8:30-16:00)] 
DESCRIPTION="working hours"

End ServiceClass

Begin ServiceClass 
NAME=Newmarket 
GOALS=[GUARANTEE] 
ACCESS_CONTROL = QUEUES[batch] FAIRSHARE_GROUPS[team2]
AUTO_ATTACH = Y
DESCRIPTION="guarantee for team2 batch jobs" 

End ServiceClass

Parameters

  • ACCESS_CONTROL
  • AUTO_ATTACH
  • CONSUMER
  • CONTROL_ACTION
  • DESCRIPTION
  • EGO_RES_REQ
  • EGO_RESOURCE_GROUP
  • GOALS
  • MAX_HOST_IDLE_TIME
  • NAME
  • PRIORITY
  • USER_GROUP

ACCESS_CONTROL

Syntax

ACCESS_CONTROL=[QUEUES[queue ...]] [USERS[ [user_name] [user_group] ...]] [FAIRSHARE_GROUPS[user_group ...]] [APPS[app_name ...]] [PROJECTS[proj_name...]] [LIC_PROJECTS[lic_proj...]]

Description

Guarantee SLAs (with GOALS=[GUARANTEE]) only.

Restricts access to a guarantee SLA. If more than one restriction is configured, all must be satisfied.

  • QUEUES restricts access to the queues listed; the queue is specified for jobs at submission using bsub -q.
  • USERS restricts access to jobs submitted by the users or user groups specified.

    User names must be valid login names. To specify a Windows user account, include the domain name in uppercase letters (DOMAIN_NAME\user_name).User group names can be LSF user groups or UNIX and Windows user groups. To specify a Windows user group, include the domain name in uppercase letters (DOMAIN_NAME\user_group).

  • FAIRSHARE_GROUPS restricts access to the fair share groups listed; the fair share group is specified for jobs at submission using bsub -G.
  • APPS restricts access to the application profiles listed; the application profile is specified for jobs at submission using bsub -app.
  • PROJECTS restricts access to the projects listed; the project is specified for jobs at submission using bsub -P.

Example

ACCESS_CONTROL = QUEUES[normal short] USERS[ug1]

Jobs submitted to the queues normal or short by users in usergroup ug1 are the only jobs accepted by the guarantee SLA.

Default

None. Access to the guarantee SLA is not restricted.

AUTO_ATTACH

Syntax

AUTO_ATTACH=Y | y | N | n

Description

Guarantee SLAs (with GOALS=[GUARANTEE]) only. Used with ACCESS_CONTROL.

Enabling AUTO_ATTACH when a guarantee SLA has ACCESS_CONTROL configured results in submitted jobs automatically attaching to the guarantee SLA if they have access. If a job can access multiple guarantee SLAs with AUTO_ATTACH enabled, the job is automatically attached to the first accessible SLA based on configuration order in the lsb.serviceclasses file.

During restart or reconfiguration, automatic attachments to guarantee SLAs are checked and jobs may be attached to a different SLA. During live reconfiguration (using the bconf command) automatic attachments are not checked, and jobs remain attached to the same guarantee SLAs regardless of configuration changes.

Example

Begin ServiceClass
...
NAME = Maple

GOALS = [GUARANTEE]
ACCESS_CONTROL = QUEUES[priority] USERS[ug1]
AUTO_ATTACH = Y

...
End ServiceClass

All jobs submitted to the priority queue by users in user group ug1 and submitted without an SLA specified are automatically attached to the service class Maple.

Default

N

CONSUMER

Syntax

CONSUMER=ego_consumer_name

Description

For EGO-enabled SLA service classes, the name of the EGO consumer from which hosts are allocated to the SLA. This parameter is not mandatory, but must be configured for the SLA to receive hosts from EGO.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have CONSUMER set. If defined, it will be ignored.
Important: CONSUMER must specify the name of a valid consumer in EGO. If a default SLA is configured with ENABLE_DEFAULT_EGO_SLA in lsb.params, all services classes configured in lsb.serviceclasses must specify a consumer name.

Default

None

CONTROL_ACTION

Syntax

CONTROL_ACTION=VIOLATION_PERIOD[minutes] CMD [action]

Description

Optional. Configures a control action to be run if the SLA goal is delayed for a specified number of minutes.

If the SLA goal is delayed for longer than VIOLATION_PERIOD, the action specified by CMD is invoked. The violation period is reset and if the SLA is still active when the violation period expires again, the action runs again. If the SLA has multiple active goals that are in violation, the action is run for each of them.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have CONTROL_ACTION set. If defined, it will be ignored.

Example

CONTROL_ACTION=VIOLATION_PERIOD[10] CMD [echo `date`: SLA is in violation >> 
! /tmp/sla_violation.log]

Default

None

DESCRIPTION

Syntax

DESCRIPTION=text

Description

Optional. Description of the service class. Use bsla to display the description text.

This description should clearly describe the features of the service class to help users select the proper service class for their jobs.

The text can include any characters, including white space. The text can be extended to multiple lines by ending the preceding line with a backslash (\).

Default

None

EGO_RES_REQ

Syntax

EGO_RES_REQ=res_req

Description

For EGO-enabled SLA service classes, the EGO resource requirement that specifies the characteristics of the hosts that EGO will assign to the SLA.

Must be a valid EGO resource requirement. The EGO resource requirement string supports the select section, but the format is different from LSF resource requirements.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have EGO_RES_REQ set. If defined, it will be ignored.

Note: After changing this parameter, running jobs using the allocation may be re-queued.

Example

EGO_RES_REQ=select(linux && maxmem > 100)

Default

None

EGO_RESOURCE_GROUP

Syntax

EGO_RESOURCE_GROUP=ego resource group name or a blank separated group list

Description

For EGO-enabled SLA service classes. A resource group or space-separated list of resource groups from which hosts are allocated to the SLA.

List must be a subset of or equal to the resource groups allocated to the consumer defined by the CONSUMER entry.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have EGO_RESOURCE_GROUP set. If defined, it will be ignored.

Note: After changing this parameter, running jobs using the allocation may be re-queued.

Example

EGO_RESOURCE_GROUP=resource_group1 resource_group4 resource_group5

Default

Undefined (vemkd determines which resource groups to allocate slots to LSF).

GOALS

Syntax

GOALS=[throughput | velocity | deadline] [\

[throughput | velocity | deadline] ...]

GOALS=[guarantee]

Description

Required. Defines the service-level goals for the service class. A service class can have more than one goal, each active at different times of the day and days of the week. Outside of the time window, the SLA is inactive and jobs are scheduled as if no service class is defined. LSF does not enforce any service-level goal for an inactive SLA.

Note: The throughput, velocity, and deadline goals are deprecated and might be removed in a future release. Only the guarantee goals are supported.

The time windows of multiple service-level goals can overlap. In this case, the largest number of jobs is run.

An active SLA can have a status of On time if it is meeting the goal, and a status Delayed, if it is missing its goals.

A service-level goal defines:

throughput - expressed as finished jobs per hour and an optional time window when the goal is active. throughput has the form:

GOALS=[THROUGHPUT num_jobs timeWindow [(time_window)]]

If no time window is configured, THROUGHPUT can be the only goal in the service class. The service class is always active, and bsla displays ACTIVE WINDOW: Always Open.

velocity - expressed as concurrently running jobs and an optional time window when the goal is active. velocity has the form:

GOALS=[VELOCITY num_jobs timeWindow [(time_window)]]

If no time window is configured, VELOCITY can be the only goal in the service class. The service class is always active, and bsla displays ACTIVE WINDOW: Always Open.

deadline - indicates that all jobs in the service class should complete by the end of the specified time window. The time window is required for a deadline goal. deadline has the form:
GOALS=[DEADLINE timeWindow (time_window)]
guarantee - indicates the SLA has guaranteed resources defined in lsb.resources and is able to guarantee resources, depending on the scavenging policies configured. Guarantee goals cannot be combined with any other goals, and do not accept time windows.
GOALS=[GUARANTEE]
Restriction: EGO-enabled SLA service classes only support velocity goals. Deadline, throughput, and guarantee goals are not supported. The configured velocity value for EGO-enabled SLA service classes is considered to be a minimum number of jobs that should be in run state from the SLA

Time window format

The time window of an SLA goal has the standard form:
begin_time-end_time
Times are specified in the format:
[day:]hour[:minute]
where all fields are numbers with the following ranges:
  • day of the week: 0-6 (0 is Sunday)
  • hour: 0-23
  • minute: 0-59
Specify a time window one of the following ways:
  • hour-hour
  • hour:minute-hour:minute
  • day:hour:minute-day:hour:minute

The default value for minute is 0 (on the hour); the default value for day is every day of the week.

You must specify at least the hour. Day of the week and minute are optional. Both the start time and end time values must use the same syntax. If you do not specify a minute, LSF assumes the first minute of the hour (:00). If you do not specify a day, LSF assumes every day of the week. If you do specify the day, you must also specify the minute.

You can specify multiple time windows, but they cannot overlap. For example:
timeWindow(8:00-14:00 18:00-22:00)
is correct, but
timeWindow(8:00-14:00 11:00-15:00)
is not valid.
Tip: To configure a time window that is always open, use the timeWindow keyword with empty parentheses.

Examples

GOALS=[THROUGHPUT 2 timeWindow ()]
GOALS=[THROUGHPUT 10 timeWindow (8:30-16:30)]
GOALS=[VELOCITY 5 timeWindow ()]
GOALS=[DEADLINE timeWindow (16:30-8:30)] [VELOCITY 10 timeWindow (8:30-16:30)]
GOALS=[GUARANTEE]

MAX_HOST_IDLE_TIME

Syntax

MAX_HOST_IDLE_TIME=seconds

Description

For EGO-enabled SLA service classes, number of seconds that the SLA will hold its idle hosts before LSF releases them to EGO. Each SLA can configure a different idle time. Do not set this parameter to a small value, or LSF may release hosts too quickly.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have MAX_HOST_IDLE_TIME set. If defined, it will be ignored.

Default

120 seconds

NAME

Syntax

NAME=string

Description

Required. A unique name that identifies the service class.

Specify any ASCII string 60 characters or less. You can use letters, digits, underscores (_) or dashes (-). You cannot use blank spaces.
Important: The name you use cannot be the same as an existing host partition, user group name, or fair share queue name.

Example

NAME=Tofino

Default

None. You must provide a unique name for the service class.

PRIORITY

Syntax

PRIORITY=integer

Description

Required (time-based SLAs only). The service class priority. A higher value indicates a higher priority, relative to other service classes. Similar to queue priority, service classes access the cluster resources in priority order.

LSF schedules jobs from one service class at a time, starting with the highest-priority service class. If multiple service classes have the same priority, LSF runs all the jobs from these service classes in first-come, first-served order.

Service class priority in LSF is completely independent of the UNIX scheduler's priority system for time-sharing processes. In LSF, the NICE parameter is used to set the UNIX time-sharing priority for batch jobs.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have PRIORITY set. If defined, it will be ignored.

Default

None.

USER_GROUP

Syntax

USER_GROUP=all | [user_name] [user_group] ...

Description

Optional. A space-separated list of user names or user groups who can submit jobs to the service class. Administrators, root, and all users or groups listed can use the service class.

Use the reserved word all to specify all LSF users. LSF cluster administrators are automatically included in the list of users, so LSF cluster administrators can submit jobs to any service class, or switch any user’s jobs into this service class, even if they are not listed.

If user groups are specified in lsb.users, each user in the group can submit jobs to this service class. If a group contains a subgroup, the service class policy applies to each member in the subgroup recursively. If the group can define fair share among its members, the SLA defined by the service class enforces the fair share policy among the users of the SLA.

User names must be valid login names. User group names can be LSF user groups (in lsb.users) or UNIX and Windows user groups.

Guarantee SLAs (with GOALS=[GUARANTEE]) cannot have USER_GROUP set. If defined, it will be ignored.

Example

USER_GROUP=user1 user2 ugroup1

Default

all (all users in the cluster can submit jobs to the service class)

Examples

  • The resource-based service class AccountingSLA guarantees hosts to the user group accountingUG for jobs submitted to the queue longjobs. Jobs submitted to this queue by this user group without an SLA specified will be automatically attached to the SLA. The guaranteed resource pools used by the SLA are configured in lsb.resources.
    Begin ServiceClass 

NAME=AccountingSLA 
GOALS=[GUARANTEE] 
DESCRIPTION="Guaranteed hosts for the accounting department" 
ACCESS_CONTROL = QUEUES[longjobs] USERS[accountingUG]
AUTO_ATTACH = Y

End ServiceClass
  • The service class Sooke defines one deadline goal that is active during working hours between 8:30 AM and 4:00 PM. All jobs in the service class should complete by the end of the specified time window. Outside of this time window, the SLA is inactive and jobs are scheduled without any goal being enforced:
    Begin ServiceClass 

NAME=Sooke
PRIORITY=20 
GOALS=[DEADLINE timeWindow (8:30-16:00)] 
DESCRIPTION="working hours" 

End ServiceClass
  • The service class Nanaimo defines a deadline goal that is active during the weekends and at nights.
    Begin ServiceClass 

NAME=Nanaimo 
PRIORITY=20 
GOALS=[DEADLINE timeWindow (5:18:00-1:8:30 20:00-8:30)] 
DESCRIPTION="weekend nighttime regression tests" 

End ServiceClass
  • The service class Sidney defines a throughput goal of 6 jobs per hour that is always active:
    Begin ServiceClass 

NAME=Sidney
PRIORITY=20 
GOALS=[THROUGHPUT 6 timeWindow ()] 
DESCRIPTION="constant throughput" 

End ServiceClass
  • The service class Tofino defines two velocity goals in a 24 hour period. The first goal is to have a maximum of 10 concurrently running jobs during business hours (9:00 AM to 5:00 PM). The second goal is a maximum of 30 concurrently running jobs during off-hours (5:30 PM to 8:30 AM)
    Begin ServiceClass 

NAME=Tofino 
PRIORITY=20 
GOALS=[VELOCITY 10 timeWindow (9:00-17:00)] [VELOCITY 30 timeWindow (17:30-8:30)]
DESCRIPTION="day and night velocity" 

End ServiceClass
  • The service class Duncan defines a velocity goal that is active during working hours (9:00 AM to 5:30 PM) and a deadline goal that is active during off-hours (5:30 PM to 9:00 AM) Only users user1 and user2 can submit jobs to this service class.
    Begin ServiceClass 

NAME=Duncan
PRIORITY=23 
USER_GROUP=user1 user2 
GOALS=[VELOCITY 8 timeWindow (9:00-17:30)] [DEADLINE timeWindow (17:30-9:00)]
DESCRIPTION="Daytime/Nighttime SLA" 

End ServiceClass
  • The service class Tevere defines a combination similar to Duncan, but with a deadline goal that takes effect overnight and on weekends. During the working hours in weekdays the velocity goal favors a mix of short and medium jobs.
    Begin ServiceClass 

NAME=Tevere 
PRIORITY=20 
GOALS=[VELOCITY 100 timeWindow (9:00-17:00)] [DEADLINE timeWindow (17:30-8:30 5:17:30-1:8:30)] 
DESCRIPTION="nine to five"

End ServiceClass