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 NEW             Newly inserted job, which did not run yet
  52 NOPING          Host does not respond to ping
  53 NOXFER          Transfer of the job body to a temporary file on the host has failed
  54 OK              Job finished successfully (this is usually not seen in the queue, since
  55                 finished jobs are immediately deleted or moved to the history)
  56 FAILED          Job failed to execute (i.e., it returned a non-zero exit code)
  57 INTERR          Internal error of BEX (e.g., failed to read job prolog file)
  58 PREPFAIL        Preparatory commands failed (i.e., those present in Prep header field)
  59 REMOVED         Job removed from the queue (behavior similar to OK)
  60
  61 These are present only in log files and messages sent over status FIFO:
  62
  63 RUN             Job is running
  64 SEND            Sending job to the host
  65 PREP            Running preparatory commands (i.e., those present in Prep header field)
  66
  67 Status codes not tied to a specific job (sent over status FIFO):
  68
  69 PING            Trying to ping the host
  70 LOCKED          Host or job not available, because it is locked by another brun
  71 INIT            Host ready, preparing to execute jobs
  72 DONE            Done with the host