How to Use Jobber
Version 1.41.31.21.1

Deployment

Jobber is written in Go, and it should be possible to compile and run it on any Linux system. We currently provide binary packages for RHEL-like systems, Ubuntu/Debian and Alpine Linux.

Note that, although Jobber can be used instead of cron, it is certainly possible to run both at the same time.

Compilation and Installation from Source

You need a recent version of Go to compile Jobber. So, install Go, pick a place for your workspace (say, /path/to/your/workspace), and ensure that the environment variable “GOPATH” includes a path to your workspace. Then:

cd /path/to/your/workspace
go get github.com/dshearer/jobber
cd src/github.com/dshearer/jobber
git checkout v1.1
make GO_WKSPC=/path/to/your/workspace

Jobber consists of two binaries: jobber and jobberd. jobberd is a daemon that runs jobs; jobber is a client with which the user can interact with jobbberd. After compiling, you’ll find them in /path/to/your/workspace/bin.

Now:

1. Make a new, non-login user called “jobber_client”.
2. Change jobber’s permissions to 04755, and its owner to jobber_client:root.
3. Change jobberd’s permissions to 0755, and its owner to root:root.
4. Move jobber and jobberd someplace more appropriate (e.g., /usr/local/bin and /usr/local/libexec respectively).
5. Ensure that jobberd will get started when your computer boots. Note that jobberd does not daemonize itself — you will need to run it with something like daemonize(1).

Defining Jobs

As with cron, each user can have its own set of jobs, which will be run under that user’s privileges. A user’s jobs are defined in a jobfile — a file named “.jobber” in the user’s home directory. Jobfiles are written in YAML format. Here's an example that defines two jobs:

---
- name: DailyBackup
  cmd: backup daily
  time: 0 0 13
  onError: Stop
  notifyOnError: true
  notifyOnFailure: false

- name: OffsiteBackup
  cmd: |
    mount /backup/offsite
    mount /backup/linux/weekly
    backup-offsite /backup/linux/weekly/backup-0 linux || exit 1
    umount /backup/linux/weekly
    umount /backup/offsite
  time: 0 0 14 * * 1
  onError: Stop

The fields of a job definition:

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 specifier describes a constraint on a “time component” — e.g., second, minute — that must hold in order for the job to run at a particular time. In order from left to right, these are the time components corresponding to the specifiers:

1. second
2. minute
3. hour
4. day of month
5. month
6. day of week

* as a specifier is a wildcard — it is satisfied by every value of the corresponding time component. If any specifiers are missing, they are assumed to be * .

Specific values are specified with numbers: 0–59 for second and minute, 0–23 for hour, 1–31 for day of month, 1–12 for month, and 0–6 for day of week (with 0 specifying Sunday).

A specifier of the form */n is satisfied by every nth value — e.g., */3 as the second specifier is satisfied by minute 0, minute 3, minute 6, etc.

A job will run at the earliest future time that satisfies the first, second, third, and fifth specifiers and at least one of the fourth and sixth specifiers.

Thus, “DailyBackup” is run whenever the current time is 13:00:00 (i.e., 1 PM), no matter the day, whereas “OffsiteBackup” is run whenever the current time is 14:00:00 (i.e., 2 PM) and the current weekday is Monday.

Error-handling

When discussing jobs, by “job error” we mean the failure of a particular run of a job, whereas by “job failure” we mean a job that jobber has decided not to schedule anymore due to one or more recent job errors. Jobber considers a run to have failed when the command (in field cmd ) returns a non-0 exit status.

Field onError ; specifies what jobber will do when a job error occurs. The possible values:

• Stop: Stop scheduling runs of this job. That is, a single job error results in a job failure.
• Backoff: Schedule runs of this job according to an exponential backoff algorithm. If a later run of the job succeeds, jobber resumes scheduling this job normally; but if the job fails again on several consecutive runs, jobber stops scheduling it — that is, the job fails.
• Continue: Continue scheduling this job normally. That is, the job will never fail.

Loading Jobs

After you've created a user’s jobfile, log in as that user and do:

jobber reload

You can also reload all users’ jobfiles by logging in as root and doing:

jobber reload -a

Listing Jobs

You can list the jobs for a particular user by logging in as that user and doing

jobber list

This command also shows you the status of each job — that is, whether the job is being scheduled as normal, the exponential backoff algorithm is being applied, or the job has failed.

As with the reload command, you can do the same for all users by adding the -a option as root.

Listing Runs

You can see a list of recent runs of any jobs for a particular user by logging in as that user and doing

jobber log

As with the other commands, you can do the same for all users by adding the -a option as root.

Testing Jobs

If you'd like to test out a job, do

jobber test JOB_NAME

Jobber will immediately run that job, tell you whether it succeeded, and show you its output.