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 Prep: <command>                 Run <command> in a shell before the job body is executed;
  36                                 $HOST contains the name of the host. This is useful for
  37                                 example if you want to transfer data to the host by rsync.
  38
  39 ### Status files ###
  40
  41 Structure identical to job headers, but they do not contain a body.
  42
  43 Known fields:
  44
  45 Time: <timestamp>               UNIX timestamp of the last status change
  46 Status: <code>                  Machine-readable status of the job (see below)
  47 Message: <msg>                  (Optional) human-readable message explaining the status
  48
  49 ### Status codes ###
  50
  51 FAILED          Job failed to execute (i.e., it returned a non-zero exit code)
  52 INTERR          Internal error of BEX (e.g., failed to read job prolog file)
  53 NEW             Newly inserted job, which did not run yet
  54 NOPING          Host does not respond to ping
  55 NOXFER          Transfer of the job body to a temporary file on the host has failed
  56 OK              Job finished successfully (this is usually not seen in the queue, since
  57                 finished jobs are immediately deleted or moved to the history)
  58 PREP            Running preparatory commands (i.e., those present in Prep header field)
  59 PREPFAIL        Preparatory commands failed (i.e., those present in Prep header field)
  60 REMOVED         Job removed from the queue (behavior similar to OK)
  61 RUN             Job is running
  62
  63 Additional status codes recorded in the log files:
  64
  65 REQUEUE         Attempted to put on a queue, but it already was there
  66
  67 Additional status codes sent only over status FIFO:
  68
  69 DONE            Done with the host (job equals "-")
  70 INIT            Host or job ready, preparing to execute jobs
  71 LOCKED          Host or job not available, because it is locked by another brun
  72 PING            Trying to ping the host (job equals "-")
  73 SEND            Sending job to the host