2. Design Notes

2.1 Fundamental Operations

The following is a list of all the "core" operations that must be provided based on the requirements.

Execute jobs

Strictly speaking, this is the only role that requires superuser privileges. Every other job should run as non-root.

Schedule jobs

Scan all the known jobs, determine which one needs to be executed next, and sleep until that time arrives.

Accept new user crontabs

Listen for connections on a socket and accept job data.

Parse crontabs into internal job format

Read the submitted files and parse their contents into a structured format.

Check for new system crontabs

Check `/etc/crontab' and `/etc/cron.d/*' every minute for modifications. If any files are changed, added, or deleted, add the listed jobs. On systems with tightened security, these files may only be readable by `root'.

Manage saved state

All jobs need to be saved to disk along with when they were last executed, in order to determine when they should be next executed.

2.2 Programs

`bcron-sched'

Top-level scheduler agent. Starts up as root, runs `bcron-exec', and then drops root permanently.

`bcron-exec'

Accepts jobs to run from `bcron-sched' on stdin, writes exit status back to stdout.

`bcron-spool'

Manages the cron spool: receives jobs submitted from users, writes them to files in `/var/spool/cron/crontabs', and notifies `bcron-sched'. This needs to be run from `unixserver' in order to securely determine the invoking UID. This program will optionally run the file through an external filter, specified on the command line, before installing the job.

`bcron-update'

Watches for changes to the system crontabs and notifies `bcron-sched'.

2.3 Files

2.3.1 Hierarchy

`/etc/cron.d/'

`/etc/cron.d/*'

`/etc/crontab'

The above three items are read

`/var/spool/cron/'

`/var/spool/cron/crontabs/'

Directory containing raw (text) crontab files.

`/var/spool/cron/bcron/'

Directory containing saved state from the crontabs.

`/var/spool/cron/bcron/:etc:cron.d:*'

Colon is chosen as a seperator because usernames cannot contain colons due to the format of `/etc/passwd'.

`/var/spool/cron/bcron/:etc:crontab'

`/var/spool/cron/tmp/'

Temporary directory for files as they are written.

`/var/spool/cron/trigger'

Named pipe used to tell `bcron-sched' to rescan the crontabs.

2.4 Inter-Process Communication

All communication between programs is done in terms of either "packets" or "lines". A packet is formatted as a netstring. That is, a packet of length N is encoded as the ASCII decimal value of N, `:', N bytes of data, terminated by `,'. A line is simply a series of non-NUL bytes terminated by a NUL byte.

2.4.1 Job Submission Protocol

Client sends a packet containing a single byte command followed by the username. If the command requires additional data, it is seperated from the username by a NUL byte. Server responds with a packet containing a response byte followed by a text message.

Client command codes are:

S

Submit a user crontab file. The content string contains the entire crontab file.

L

List the current crontab file. No content string.

R

Remove any previously submitted crontab file. No content string.

Server response codes are:

K

Command was successful; file was parsed and accepted.

D

File could not be parsed.

Z

Temporary internal error.

2.4.2 bcron-exec Protocol

Input packets contain a series of four or more NUL-terminated lines:

ID

username

command

environment

The environment is optional. If the environment contains SHELL, it replaces the default shell (`/bin/sh'). If the environment contains MAILTO, it overrides the default mailing address derived from the username.

Output packet:

ID

NUL

response code

text message