lsb.users

The lsb.users file is used to configure user groups, hierarchical fair share for users and user groups, and job slot limits for users and user groups. It is also used to configure account mappings in a multicluster environment.

This file is optional.

The lsb.users file is stored in the directory LSB_CONFDIR/cluster_name/configdir, where LSB_CONFDIR is defined in lsf.conf.

Changing lsb.users configuration

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

#INCLUDE

Syntax

#INCLUDE "path-to-file"

Description

Inserts a configuration setting from another file to the current location. Use this directive to dedicate control of a portion of the configuration to other users or user groups by providing write access for the included file to specific users or user groups, and to ensure consistency of configuration file settings in different clusters (if you are using the LSF multicluster capability).

For more information, see Shared configuration file content.

#INCLUDE can be inserted anywhere in the local configuration file.

Default

Not defined.

UserGroup section

Optional. Defines user groups.

The name of the user group can be used in other user group and queue definitions, as well as on the command line. Specifying the name of a user group in the GROUP_MEMBER section has exactly the same effect as listing the names of all users in the group.

The total number of user groups cannot be more than 1024.

Structure

The first line consists of two mandatory keywords, GROUP_NAME and GROUP_MEMBER. Other keywords are optional. Subsequent lines name a group and list its membership and optionally its share assignments and administrator.

Each line must contain one entry for each keyword. Use empty parentheses () or a dash - to specify the default value for an entry.

Restriction: If specifying a specific user name for a user group, that entry must precede all user groups.

Examples of a UserGroup section

Example 1:
Begin UserGroup 
GROUP_NAME          GROUP_MEMBER                 GROUP_ADMIN           PRIORITY
groupA              (user1 user2 user3 user4)    (user5[full])          100
groupB              (user7 user8 user9)          (groupA[usershares])   50
groupC              (groupA user5)               (groupA)               50
groupD              (!)                          ()                     10
Example 2:
Begin UserGroup 
GROUP_NAME           GROUP_MEMBER                 GROUP_ADMIN     PRIORITY
groupA               (user1 user2 user3 user4)    (user5)         200
groupB               (groupA user5)               (groupA)        100
groupC               (!)                          ()              50
End UserGroup
Example 3:
Begin UserGroup 
GROUP_NAME   GROUP_MEMBER            USER_SHARES                PRIORITY 
groupB       (user1 use r2)          ()                         100
groupC       (user3 user4)           ([User3,3] [User4,4])      200
groupA       (GroupB GroupC user5)   ([User5,1] [default,10])   50
End UserGroup

GROUP_NAME

An alphanumeric string representing the user group name. You cannot use the reserved name all or a "/" in a group name.

FS_POLICY

Syntax

(global_fairshare_policy_name ...)

Description

Optional. Enables partial SYNC_MODE global fair share policy for the defined user group. It specifies which partial SYNC_MODE global fair share policy the share account will participate into.

Default

Not defined.

Example

Begin UserGroup
GROUP_NAME   GROUP_MEMBER  USER_SHARES          FS_POLICY
group1       (user1 user2) ([default, 10])      (utopia)
End UserGroup

GROUP_MEMBER

User group members are the users who belong to the group. You can specify both user names and user group names.

User and user group names can appear on multiple lines because users can belong to multiple groups.

Note: When a user belongs to more than one group, any of the administrators specified for any of the groups the user belongs to can control that users’ jobs. Limit administrative control by defining STRICT_UG_CONTROL=Y in lsb.params and submitting jobs with the -G option, specifying which user group the job is submitted with.

User groups may be defined recursively but must not create a loop.

Syntax

(user_name | user_group ...) | (all) | (!)

Enclose the entire group member list in parentheses. Use space to separate multiple names.

You can combine user names and user group names in the same list.

Valid values

all
The reserved name all specifies all users in the cluster.
!
An exclamation mark (!) indicates an externally-defined user group, which the egroup executable retrieves.
user_name
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
User group names can be LSF user groups defined previously in this section, or UNIX and Windows user groups.

If you specify a name that is both a UNIX user group and also a UNIX user, append a backslash to make sure it is interpreted as a group (user_group/).

To specify a Windows user group, include the domain name in uppercase letters (DOMAIN_NAME\user_group).

GROUP_ADMIN

User group administrators can administer the jobs of group members. You can specify both user names and user group names.

  • If you specify a user group as an administrator for another user group, all members of the first user group become administrators for the second user group.
  • You can also specify that all users of a group are also administrators of that same group.
  • Users can be administrators for more than one user group at the same time.
    Note: When a user belongs to more than one group, any of the administrators specified for any of the groups the user belongs to can control that users' jobs. Define STRICT_UG_CONTROL=Y in lsb.params to limit user group administrator control to the user group specified by -G at job submission.

By default a user group administrator has privileges equivalent to those of a job owner, and is allowed to control any job belonging to member users of the group they administer. A user group administrator can also resume jobs stopped by the LSF administrator or queue administrator if the job belongs to a member of their user group.

Optionally, you can specify additional user group administrator rights for each user group administrator.

User group administrator rights are inherited. For example, if admin2 has full rights for user group ugA and user group ugB is a member of ugA, admin2 also has full rights for user group ugB.

Restriction: Unlike a job owner, a user group administrator cannot run brestart and bread -a data_file.

To manage security concerns, you cannot specify user group administrators for any user group containing the keyword all as a member unless STRICT_UG_CONTROL=Y is defined in lsb.params.

Syntax

(user_name | user_name[admin_rights] | user_group | user_group[admin_rights] ...)

Enclose the entire group administrator list in parentheses. If you specify administrator rights for a user or group, enclose them in square brackets.

You can combine user names and user group names in the same list. Use space to separate multiple names.

Valid values

  • user_name

    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

    User group names can be LSF user groups defined previously in this section, or UNIX and Windows user groups.

    If you specify a name that is both a UNIX user group and also a UNIX user, append a backslash to make sure it is interpreted as a group (user_group/).

    To specify a Windows user group, include the domain name in uppercase letters (DOMAIN_NAME\user_group).

  • admin_rights
    • If no rights are specified, only default job control rights are given to user group administrators.
    • usershares: user group administrators with usershares rights can adjust user shares using bconf update.
    • full: user group administrators with full rights can use bconf to delete the user group, create new user groups, and adjust usershares, group members, and user group priorities.

      User group administrators with full rights can only add a user group member to the user group if they also have full rights for the member user group.

      User group administrators adding a new user group with bconf create are automatically added to GROUP_ADMIN with full rights for the new user group.

Restrictions

  • Wildcard and special characters are not supported (for example: *, !, $, #, &, ~)
  • The reserved keywords others, default, allremote are not supported.
  • User groups with the keyword all as a member can only have user group administrators configured if STRICT_UG_CONTROL=Y is defined in lsb.params.
  • User groups with the keyword all as a member cannot be user group administrators.
  • User groups and user groups administrator definitions cannot be recursive or create a loop.

PRIORITY

Optional. Specifies a priority that is used as a factor when calculating the job priority for absolute job priority scheduling (APS).

Valid values

Specify an integer between 0 and 2147483646. A larger value represents a higher priority.

Default

Not defined.

If APS is enabled for users, user groups, or application profiles, the default value is 0.

USER_SHARES

Optional. Enables hierarchical fair share and defines a share tree for users and user groups.

By default, when resources are assigned collectively to a group, the group members compete for the resources according to FCFS scheduling. You can use hierarchical fair share to further divide the shares among the group members.

Syntax

([user, number_shares])

Specify the arguments as follows:
  • Enclose the list in parentheses, even if you do not specify any user share assignments.
  • Enclose each user share assignment in square brackets, as shown.
  • Separate the list of share assignments with a space.
  • user: specify users or user groups. You can assign the shares to:
    • A single user (specify user_name). To specify a Windows user account, include the domain name in uppercase letters (DOMAIN_NAME\user_name).
    • Users in a group (specify group_name). To specify a Windows user group, include the domain name in uppercase letters (DOMAIN_NAME\group_name).
    • Users not included in any other share assignment, individually (specify the keyword default) or collectively (specify the keyword others).
    Note: By default, when resources are assigned collectively to a group, the group members compete for the resources on a first-come, first-served (FCFS) basis. You can use hierarchical fair share to further divide the shares among the group members. When resources are assigned to members of a group individually, the share assignment is recursive. Members of the group and of all subgroups always compete for the resources according to FCFS scheduling, regardless of hierarchical fair share policies.
  • number_shares: specify a positive integer representing the number of shares of the cluster resources assigned to the user. The number of shares assigned to each user is only meaningful when you compare it to the shares assigned to other users or to the total number of shares. The total number of shares is just the sum of all the shares assigned in each share assignment.

User section

Optional. If this section is not defined, all users and user groups can run an unlimited number of jobs in the cluster.

This section defines the maximum number of jobs a user or user group can run concurrently in the cluster. This is to avoid situations in which a user occupies all or most of the system resources while other users’ jobs are waiting.

Structure

One field is mandatory: USER_NAME.

All other fields are optional.

You must specify a dash (-) to indicate the default value (unlimited) if a user or user group is specified. Fields cannot be left blank.

Example of a User section

Begin User 
USER_NAME   MAX_JOBS   JL/P   MAX_PEND_JOBS     PRIORITY
user1       10          -        1000           200
user2        4          -           -           100
user3        -          -           -           300
groupA      10          1      100000           400
groupA@      -          1         100           200
groupC       -          -         500           100
default      6          1          10             0
End User

USER_NAME

User or user group for which job slot limits are defined.

Use the reserved user name default to specify a job slot limit that applies to each user and user group not explicitly named. Since the limit specified with the keyword default applies to user groups also, make sure you select a limit that is high enough, or explicitly define limits for user groups.

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

Job slot limits apply to a group as a whole. Append the at sign (@) to a group name to make the job slot limits apply individually to each user in the group. If a group contains a subgroup, the job slot limit also applies to each member in the subgroup recursively.

If the group contains the keyword all in the user list, the at sign (@) has no effect. To specify job slot limits for each user in a user group containing all, use the keyword default.

MAX_JOBS

Per-user or per-group job slot limit for the cluster. Total number of job slots that each user or user group can use in the cluster.

Note: If a group contains the keyword all as a member, all users and user groups are included in the group. The per-group job slot limit set for the group applies to the group as a whole, limiting the entire cluster even when ENFORCE_ONE_UG_LIMIT is set in lsb.params.

JL/P

Per processor job slot limit per user or user group.

Total number of job slots that each user or user group can use per processor. This job slot limit is configured per processor so that multiprocessor hosts will automatically run more jobs.

This number can be a fraction such as 0.5, so that it can also serve as a per-host limit. This number is rounded up to the nearest integer equal to or greater than the total job slot limits for a host. For example, if JL/P is 0.5, on a 4-CPU multiprocessor host, the user can only use up to 2 job slots at any time. On a uniprocessor machine, the user can use 1 job slot.

MAX_PEND_JOBS

Per-user or per-group pending job limit. This is the total number of pending jobs that each user or user group can have in the system. If a user is a member of multiple user groups, the user’s pending jobs are counted towards the pending job limits of all groups from which the user has membership.

If ENFORCE_ONE_UG_LIMITS is set to Y in lsb.params and you submit a job while specifying a user group, only the limits for that user group (or any parent user group) apply to the job even if there are overlapping user group members.

MAX_PEND_SLOTS

Per-user or per-group pending job slot limit. This is the total number of pending job slots that each user or user group can have in the system. If a user is a member of multiple user groups, the user’s pending jobs are counted towards the pending job slot limits of all groups from which the user has membership.

If ENFORCE_ONE_UG_LIMITS is set to Y in lsb.params and you submit a job while specifying a user group, only the limits for that user group (or any parent user group) apply to the job even if there are overlapping user group members.

PRIORITY

Optional. Specifies a priority that is used as a factor when calculating the job priority for absolute job priority scheduling (APS).

Valid values

Specify an integer between 0 and 2147483646.

Default

Not defined.

If APS is enabled for users, user groups, or application profiles, the default value is 0.

UserMap section

Optional. Used only in a multicluster environment with a non-uniform user name space. Defines system-level cross-cluster account mapping for users and user groups, which allows users to submit a job from a local host and run the job as a different user on a remote host. Both the local and remote clusters must have corresponding user account mappings configured.

Structure

The following three fields are all required:
  • LOCAL
  • REMOTE
  • DIRECTION
LOCAL
A list of users or user groups in the local cluster. To specify a Windows user account or user group, include the domain name in uppercase letters (DOMAIN_NAME\user_name or DOMAIN_NAME\user_group). Separate multiple user names by a space and enclose the list in parentheses: 
(user4 user6)
REMOTE
A list of remote users or user groups in the form user_name@cluster_name or user_group@cluster_name. To specify a Windows user account or user group, include the domain name in uppercase letters (DOMAIN_NAME\user_name@cluster_name or DOMAIN_NAME\user_group@cluster_name). Separate multiple user names by a space and enclose the list in parentheses: 
(user4@cluster2 user6@cluster2)
DIRECTION
Specifies whether the user account runs jobs locally or remotely. Both directions must be configured on the local and remote clusters.
  • The export keyword configures local users/groups to run jobs as remote users or user groups.
  • The import keyword configures remote users/groups to run jobs as local users or user groups.

Example of a UserMap section

On cluster1:
Begin UserMap 
LOCAL    REMOTE                             DIRECTION 
user1    user2@cluster2                     export 
user3    user6@cluster2    export 
End UserMap
On cluster2:
Begin UserMap 
LOCAL    REMOTE                             DIRECTION 
user2    user1@cluster1                     import 
user6    user3@cluster1                     import 
End UserMap

Cluster1 configures user1 to run jobs as user2 and user3 to run jobs as user6.

Cluster2 configures user1 to run jobs as user2 and user3 to run jobs as user6.

Automatic time-based configuration

Variable configuration is used to automatically change LSF configuration based on time windows. You define automatic configuration changes in the lsb.users file by using if-else constructs and time expressions. After you change the files, reconfigure the cluster with the badmin reconfig command.

The expressions are evaluated by LSF every 10 minutes based on mbatchdstart time. When an expression evaluates true, LSF dynamically changes the configuration based on the associated configuration statements. Reconfiguration is done in real time without restarting mbatchd, providing continuous system availability.

Example

From 12 - 1 p.m. daily (in Eastern Daylight Time), user smith has 10 job slots, but during other hours, user has only 5 job slots.
Begin User
USER_NAME  MAX_JOBS  JL/P
#if time(12-13 EDT)
smith      10         -
#else
smith       5         -
default     1         -
#endif
End User

Specifying the time zone is optional. If you do not specify a time zone, LSF uses the local system time zone. LSF supports all standard time zone abbreviations.