Configuration¶

The adapter's settings are one JSON object, passed to the adapter as dispatch.Config.Adapter (it arrives as AdapterConfig.Settings), or as a slurm.Config to slurm.New. Every key is optional except where noted; an omitted key takes its default. An empty section, or none, is the all-defaults configuration.

The schema is slurm.Schema(), a JSON Schema (draft 2020-12) with additionalProperties: false at every level. Why the decoders are strict lists what the decoder refuses beyond it: unknown and repeated keys, null, empty strings, numbers below 1, and text that is not a positive Go duration.

The schema is laxer than the adapter in places. It accepts, and the adapter later refuses:

• ssh.host, ssh.user and ssh.proxyJump with characters outside the sets below, or starting with -, and ssh paths with characters other than letters, digits and - _ . / +. The adapter refuses these when slurm.New opens the ssh transport;
• a controlPath over 90 bytes once expanded, or with characters other than letters, digits and - _ . / + %, which the adapter refuses when it decodes the configuration;
• an output.dir holding % or \, refused when a job is started or the probe submitted.

It is stricter in one: it lists only the local and ssh transports.

Durations are strings in Go's format, such as 10s, 2m or 1h30m, and must be positive. In Go they are slurm.Duration, a time.Duration.

{
  "transport": "ssh",
  "ssh": { "host": "login.example.org", "user": "ada" },
  "defaults": { "partition": "gpu", "account": "research" },
  "output": { "dir": "$HOME/runs" },
  "environment": { "pass": ["PATH", "HF_HOME"] },
  "cessation": { "command": "/opt/site/nodes-clean", "timeout": "90s" },
  "preflight": { "cacheDir": "/home/ada/.cache/dispatch-slurm", "maxAge": "12h" },
  "timeouts": { "command": "3m" }
}

Top level¶

The Go decoder also accepts a transport name added with slurm.RegisterTransport. The schema lists only local and ssh.

ssh¶

Required when transport is ssh; refused otherwise. The set is closed: there is no way to pass an arbitrary ssh option. Values are checked for characters ssh would misread. Paths are absolute and may contain only letters, digits and - _ . / +.

The adapter always adds -T, -o BatchMode=yes and -o StrictHostKeyChecking=yes. The default controlPath directory is created with mode 0700; a configured one is not created.

defaults¶

sbatch placement defaults. A job's slurm.Placement extension overrides each field that it sets. Every value is a non-empty string without control characters.

output¶

The % and \ rule is checked when a job is started, not when the configuration is read, because sbatch rewrites both in --output. A writable slurm.New that runs the preflight probe, because it has no fresh cached result, checks it too, since the probe is a submission. See How a job becomes an sbatch submission.

environment¶

The values are read on the Slurm host, in the environment the transport's shell sees, each time a job is started, and written into the batch script as literals. A variable that is not set there is not exported. An empty array passes nothing, which is not the same as omitting the key. Jobs are submitted with --export=NIL, so the batch environment has no HOME; add it here if a job needs it.

Do not pass a secret this way. The values are written into the batch script as literal export lines, and slurmctld stores the script: an administrator can read it, and accounting keeps it where the cluster records job scripts. The same holds for JobSpec.Env.

A Go slurm.Config says the same with an empty, non-nil Pass slice, which survives dispatch.Open; a nil slice means the default.

singleton¶

When true, every job is submitted with --dependency=singleton, so a later submission of the same dispatch job (they share one Slurm job name) waits for the earlier one to end. The adapter checks the dependency on read-back, and refuses a job whose dependency is not what it asked for.

cessation¶

The command a site supplies to say whether a job's processes have stopped. Without it, Ceased returns dispatch.ErrUnsupported.

The command's exit status is the answer: 0 means ceased, 1 means not yet. Any other status, or a kill at timeout, is an error and never evidence. The last 4 KiB of its combined output is kept as the evidence's detail. It works on a read-only backend.

preflight¶

See Read a preflight result.

timeouts¶

Rules between keys¶

• ssh with a transport other than ssh, or transport: ssh without ssh, is refused.
• A transport name must be local, ssh or one registered with slurm.RegisterTransport.
• No value may hold a control character (below 0x20, or 0x7f).
• Every failure names the key it is about.