# Slurm Burst Buffer Guide

- Overview
- Configuration (for system administrators)
- Job Submission Commands
- Persistent Burst Buffer Creation and Deletion Directives
- Interactive Job Options
- Status Commands
- Advanced Reservations

## Overview

Slurm version 15.08 includes support for burst buffers, a shared high-speed storage resource. Slurm provides support for allocating these resources, staging files in, scheduling compute nodes for jobs using these resources, then staging files out. Burst buffers can also be used as temporary storage during a job's lifetime, without file staging. Another typical use case is for persist storage, not associated with any specific job. This support is provided using a plugin mechanism so that a various burst buffer infrastructures may be easily configured. Two plugins are provided initially:

1. cray - Uses Cray APIs to perform underlying management functions
2. generic - Uses system administrator defined scripts to perform underlying management functions, currently under development

Additional plugins may be provided in future releases of Slurm.

Slurm's mode of operation follows this general pattern:

0. Read configuration information and initial state information
1. After expected start times for pending jobs are established, allocate burst buffers to those jobs expected to start earliest and start stage-in of required files
2. After stage-in has completed, jobs can be allocated compute nodes and begin execution
3. After job has completed execution, begin file stage-out from burst buffer
4. After file stage-out has completed, burst buffer can be released and the job record purged

## Configuration (for system administrators)

Burst buffer support in Slurm is enabled by specifying the plugin(s) to loaded for managing these resources using the BurstBufferType configuration parameter in the slurm.conf file. Multiple plugin names may be specified in a comma separated list. Detailed logging of burst buffer specific actions may be generated for debugging purposes by using the DebugFlags=BurstBuffer configuration parameter. This DebugFlag can result in very verbose logging and is only intended for diagnostic purposes rather than for use in a production system.

    # Excerpt of slurm.conf file
    BurstBufferType=burst_buffer/generic
    DebugFlags=BurstBuffer

Burst buffer specific options should be defined in a burst_buffer.conf file. If multiple burst buffer plugins are configured, an independent configuration file can be specified for each one with a file name including the plugin name. For example files named "burst_buffer_cray.conf" and "burst_buffer_generic.conf" can be used indepdently by the cray and generic burst buffer plugins respectively. This file can contain information about who can or can not use burst buffers, resource limits, priority boost specifications for jobs using burst buffers, timeouts, and paths to script used to perform various functions. Note that the UserSizeLimit is global (applies to every user), but can be overridden by using TRES limits in the Slurm database for finer grained controls. The PriorityBoost options can also be replaced by a including burst buffer factor in the multifactor priority algorithm.

Note that sample scripts for performing these burst buffer operations for the burst_buffer/generic plugin are included with the Slurm distribution. These scripts were intended for Slurm development and testing purposes and are not currently intended for customer use. Contributions of usable scripts/programs are invited. For more information about the functionality that might be included in the scripts, please see The Ramdisk Storage Accelerator by Timothy B. Wickberg. Note that these scripts/programs are executed as SlurmUser rather than user root. Please see the burst_buffer.conf man page for more information.

    # Excerpt of burst_buffer.conf file for generic plugin
    AllowUsers=alan:brenda
    Flags=EnablePersistent,PrivateData
    Granularity=1GB
    StageInTimeout=30
    StageOutTimeout=30
    #
    GetSysState=/usr/local/slurm/15.08/sbin/GSS
    StartStageIn=/usr/local/slurm/15.08/sbin/SSI
    StartStageOut=/usr/local/slurm/15.08/sbin/SSO
    StopStageIn=/usr/local/slurm/15.08/sbin/PSI
    StopStageOut=/usr/local/slurm/15.08/sbin/PSO

Note for Cray systems: The JSON-C library must be installed in order to build Slurm's burst_buffer/cray plugin, which must parse JSON format data. See Slurm's JSON installation information for details.

## Job Submission Commands

The normal mode of operation is for batch jobs to specify burst buffer requirements within the batch script. Batch script lines containing a prefix of "#BB" identify the job's burst buffer space requirements, files to be staged in, files to be staged out, etc. when using the burst_buffer/generic plugin. The prefix of "#DW" (for "DataWarp") is used for burst buffer directives when using the burst_buffer/cray plugin. Please reference Cray documentation for details about the DataWarp options. For DataWarp systems, the prefix of "#BB" can be used for interactive jobs to create or delete persistent burst buffer storage (NOTE: The "#BB" prefix is used since the command is interpreted by Slurm and not by the Cray Datawarp software). Slurm converts the batch script's burst buffer options into a summary of buffer creation and deletion requests and stores the information in the job's "burst_buffer" field (a string) which is visible using the "scontrol show job" command or the appropriate options in the squeue and sview commands. Interactive jobs (those submitted using the salloc and srun commands) can specify their burst buffer space requirements using the "--bb" command line option, but staging of jobs before and after the resource allocation is not supported.

A basic validation is performed on the job's burst buffer options at job submit time. If the options are invalid, the job will be rejected and an error message will be returned directly to the user. If the job is accepted, but later fails (e.g. some problem staging files), the job will be held and its "Reason" field will be set to an appropriate error message.

Users may also request to be notified by email upon completion of burst buffer stage out using the "--mail-type=stage_out" or "--mail-type=all" option. The subject line of the email will be of this form:

    SLURM Job_id=12 Name=my_app Staged Out, StageOut time 00:05:07

NOTE: Burst buffer support is currently not available for job arrays.

## Persistent Burst Buffer Creation and Deletion Directives

These options are used for both the burst_buffer/cray and burst_buffer/generic plugins to create and delete persistent burst buffers, which have a lifetime independent of the job. These options are only available for batch jobs.

- #BB create_persistent name=<name> capacity=<number> [access=<access>] [type=<type>]
- #BB destroy_persistent name=<name> [hurry]

The persistent burst buffer name may not start with a numeric value (numbers are reserved for job specific burst buffers). The size specification can include a suffix of GB, TB, PB, etc for gigabytes, terabytes, petabytes, etc. Multiple persistent burst buffers may be created or deleted within a single job. A sample batch script follows:

    #!/bin/bash
    #BB create_persistent name=alpha capacity=32GB access=striped
    #DW jobdw type=scratch capacity=1GB access_mode=striped
    #DW stage_in  type=file source=/home/alan/data.in  destination=/ss/data
    #DW stage_out type=file destination=/home/alan/data.out source=/ss/data
    /home/alan/a.out

NOTE: The ability to create and destroy peristent burst buffers may be limited by the "Flags" option in the burst_buffer.conf file. By default only privileged users can create or destroy persistent burst buffers.

## Interactive Job Options

Interactive jobs may include directives for creating job specific burst buffers. Note that for interactive jobs, the burst buffers will be allocated and deleted, but no file staging is supported. These options may be specified using the "--bb" option of the salloc or srun command. Multiple directives should be space separated.

- access=<access>
- capacity=<number>
- swap=<number>
- type=<type>

If a swap option is specified, the job must also specify the required node count. The capacity specification can include a suffix of GB, TB, PB, etc for gigabytes, terabytes, petabytes, etc. A sample command line follows:

    srun --bb="capacity=1GB access=striped" a.out

## Status Commands

Slurm's current burst buffer state information is available using the scontrol show burst command or by using the sview command's Burst Buffer tab.

    $ scontrol show burst
    Name=generic DefaultPool=ssd Granularity=100G TotalSpace=50T UsedSpace=42T
      StageInTimeout=30 StageOutTimeout=30 Flags=EnablePersistent,PrivateData
      AllowUsers=alan:brenda
      CreateBuffer=/usr/local/slurm/15.08/sbin/CB
      DestroyBuffer=/usr/local/slurm/15.08/sbin/DB
      GetSysState=/usr/local/slurm/15.08/sbin/GSS
      StartStageIn=/usr/local/slurm/15.08/sbin/SSI
      StartStageIn=/usr/local/slurm/15.08/sbin/SSO
      StopStageIn=/usr/local/slurm/15.08/sbin/PSI
      StopStageIn=/usr/local/slurm/15.08/sbin/PSO
      Allocated Buffers:
        JobID=18 Account=foo CreateTime=2015-08-19T16:46:05 Partition=debug QOS=high   Size=10T State=allocated UserID=alan(1000)
        JobID=20 Account=foo CreateTime=2015-08-19T16:46:45 Partition=debug QOS=high   Size=10T State=allocated UserID=alan(1000)
        Name=DB1 Account=bar CreateTime=2015-08-19T16:46:45 Partition=debug QOS=normal Size=22T State=allocated UserID=brenda(1001)
      Per User Buffer Use:
        UserID=alan(1000) Used=20T
        UserID=brenda(1001) Used=22T

## Advanced Reservations

Burst buffer resources can be placed in an advanced reservation using the BurstBuffer option. The argument consists of four elements:
[plugin:][type:]#[units]
plugin is the burst buffer plugin name, currently either "cray" or "generic". If no plugin is specified, the reservation applies to all configured burst buffer plugins.
type specifies a Cray generic burst buffer resource, for example "nodes". if "type" is not specified, the number is a measure of storage space.
units may be "N" (nodes), "GB" (gigabytes), "TB" (terabytes), "PB" (petabytes), etc. with the default units being megabytes for reservations of storage space.
Jobs using this reservation are not restricted to these burst buffer resources, but may use these reserved resources plus any which are generally available. Some examples follow.

    $ scontrol create reservation starttime=now duration=60 \
      users=alan flags=any_nodes \
      burstbuffer=cray:100GB,generic:20GB

    $ scontrol create reservation StartTime=noon duration=60 \
      users=brenda NodeCnt=8 \
      BurstBuffer=cray:20GB

Last modified 20 August 2015