RATRUN(8)

SYNOPSIS

/usr/libexec/ratrun [-n[n]] [-d date]

/usr/libexec/ratrun -a

Sends reminders for Events in ~/.ratrun/, to the invoking user, then moves expired events to old. With -n, doesn't, and lists what would be sent to the standard output stream (incl. the bodies if -nn). -d overrides when "now" is: this is most useful in consort with -n to ascertain upcoming events.

With -a, runs ratrun for all configured users: those limited to RATRUN_GROUPS, plus the individually-named RATRUN_USERS, who have a .ratrun directory in their home directory. Users are mailed with a summary of the errors for their run, if any.

No user-specified code is ever run, and no root mail is generated (unless, of course, root schedules a reminder): ratrun is essentially just a way for users to schedule (periodic) mail delivery to themselves.

Events

Have a very simple format:

the first line is the event date in date -d format,
the second line is the per-event reminder override (optional, and taken as part of the body if it doesn't start with a digit),
the remainder of the file is the event body, sent verbatim in the reminder.

An event is said to be expired if it doesn't have any more Reminders left.

iCalendar/VCALENDAR/.ics files can be dropped in verbatim, too, cf. ratrun.ics(7).

Reminders

Start with a digit, are decimal integers, and optionally end with a recursively-expanded multiplicative suffix:

mo	=	4	wk
wk	=	7	d
yr	=	365	d
d	=	24	h
h	=	60	m
m	=	60
s	=	1

in this order, i.e. 10h = 600m = 36000 (= 36000s).

They correspond to the minimal time before the event, in seconds, to send a reminder — i.e. for reminders "3600 60 0" (equiv. "1h 1m 0"), a mail will be sent no sooner than an hour, a minute, and at the time of the event.

Notification format

For each reminder that expires, users will receive mail with a subject of

ratrun: in {latest-expired reminder}

 /
  at

{HH:MM} ({raw event date}): {event filename}

and body of the rest of the event. The reminder time is folded, in reverse, per the suffix table above; the parenthetical is omitted if it's the same as HH:MM (or H:MM), and the reminder – if the only one is 0.

Additionally, users may receive messages with a subject of

Errors for your ratrun at …

from root. These are produced by -a runs, and contain the standard error and output streams from the user's run.

ENVIRONMENT

RATRUN_REMINDERS: System-wide default list of reminders. Overriden per-user with .reminders and per-event with the second line.
RATRUN_GROUPS: If non-empty, in -a mode, only check .ratrun presence for the specified groups. Field-split (white-space-delimited).
RATRUN_USERS: If non-empty, in -a mode, only check .ratrun presence for the specified users, or add them to the result from RATRUN_GROUPS. Field-split.
CONFDIR: Replaces "/etc/default" below.

FILES

/etc/default/ratrun: Sourced at the top.
~/.ratrun/: Contains Events. Directory/hidden/unreadable/empty files are ignored.
~/.ratrun/old/: Expired events are moved here. If one already existed, its new name is appended with its date (first raw, then à la 2022-11-02T04:44+01:00).
~/.ratrun/.reminders: Overrides user's RATRUN_REMINDERS, if present. One field-split line.
~/.ratrun/.tz: If present, value exported as TZ per-user (cf. tzset(3)). One line.
~/.ratrun/.prefix: Changes the user's mail subject prefix from "ratrun:"; "🐀" and empty are popular choices. One line.
~/.ratrun/.expcnt/: Contains counts for expired reminders for each event. Remove the file corresponding to an event from this directory to re-send its latest reminder. Entries here with no corresponding events are auto-pruned.

EXAMPLES

$ cat > .ratrun/call-robert
12:00
1h 0
bring up sales for q4
^D
$ echo 18:30 > .ratrun/'meet henry in 201'
$ { echo 2022-12-12T23:11; date; uptime; } > .ratrun/1yr-uptime

Assuming a default reminder time of "30m", the first reminders from each of these will, respectively, produce the following messages:

Date: Mon, 31 Oct 2022 11:00:42 +0100
Subject: ratrun: in 1h / on 12:00: call-robert

bring up sales for q4

and

Date: Mon, 31 Oct 2022 18:00:21 +0100
Subject: ratrun: in 30m / on 18:30: meet henry in 201

and

Date: Mon, 12 Dec 2022 22:41:12 +0100
Subject: ratrun: in 30m / on 23:11 (2022-12-12T23:11): 1yr-uptime

Mon 31 Oct 21:00:54 CET 2022
 21:00:54 up 322 days, 12:09,  4 users,  load average: 1.28, 0.69, 0.52

NAME