esub

When users submit jobs, you can use an esub script to control submissions. The esub script can validate job parameters and choose to accept, modify, or reject the job. The esub script runs on the submission host.

warning

esub currently checks in the following order and uses the first file found:

• Fixed location: /etc/wrappers/esub
• esub under the LSF_SERVERDIR directory

How It Works

When users submit with bsub, it checks for an esub script at the fixed locations. If present, bsub executes the script and passes environment variables to it. The esub script uses these variables to decide whether to accept, modify, or reject the job. Based on the esub exit code, bsub decides what to do.

• If esub returns 0, the job is accepted and parameter updates are applied.
• If esub returns LSF_SUB_ABORT_VALUE, the job is rejected.
• If esub returns any other value, the job is submitted with the original parameters.

Deployment

1. Install lsf-wrapper and load environment variables.
2. Place the esub script at $LSF_SERVERDIR/esub or /etc/wrappers/esub.
3. Subsequent bsub submissions will be controlled by the esub script.

Environment Variables Used by esub

• LSF_INVOKE_CMD: The command name that invokes esub; currently only bsub is supported.
• LSB_SUB_ABORT_VALUE: To reject the job, esub should exit $LSB_SUB_ABORT_VALUE.
• LSB_SUB_PARM_FILE: bsub parameters are stored in this file. esub reads it during submission and can accept/modify/reject the job based on parameters listed in the next section.
• LSB_SUB_MODIFY_FILE: If you want to modify job parameters, write new option values to this file. Supported parameters are listed in the next section.
• LSB_SUB_MODIFY_ENVFILE: If you want to modify user environment variables, write the new variables to this file.

Parameters Supported by esub

Currently supported parameters:

Option	esub Variable	Purpose
-e, -eo	LSB_SUB_ERR_FILE	Standard error file path
-o, -oo	LSB_SUB_OUT_FILE	Standard output file path
-i	LSB_SUB_IN_FILE	Standard input file path
-W	LSB_SUB_RLIMIT_RUN	Run time limit
-n	LSB_SUB_NUM_PROCESSORS	Task count
-R	LSB_SUB_RES_REQ	Resource request (-R)
-b	LSB_SUB_BEGIN_TIME	Job start time
-t	LSB_SUB_TERM_TIME	Job forced termination time
-x	LSB_SUB_EXCLUSIVE	Exclusive nodes
-w	LSB_SUB_DEPEND_COND	Dependency condition
-E	LSB_SUB_PRE_EXEC	Prelog script path
-Ep	LSB_SUB_POST_EXEC	Postlog script path
-J	LSB_SUB_JOB_NAME	Job name
-P	LSB_SUB_PROJECT_NAME	Project name
-G	LSB_SUB_USER_GROUP	Fairshare user group name
-q	LSB_SUB_QUEUE	Queue/partition name
-Is	LSB_SUB_PTY_SHELL	Request PTY shell
-Ip	LSB_SUB_PTY	Request PTY
-L	LSB_SUB_LOGIN_SHELL	Use login shell
-Jd	LSB_SUB_JOB_DESCRIPTION	Job description

esub Script Examples

Require Project (-P), Reject if Missing

#!/bin/bash

source ${LSB_SUB_PARM_FILE}

# abort the job if mandatory parameter is missing
if [ -z "${LSB_SUB_PROJECT_NAME}" ]; then
    echo "Error: Mandatory parameter '-P <project_name>' is missing."
    echo "Please specify a project name using '-P' option when submitting jobs."
    exit ${LSB_SUB_ABORT_VALUE}
fi

# continue the job
exit 0

Require Fairshare Group (-G), Reject if Missing

#!/bin/bash

source ${LSB_SUB_PARM_FILE}

# abort the job if mandatory parameter is missing

if [ -z "${LSB_SUB_USER_GROUP}" ]; then
    echo "Error: Mandatory parameter '-G <account_name>' is missing."
    echo "Please specify an account name using '-G' option when submitting jobs."
    exit ${LSB_SUB_ABORT_VALUE}
fi

# continue the job
exit 0