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/<job-id>.job       All jobs issued on this queue, including those which
  13                                 are no longer queued for any machine
  14
  15 <queue>/history/<hostname>/     Successfully completed jobs (their .job, .stat and .log files)
  16                                 are moved here if the keep_history config switch is set.
  17
  18 <queue>/log                     Log of actions on this queue. Lines look this way:
  19                                 YYYY-MM-DD HH:MM:SS <host> <job-id> <status> [<msg>]
  20                                 <status> and <msg> correspond to "Status" and "Message"
  21                                 in status files.
  22
  23 <queue>/status-fifo             FIFO used for reporting status of subprocesses by `bprun'
  24
  25 ### Job files ###
  26
  27 Mail-like structure. First come the headers (<keyword>:<spaces><value>), keywords are
  28 case-sensitive, no multi-line fields allowed, then an empty line and then the body
  29 (i.e., commands to be executed on the remote host).
  30
  31 Known header fields:
  32
  33 ID: <job-id>                    Identifier of the job, unique in the scope of a queue
  34 Subject: <subject>              Subject to be displayed to the user
  35
  36 ### Status files ###
  37
  38 Structure identical to job headers, but they do not contain a body.
  39
  40 Known fields:
  41
  42 Time: <timestamp>               UNIX timestamp of the last status change
  43 Status: <code>                  Machine-readable status of the job (see below)
  44 Message: <msg>                  (Optional) human-readable message explaining the status
  45
  46 ### Status codes ###
  47
  48 NEW             Newly inserted job, which did not run yet
  49 NOPING          Host does not respond to ping
  50 NOXFER          Transfer of the job body to a temporary file on the host has failed
  51 OK              Job finished successfully (this is usually not seen in the queue, since
  52                 finished jobs are immediately deleted or moved to the history)
  53 FAILED          Job failed to execute (i.e., it returned a non-zero exit code)
  54 INTERR          Internal error of BEX (e.g., failed to read job prolog file)
  55
  56 These are present only in log files and messages sent over status FIFO:
  57
  58 RUN             Job is running
  59 SEND            Sending job to the host
  60
  61 Status codes not tied to a specific job (sent over status FIFO):
  62
  63 PING            Trying to ping the host
  64 LOCKED          Host or job not available, because it is locked by another brun
  65 INIT            Host ready, preparing to execute jobs
  66 DONE            Done with the host