Basic Batch Connect Options

batch_connect:
  template: "basic"
  work_dir: nil
  conn_file: "connection.yml"
  conn_params:
    - host
    - port
    - password
  bash_helpers: "..."
  min_port: 2000
  max_port: 65535
  password_size: 8
  header: ""
  footer: ""
  script_wrapper: "%s"
  set_host: "host=$(hostname)"
  before_script: "..."
  before_file: "before.sh"
  run_script: "..."
  script_file: "./script.sh"
  timeout: ""
  clean_script: "..."
  clean_file: "clean.sh"

min_port (Integer, 2000)

the smallest value to use when trying to open a port

Default

2000 is the lowest value to use when trying to open a port

min_port: 2000

Example

set the lowest possible port number to 3005

min_port: 3005

max_port (Integer, 65535)

the largest value to use when trying to open a port

Default

65535 is the highest possible value a port could have

max_port: 65535

Example

set the highest possible port number to 40000

max_port: 40000

password_size (Integer, 8)

the number of characters in the passwords

Default

passwords will be generated with 8 characters

password_size: 8

Example

passwords will be generated with 32 characters

password_size: 32

header (String, "")

the script header

Default

the script has no header

header: ""

Example

set the header to a bash shebang

header: "#!/bin/bash"

footer (String, "")

commands at the bottom of the script

Default

the script has no footer

header: ""

Example

print the end time of the job

header: 'echo "all done at $(date)"'

script_wrapper (String, "%s")

Wrap the script (%s being the script content) with commands before and after.

Default

The script has no wrapper.

script_wrapper: "%s"

Example

Load a module before the script and echo a statement after it.

script_wrapper: |
  module load vnc
  %s
  echo "all done now!"

set_host (String, "host=$(hostname)")

set the host variable with this command

Default

the host variable is set by the hostname command

set_host: "host=$(hostname)"

Example

the host variable the first item in the hostname -A output

set_host: "host=$(hostname -A | awk '{print $1}')"

before_script (String, "...")

commands to execute the before file

Default

sources the configurable before_file if it exists

def before_script
  context.fetch(:before_script) do
    before_file = context.fetch(:before_file, "before.sh").to_s

    "[[ -e \"#{before_file}\" ]] && source \"#{before_file}\""
  end.to_s
end

Example

temporarily override the PATH variable when executing the before script

before_script: |
  # careful now, we can't override before_file or we have to
  # change it here too!
  PATH=$PATH:/opt/ood-before/bin source before.sh

before_file (String, "before.sh")

the script file to run before the main script

Default

execute the file before.sh before the main script

before_file: "before.sh"

Example

execute the file prepare.sh before the main script

before_file: "prepare.sh"

run_script (String, "...")

commands to execute the main file

Default

execute the configurable script_file or optionally run with the timeout command if there is a timeout given.

def run_script
  context.fetch(:run_script) do
    script_file = context.fetch(:script_file,  "./script.sh").to_s
    timeout     = context.fetch(:timeout, "").to_s

    timeout.empty? ? "\"#{script_file}\"" : "timeout #{timeout} \"#{script_file}\""
  end.to_s
end

Example

execute the main script in a singularity container

run_script: |
  # careful now, we can't override run_file or we have to
  # change it here too!  This also doesn't account for timeout,
  # if it's provided.
  IMAGE=/opt/images/el9.sif
  singularity exec -p $IMAGE /bin/bash script.sh

script_file (String, "./script.sh")

the main script file

Default

execute the file script.sh in the current working directory

script_file: "./script.sh"

Example

execute the file other_main.sh in the current working directory

script_file: "./other_main.sh"

timeout (String, "")

timeout (in seconds) of the main script

Default

no timeout applied to the main script file

script_file: ""

Example

all scripts timeout after 3600 seconds (1 hour)

script_file: "3600"

clean_script (String, "...")

commands to execute the clean script file

Default

sources the configurable clean_file if it exists

def clean_script
  context.fetch(:clean_script) do
    clean_file = context.fetch(:clean_file, "clean.sh").to_s

    "[[ -e \"#{clean_file}\" ]] && source \"#{clean_file}\""
  end.to_s
end

Example

temporarily override the PATH variable when executing the clean script

clean_script: |
  # careful now, we can't override clean_file or we have to
  # change it here too!
  PATH=$PATH:/opt/ood-clean/bin source clean.sh

clean_file (String, "clean.sh")

the cleanup script file

Default

execute the file clean.sh

clean_file: "clean.sh"

Example

execute the file scrub.sh

clean_file: "scrub.sh"

conn_params (Array<String>, ['host','port','password'])

The connection parameters that will be written to the conn_file. This is useful when you need to generate something in one of the shell scripts and pass it back to the view.html.erb through the connection.yml file.

Note

Anything added here will be added to the default. The default configuration is required and so cannot be overridden, only added to.

Default

‘host’, ‘port’ and ‘password’

conn_params: [ 'host', 'port', 'password' ]

Example

The API to connect to can change in the script.sh.erb based off of something that can only be determined during the job (for example an environment variable in a module).

conn_params:
  - the_connect_api

Warning

These items below should not be set by users. They are given for completeness only. It’s likely they’ll cause errors if overridden.

work_dir (String, null)

the working directory of the job. This is set by the dashboard for batch connect apps and users shouldn’t need to set it.

Default

set by the dashboard to a directory under ~/ondemand/data

Example

no example given because users shouldn’t set this value

conn_file (String, "connection.yml")

the file all the connection data will be written to

Default

a file named ‘connection.yml’

conn_file: "connection.yml"

Example

no example given because users shouldn’t set this value

bash_helpers (String, "...")

a library of bash utility functions called in all the other scripts

Default

a very large set of functions. See source code for complete library

Example

no example given because users shouldn’t set this value