NOTES

   1 ### Structure of queue directories ###
   2
   3 <queue>/hosts/<hostname>/       Jobs queued for the given host
   4                                 (they are executed in the lexicographic order of <job-id>s)
   5         /<job-id>.job           Symlink to <queue>/jobs/<job-id>.job
   6         /<job-id>.stat          (Optional) status of the job
   7         /<job-id>.tmp           Used temporarily by brun to store the script actually
   8                                 sent to the host (can be inspected if something goes wrong)
   9         /<job-id>.log           (Optional) transcript of output produced by the job (including
  10                                 previous failed attempts)
  11
  12 <queue>/jobs/                   All jobs issued on this queue, including those which
  13                                 are no longer queued for any machine
  14         /<job-id>.job           Description of the job (see below)
  15         /<job-id>.attach/       A directory containing attachments (if any)
  16
  17 <queue>/history/<hostname>/     Successfully completed jobs (their .job, .stat and .log files)
  18                                 are moved here if the keep_history config switch is set.
  19
  20 <queue>/log                     Log of actions on this queue. Lines look this way:
  21                                 YYYY-MM-DD HH:MM:SS <host> <job-id> <status> [<msg>]
  22                                 <status> and <msg> correspond to "Status" and "Message"
  23                                 in status files.
  24
  25 <queue>/status-fifo             FIFO used for reporting status of subprocesses by `bprun'
  26
  27 ### Job files ###
  28
  29 Mail-like structure. First come the headers (<keyword>:<spaces><value>), keywords are
  30 case-sensitive, no multi-line fields allowed, then an empty line and then the body
  31 (i.e., commands to be executed on the remote host).
  32
  33 Known header fields:
  34
  35 ID: <job-id>                    Identifier of the job, unique in the scope of a queue
  36 Subject: <subject>              Subject to be displayed to the user
  37 Prep: <command>                 Run <command> in a shell before the job body is executed;
  38                                 $HOST contains the name of the host. This is useful for
  39                                 example if you want to transfer data to the host by rsync.
  40
  41 Whenever a user command wants a job ID, it accepts any substring starting
  42 at a component boundary (start of the ID or a "-"), as long as the substring
  43 is unique.
  44
  45 ### Status files ###
  46
  47 Structure identical to job headers, but they do not contain a body.
  48
  49 Known fields:
  50
  51 Time: <timestamp>               UNIX timestamp of the last status change
  52 Status: <code>                  Machine-readable status of the job (see below)
  53 Message: <msg>                  (Optional) human-readable message explaining the status
  54
  55 ### Status codes ###
  56
  57 FAILED          Job failed to execute (i.e., it returned a non-zero exit code)
  58 INTERR          Internal error of BEX (e.g., failed to read job prolog file)
  59 NEW             Newly inserted job, which did not run yet
  60 NOPING          Host does not respond to ping
  61 NOXFER          Transfer of the job body to a temporary file on the host has failed
  62 OK              Job finished successfully (this is usually not seen in the queue, since
  63                 finished jobs are immediately deleted or moved to the history)
  64 PREP            Running preparatory commands (i.e., those present in Prep header field)
  65 PREPFAIL        Preparatory commands failed (i.e., those present in Prep header field)
  66 REMOVED         Job removed from the queue (behavior similar to OK)
  67 RUN             Job is running
  68
  69 Additional status codes recorded in the log files:
  70
  71 REQUEUE         Attempted to put on a queue, but it already was there
  72
  73 Additional status codes sent only over status FIFO:
  74
  75 DONE            Done with the host (job equals "-")
  76 INIT            Host or job ready, preparing to execute jobs
  77 LOCKED          Host or job not available, because it is locked by another brun
  78 PING            Trying to ping the host (job equals "-")
  79 SEND            Sending job to the host