How to Use Jobber
Version 1.41.31.21.1

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 a job (or, specifically, the shell code that the job runs) exited with a non-0 status, we call this a “job error”.

One of Jobber’s main features is that you can control how Jobber handles job errors. You do this by setting the onError field in a job’s definition to one of these values:

When Jobber stops scheduling runs of a job due to one or more job errors, we call this a “job failure”.

If you would like Jobber to notify you when a job error or job failure occurs, do the following:

1. Write a notify program that does whatever you want done after a job error or job failure
2. Set the notifyProgram field in the prefs section of the Jobber file to the path to your notify program

The input that Jobber will send to the notify program is described elsewhere.

Job Status Notifications

You can arrange for Jobber to send notifications when certain events happen for a particular job:

By default, these notifications consist of emails to the user account that owns the job. Jobber uses sendmail to do this.

Also, by default, Jobber will send notifications when any job fails. To disable this for a particular job, set notifyOnFailure in that job’s definition to false .

To enable notifications when a particular job succeeds, set notifyOnSuccess to true in that job’s definition.

To enable notifications when a particular job errs, set notifyOnError to true in that job’s definition.

For example, in the following, for DailyBackup Jobber will send notifications only on job error, while for OffsiteBackup it will send notifications only on job failure:

[prefs]
...

[jobs]
- name: DailyBackup
  notifyOnError: true
  notifyOnFailure: false
  ...

- name: OffsiteBackup
  onError: Stop
  ...

Notify Programs

Rather than having Jobber notify by sending emails, you can have it call an arbitrary program, called a “notify program”.

To do so, in the prefs section of your jobfile define notifyProgram to be a path to your notify program, thus:

[prefs]
notifyProgram: /home/dylan/myNotifyProgram.sh

(Make sure the notify program is executable.)

When Jobber calls your notify program, it will write to stdin a JSON document like this:

{  
   "job":{  
      "command":"/home/dylan/some_program",
      "name":"MyHourlyJob",
      "notifyOnError":true,
      "notifyOnFailure":false,
      "onError":"Stop",
      "status":"Failed",
      "time":"0 0 * * * *"
   },
   "startTime":"May 29 15:25:10 2017",
   "stderr":"Some errors\n",
   "stderr_base64":false,
   "stdout":"Quotes: \"adf\"\n",
   "stdout_base64":false,
   "succeeded":false,
   "user":"dylan"
}

The fields in the job object are from the job’s definition, except for status, which indicates whether and how Jobber will schedule runs of the job in the future. Its possible values are Good , Backoff , or Failed .

stdout (respectively, stderr ) contains whatever the job wrote to stdout (stderr). If stdout_base64 (stderr_base64) contains false , then the job wrote only UTF-8 bytes to stdout (stderr), and stdout ( stderr ) contains a string with those bytes; otherwise, there were some non-UTF-8 bytes and stdout ( stderr ) contains a Base64 encoding of the output.

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.