bsub
Submit jobs to a batch system
TLDR
Submit a script file as a job
Submit a job to a specific queue
Submit a job with a name and redirect output and error
Request 8 CPU cores and 16GB memory for a command
Run an interactive shell in the current session
Submit a job with a runtime limit of 45 minutes
SYNOPSIS
bsub [options] command [arguments]
bsub [options] -J job_name -o output_file -e error_file command
bsub [options] -Is command [arguments]
PARAMETERS
-q
Specifies the queue for job submission.
-P
Assigns the job to a specific project.
-J
Sets a unique name for the job.
-o
Redirects standard output to the specified file.
-e
Redirects standard error to the specified file.
-W
Sets the wall clock time limit for the job in minutes.
-n
Requests a specific number of processors.
-R "
Defines job resource requirements (e.g., select[os_linux] span[hosts=1] rusage[mem=100]).
-i
Redirects standard input from the specified file.
-C
Enables job checkpointing to the specified directory.
-K
Keeps the job running after submission, typically for interactive use.
-Is
Submits an interactive job with a pseudo-terminal (shell access).
-Ip
Submits an interactive job with pre-execution commands.
-L
Specifies the login shell for the job execution environment.
-cwd
Executes the job in the current working directory.
-host
Requests execution on a specific host.
-m
Requests execution on hosts from a specified host group.
-u
Sends job status notifications to the specified email.
-b
Defines a job run window (e.g., 09:00:22:00).
-c
Sets the CPU time limit for the job in minutes.
-M
Sets the memory limit for the job in MB.
-N
Enables email notification upon job completion or termination.
-r
Allows the job to be rerun automatically if it terminates abnormally.
-s
Submits a job from a script file.
-f
Specifies file staging for job input/output.
DESCRIPTION
bsub is a fundamental command within the IBM Spectrum LSF (Load Sharing Facility) workload management system. It is used to submit computation jobs, scripts, or commands to the LSF cluster for execution. Unlike directly running commands on a local machine, bsub offloads the execution to a managed cluster, allowing LSF to efficiently allocate resources, schedule jobs, and manage their lifecycle from submission to completion.
Users employ bsub to specify various job attributes such as the execution queue, resource requirements (e.g., number of CPUs, memory, specific hosts), job name, output/error file redirection, and time limits. LSF then places the job into a queue, and once resources become available according to defined policies, the job is dispatched to an appropriate execution host. This provides benefits like improved resource utilization, fault tolerance (jobs can be re-run or rescheduled), and centralized monitoring, making bsub indispensable for high-performance computing (HPC), grid computing, and large-scale enterprise batch processing environments.
CAVEATS
The bsub command is part of the IBM Spectrum LSF suite and is not a standard component of core Linux distributions. Its availability and specific functionality depend entirely on a configured LSF environment. Options and behavior may vary slightly across different LSF versions. Jobs submitted via bsub are subject to cluster policies, resource availability, and potential licensing constraints. Proper environment setup (e.g., LSF client libraries, PATH configuration) is required for bsub to function correctly.
JOB STATES AND LIFECYCLE
LSF jobs submitted via bsub transition through various states:
PEND (Pending): Waiting for resources.
RUN (Running): Currently executing.
PSUSP (Preempted Suspend): Suspended by LSF for higher priority jobs.
USUSP (User Suspend): Suspended by user.
DONE (Done): Completed successfully.
EXIT (Exited): Terminated with non-zero exit code or by LSF.
Monitoring these states with commands like bjobs is crucial for job management.
INTERACTIVE VS. BATCH JOBS
bsub supports both traditional batch processing and interactive job submission. Batch jobs run in the background, typically redirecting output to files. Interactive jobs, often submitted with options like -Is or -Ip, allow users to interact with the running application directly, similar to a regular shell session, once the job starts on a compute node. This is useful for debugging, developing, or running applications that require user input.
HISTORY
LSF (Load Sharing Facility) was originally developed by Platform Computing Corporation in the early 1990s. It quickly became a leading workload management system for distributed computing and High-Performance Computing (HPC) environments. IBM acquired Platform Computing in 2012, integrating LSF into its Spectrum Computing portfolio as IBM Spectrum LSF. The bsub command has been a central component since LSF's inception, evolving alongside the product to support increasingly complex workloads, diverse resource types, and large-scale clusters.
SEE ALSO
bjobs(1), bkill(1), bhist(1), bqueues(1), bhosts(1), bpeek(1)