How to Use Jobber
Version 1.41.31.21.1

Specifying Commands

Jobs’ commands are specified with YAML strings containing sh scripts. YAML’s syntax makes it easy to write multi-line scripts:

jobs:
  MyJob:
    cmd: |
      /home/bob/do-something.sh
      if [ $? -ne 0 ]; then
        /home/bob/handle-error.sh
      fi
    ...

These commands will be executed as the user that owns the jobfile, in a login session.

Time Strings

Field time specifies the schedule at which a job is run, in a manner similar to how cron jobs’ schedules are specified: with a space-separated list of up to six specifiers, each one of which constrains a different component of time (second, minute, hour, etc.). Schematically:

sec min hour month_day month week_day

A job is scheduled thus: the next run time is the time that satisfies the second, minute, hour, and month specifiers and at least one of the month-day and weekday specifiers.

Important: If a specifier is one of the random specifiers (beginning with R ), a random value is chosen when the jobfile is loaded, and stays the same until the jobfile is loaded again.

Each specifier can take one of the following forms: (“a”, “b”, “c”, and “n” are placeholders for arbitrary numerals.)

The specifiers have different permitted values for the placeholders in the specifier forms:

The default value for time is * * * * * * .

Error-handling

When you run jobber list to list the jobs for a user, you get an output like this:

NAME         STATUS  SEC/MIN/HR/MDAY/MTH/WDAY  NEXT RUN TIME              NOTIFY ON SUCCESS  NOTIFY ON ERR  NOTIFY ON FAIL  ERR HANDLER
DailyBackup  Good    0 0 13 * * *              Nov 22 13:00:00 +0000 UTC                                    system-email    Stop

In this example, the job’s status is Good, which means that runs of the job will be scheduled normally. A status of Failed means that runs will no longer be scheduled. A status of Backoff means that runs will be scheduled in the following several seconds according to an exponential backoff algorithm.

A job’s status is affected by job errors — that is, runs of the job’s shell script that resulted in non-0 exit codes. This is done according to the job’s error-handler, as specified in the jobfile under the onError key in the job’s definition.

Result Sinks
Doing Stuff with Job Run Output

A run of a job results in one of three events:

For a partiular job, you can assign result sinks that can do various things with the job’s output in response to these events, using the notifyOnSuccess, notifyOnError, and notifyOnFailure fields in the job’s definition:

jobs:
  GetAirQuality:
    cmd: /home/bob/get-air-quality.sh
    time: 0 0 8
    onError: Backoff
    notifyOnSuccess:
      - type: program
        path: /home/bob/text-air-quality.sh
    notifyOnFailure:
      - type: system-email
      - type: filesystem
        path: /home/bob/jobber-failures
        data:
          - stdout
          - stderr
        maxAgeDays: 10

In this example, result sinks are used only for successes and failures. The notifyOnSuccess, notifyOnError, and notifyOnFailure fields take lists of result sink definitions, and each result sink definition has a required type field as well as other fields depending on the type.

It is common to want to use the same result sink in different jobs (or even for different events from the same job). This is best done by moving the sink’s definition to the resultSinks section of the jobfile and then using YAML anchors in the job definitions to reference the sink’s definition:

jobs:
  GetAirQuality:
    cmd: /home/bob/get-air-quality.sh
    time: 0 0 8
    onError: Backoff
    notifyOnSuccess:
      - type: program
        path: /home/bob/text-air-quality.sh
    notifyOnFailure:
      - type: system-email
      - *filesytemFailureSink

  DailyBackup:
    cmd: /usr/local/bin/backup /home/bob/documents
    time: 0 0 13
    onError: Stop
    notifyOnFailure:
      - *filesytemFailureSink

resultSinks:
  - &filesytemFailureSink
    type: filesystem
    path: /home/bob/jobber-failures
    data:
      - stdout
      - stderr
    maxAgeDays: 10

Here are the types of result sinks:

- /some/dir/
  - JobOne/
    - 1521318351.stdout
    - 1521318351.stderr
    - 1521318411.stdout
    - 1521318411.stderr
    - 1521318471.stdout
    - 1521318471.stderr

Several types of result sinks publish details about a job’s run in the form of a run record, which is a JSON document. Here is an example:

{
  "version": "1.4",
  "job": {
    "name": "DailyBackup",
    "command": "/usr/local/bin/backup /home/bob/documents",
    "time": "0 0 13 * * *",
    "status": "Good"
  },
  "user": "bob",
  "startTime": 1543150800,
  "succeeded": true,
  "stdout": "Backing up...\nSuccess",
  "stderr": ""
}

If the run’s stdout (or stderr) output contained non-UTF-8 bytes, then the run record will have a stdoutBase64 (or stderrBase64) field instead of a stdout (or stderr) field, containing the output encoded in Base64.

Keeping a Log of Job Runs

The jobber log command prints the run log — i.e., a log containing info about previous runs. By default, the run log only contains the 100 most recent runs, and it is not written to disk, which means that it will be lost when the Jobber service stops or restarts.

Here is an example of keeping the run log in memory:

prefs:
  runLog:
    type: memory
    maxLen: 500

With this, Jobber will keep log entries for no more than the 500 most recent runs of any of the user’s jobs.

Here is an example of keeping the run log on disk:

prefs:
  runLog:
    type: file
    path: /var/log/jobber-runs
    maxFileLen: 100m
    maxHistories: 2

With this, Jobber will write run log entries to /var/log/jobber-runs. /var/log/jobber-runs will grow to no more than 100 MB, and Jobber will rotate it when it gets too big. Jobber will keep up to two of these rotated “history” files (named “jobber-runs.1” and “jobber-runs.2”). When it is necessary to delete a history file, the oldest one will get the axe.