lsb.users

The lsb.users file is used to configure user groups, hierarchical fairshare 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.

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. The USER_SHARES and GROUP_ADMIN 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.

Example of a UserGroup section

Begin UserGroup 
GROUP_NAME GROUP_MEMBER GROUP_ADMIN
groupA       (user1 user2 user3 user4) (user5)
groupB       (groupA user5) (groupA)
groupC       (!) ()
End UserGroup
Begin UserGroup 
GROUP_NAME   GROUP_MEMBER            USER_SHARES 
groupB       (user1 user2)           () 
groupC       (user3 user4)           ([User3,3] [User4,4]) 
groupA       (GroupB GroupC user5)   ([User5,1] [default,10]) 
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.

GROUP_MEMBER

A list of user names or user group names that belong to the group, enclosed in parentheses and separated by spaces.

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 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) | (!)

Specify the following, all enclosed in parentheses:

user_name | user_group

User and user group names, separated by spaces. 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 defined previously in this section, or UNIX and Windows user groups. To specify a Windows user group, include the domain name in uppercase letters (DOMAIN_NAME\user_group).

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.

GROUP_ADMIN

User group administrators are a list of user names or user group names that administer the jobs of the group members, enclosed in parentheses and separated by spaces.

A user group administrator is allowed to control any jobs of the members of the user 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.

A user group administrator has privileges equivalent to those of a job owner. A user group administrator can control any job belonging to member users of the group they administer.

Restriction:

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

To manage security concerns, you cannot specify the keyword ALL for any user group administrators.

Syntax

(user_name | user_group ...)

Specify the following, all enclosed in parentheses:

user_name | user_group

User and user group names, separated by spaces. 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 defined previously in this section, or UNIX and Windows user groups. To specify a Windows user group, include the domain name in uppercase letters (DOMAIN_NAME\user_group).

Valid values

  • You can specify a user group as an administrator for another user group. In that case, 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.

Restrictions

  • Wildcard and special characters are not supported (for example: *, !, $, #, &, ~)

  • The reserved keywords ALL, others, default, allremote are not supported.

    User groups with members defined with the keyword ALL are also not allowed as a user group administrator.

  • User groups and user groups administrator definitions cannot be recursive or create a loop.

USER_SHARES

Optional. Enables hierarchical fairshare 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 fairshare 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, individually (specify group_name@) or collectively (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 default).

    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 fairshare 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 fairshare 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

Three fields are mandatory: USER_NAME, MAX_JOBS, JL/P.

MAX_PEND_JOBS is 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 
user1       10          -        1000 
user2        4          -           - 
user3        -          -           - 
groupA      10          1      100000 
groupA@      -          1         100 
groupC       -          -         500 
default      6          1          10 
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 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 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.

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/groups.

  • The import keyword configures remote users/groups to run jobs as local users/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 lsb.users 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 mbatchd start 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, 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)
smith      10         -
#else
smith       5         -
default     1         -
#endif
End User