External host and user groups

Use the external host and user groups feature to maintain group definitions for your site in a location external to LSF, and to import the group definitions on demand.

About external host and user groups

LSF provides you with the option to configure host groups, user groups, or both. When the membership of a host or user group changes frequently, or when the group contains a large number of members, you can use an external executable called egroup to retrieve a list of members rather than having to configure the group membership manually. You can write a site-specific egroup executable that retrieves host or user group names and the hosts or users that belong to each group.

You can write your egroup executable to retrieve group members for:
  • One or more host groups

  • One or more user groups

  • Any combination of host and user groups

LSF does not include a default egroup; you should write your own executable to meet the requirements of your site.

Default behavior (feature not enabled)

The following illustrations show the benefits of using the external host and user groups feature.

With external host and user groups enabled

Scope


Applicability

Details

Operating system

  • UNIX

  • Windows

  • A mix of UNIX and Windows hosts

Dependencies

  • UNIX and Windows user accounts must be valid on all hosts in the cluster and must have the correct permissions to successfully run jobs.

  • You must reconfigure the cluster using badmin reconfig each time you want to run the egroup executable to retrieve host or user group members.

Limitations

  • The egroup executable works with static hosts only; you cannot use an egroup executable to add a dynamically added host to a host group.

Not used with

  • Host groups when you have configured EGO-enabled service-level agreement (SLA) scheduling, because EGO resource groups replace LSF host groups.


Configuration to enable external host and user groups

To enable the use of external host and user groups, you must
  • Define the host group in lsb.hosts, or the user group in lsb.users, and put an exclamation mark (!) in the GROUP_MEMBER column.

  • Create an egroup executable in the directory specified by the parameter LSF_SERVERDIR in lsf.conf. LSF does not include a default egroup; you should write your own executable to meet the requirements of your site.

  • Run the command badmin reconfig to reconfigure the cluster and import your external host and user groups.

Define an external host or user group

External host groups are defined in lsb.hosts, and external user groups are defined in lsb.users. Your egroup executable must define the same group names that you use in the lsb.hosts and lsb.users configuration files.


Configuration file

Parameter and syntax

Default behavior

lsb.hosts

GROUP_NAME GROUP_MEMBER

hostgroup_name (!)

  • Enables the use of an egroup executable to retrieve external host group members.

  • The hostgroup_name specified in lsb.hosts must correspond to the group name defined by the egroup executable.

  • You can configure one or more host groups to use the egroup executable.

  • LSF does not support the use of external host groups that contain dynamically added hosts.

lsb.users

GROUP_NAME GROUP_MEMBER

usergroup_name (!)

  • Enables the use of an egroup executable to retrieve external user group members.

  • The usergroup_name specified in lsb.users must correspond to the group name defined by the egroup executable.

  • You can configure one or more user groups to use the egroup executable.


Create an egroup executable

The egroup executable must
  • Be located in LSF_SERVERDIR and follow these naming conventions:

    Operating system

    Naming convention

    UNIX

    LSF_SERVERDIR\egroup

    Windows

    LSF_SERVERDIR\egroup.exe

    or

    LSF_SERVERDIR\egroup.bat


  • Run when invoked by the commands egroup –m hostgroup_name and egroup –u usergroup_name. When mbatchd finds an exclamation mark (!) in the GROUP_MEMBER column of lsb.hosts or lsb.users, mbatchd runs the egroup command to invoke your egroup executable.

  • Output a space-delimited list of group members (hosts, users, or both) to stdout.

  • Retrieve a list of static hosts only. You cannot use the egroup executable to retrieve hosts that have been dynamically added to the cluster.

The following example shows a simple egroup script that retrieves both host and user group members:

#!/bin/sh 
if [ "$1"="-m" ]; then                              #host group    
if  [ "$2"="linux_grp" ]; then                   #Linux hostgroup
        echo "linux01 linux 02 linux03 linux04"
    elif [ "$2"="sol_grp" ]; then                   #Solaris hostgroup
        echo "Sol02 Sol02 Sol03 Sol04"    
 fi
else                                                  #user group
 if [ "$2"="srv_grp" ]; then                     #srvgrp user group
        echo "userA userB userC userD"
    elif [ "$2"="dev_grp" ]; then                   #devgrp user group
        echo "user1 user2 user3 user4"
 fi
fi 

External host and user groups behavior

On restart and reconfiguration, mbatchd invokes the egroup executable to retrieve external host and user groups and then creates the groups in memory; mbatchd does not write the groups to lsb.hosts or lsb.users. The egroup executable runs under the same user account as mbatchd. By default, this is the root account on UNIX hosts and the cluster administrator account on Windows hosts.

Once LSF creates the groups in memory, the external host and user groups work the same way as any other LSF host and user groups, including configuration and batch command usage.

Configuration to modify external host and user groups

Not applicable: There are no parameters that modify the behavior of the egroup executable.

By defining additional parameters in lsb.hosts and lsb.users, however, you can configure the behavior of your external host and user groups the same way as you would for any LSF host or user group.

External host and user groups commands

Commands to submit workload


Command

Description

bsub -m host_group

  • Submits a job to run on any host that belongs to the specified host group.

bsub -G user_group

  • For fairshare scheduling only. Associates the job with the specified group. Specify any group that you belong to that does not contain subgroups.


Commands to monitor

Although you cannot monitor egroup behavior directly, you can display information about running jobs for specific host or user groups.


Command

Description

bjobs -m host_group

  • Displays jobs submitted to run on any host that belongs to the specified host group.

bjobs -G user_group

  • Displays jobs submitted using bsub -G for the specified user group.

bjobs -u user_group

  • Displays jobs submitted by users that belong to the specified user group.


Commands to control


Command

Description

badmin reconfig

  • Imports group members on demand from your external host and user group lists.


Commands to display configuration


Command

Description

bmgroup

  • Displays a list of host groups and the names of hosts that belong to each group.

bugroup

  • Displays a list of user groups and the names of users that belong to each group.


Use a text editor to view the lsb.hosts and lsb.users configuration files.