Most small studios end up with a few scheduled jobs: a nightly backup, a script that pulls store reports, a certificate renewal, a cleanup task for old build artifacts. They usually begin as one line in a crontab or a plist copied from somewhere. A few months later, nobody remembers whether they still run.
This post covers how to set up scheduled jobs on Linux (cron) and macOS (launchd) so they behave the same way every time and fail where you can see it. Neither tool is hard to use. The trouble is that both run your script in an environment that is quite different from your terminal.
Pick the right scheduler for the machine
- Linux server or VPS: cron is installed almost everywhere and works fine for most jobs. systemd timers are also an option if you want built-in logging through
journalctl, but cron is enough for the examples here. - macOS (a build Mac, a Mac mini in a closet, your laptop): use launchd. cron still exists on macOS, but Apple treats launchd as the supported scheduler. launchd also deals with sleep better, as covered below.
Whichever you use, the rules are the same: start from a known environment, log everything, prevent overlapping runs, and check from outside that the job ran.
Rule 1: Write the job as a standalone script
Keep logic out of the crontab line and out of the plist. Point the scheduler at one executable script that sets up everything it needs. Then you can run that exact script by hand and get the same behavior the scheduler gets.
#!/usr/bin/env bash
set -euo pipefail
# Known environment, regardless of who calls us
export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
export LANG="en_US.UTF-8"
cd "$(dirname "$0")"
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] start backup"
./do-backup.sh
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] done"A few details matter here:
set -euo pipefailmakes the script stop at the first failing command and return a non-zero exit code. Without it, a failed step in the middle can still end in a "success" exit.- An explicit PATH is the most common fix for "works in my terminal, fails in cron." cron and launchd both start jobs with a minimal PATH, so tools installed through Homebrew or a version manager often won't be found.
cdinto the script's own directory so relative paths always resolve the same way.- UTC timestamps in log lines make it easy to compare logs across machines.
Rule 2: Prevent overlapping runs
If a job that runs every 15 minutes sometimes takes 20, two copies can end up writing to the same files. On Linux, flock handles this:
*/15 * * * * /usr/bin/flock -n /tmp/sync-reports.lock /home/deploy/jobs/sync-reports.sh >> /home/deploy/logs/sync-reports.log 2>&1With -n, the second copy exits right away instead of waiting. macOS doesn't include flock by default, so a lock directory works as a portable alternative, because mkdir either creates the directory or fails in one step:
LOCK="/tmp/sync-reports.lock"
if ! mkdir "$LOCK" 2>/dev/null; then
echo "already running, skipping"
exit 0
fi
trap 'rmdir "$LOCK"' EXITlaunchd also won't start a second instance of a job whose previous run is still going, so overlap is less likely there. A lock still protects you when you run the script by hand while the scheduled run is active.
Setting up cron properly
Edit the crontab with crontab -e as the user the job should run as, not as root unless it really needs root. A tidy crontab looks like this:
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
MAILTO=""
# m h dom mon dow command
15 3 * * * /home/deploy/jobs/backup.sh >> /home/deploy/logs/backup.log 2>&1
*/15 * * * * /usr/bin/flock -n /tmp/sync.lock /home/deploy/jobs/sync.sh >> /home/deploy/logs/sync.log 2>&1Things that commonly go wrong with cron:
- The
%character. In a crontab,%means newline. If you writedate +%Fdirectly in the command, it breaks. Put the logic in the script, or escape it as\%. - Timezone. cron uses the system timezone. If the server runs in UTC and you think in local time, "3 a.m." will be off. Check with
timedatectlordate, and add a comment saying which timezone the schedule assumes. - Missed runs. If the machine is off at the scheduled time, plain cron skips that run and does not catch up. On a server that is always on, this rarely matters. On a machine that reboots or sleeps, it can.
- Output going nowhere. Without redirection, cron tries to email output. Usually no mail is set up, so the output is lost. Always redirect to a log file.
Setting up launchd on macOS
A per-user job is a plist in ~/Library/LaunchAgents/. Use a reverse-DNS label and the same name for the file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.example.nightly-backup</string>
<key>ProgramArguments</key>
<array>
<string>/Users/me/jobs/backup.sh</string>
</array>
<key>StartCalendarInterval</key>
<dict>
<key>Hour</key><integer>3</integer>
<key>Minute</key><integer>15</integer>
</dict>
<key>StandardOutPath</key>
<string>/Users/me/Library/Logs/nightly-backup.log</string>
<key>StandardErrorPath</key>
<string>/Users/me/Library/Logs/nightly-backup.log</string>
</dict>
</plist>Validate the file, then load it:
plutil -lint ~/Library/LaunchAgents/com.example.nightly-backup.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.nightly-backup.plist
# Run it now, without waiting for the schedule
launchctl kickstart -k gui/$(id -u)/com.example.nightly-backup
# Inspect state, last exit code, and paths
launchctl print gui/$(id -u)/com.example.nightly-backup
# Unload before editing the plist, then bootstrap again
launchctl bootout gui/$(id -u)/com.example.nightly-backuplaunchd details that catch people out:
- No tilde expansion.
~/jobs/backup.shin a plist will not work. Use absolute paths everywhere. - No shell.
ProgramArgumentsis run directly, so pipes, redirects and&&do nothing. This is another reason to keep logic in a script. - Sleep behavior. If the Mac is asleep when a
StartCalendarIntervaljob is due, launchd runs it once after the Mac wakes. That is usually what you want for backups, but it means the job may run at an unexpected time. If several runs were missed, they are combined into one. - Agents vs daemons. Jobs in
~/Library/LaunchAgentsonly run while that user is logged in. A job that has to run on a headless Mac with nobody logged in belongs in/Library/LaunchDaemons, owned by root, with aUserNamekey if it shouldn't run as root. - Privacy permissions. Scripts that read protected folders such as Documents, Desktop or external volumes may fail with permission errors until the binary that runs them is granted access in System Settings under Privacy & Security. Check the log for "Operation not permitted."
Rule 3: Make failure visible
A log file only helps if someone reads it. Two cheap ways to make sure a broken job gets noticed:
Report on exit
Add a trap that sends a notification when the script exits non-zero. The notification target can be anything you already watch: a chat webhook, an email relay, a push service.
notify_failure() {
curl -fsS -m 10 -X POST "$ALERT_WEBHOOK_URL" \
-d "job=nightly-backup host=$(hostname) status=failed" || true
}
trap 'rc=$?; [ $rc -ne 0 ] && notify_failure; exit $rc' EXITLoad the webhook URL from a file outside the repository instead of writing it into the script.
Check in on success
Failure alerts don't fire if the job never starts, for example when the plist was never loaded, the crontab was overwritten, or the machine was off. The more reliable pattern is a dead man's switch: the job pings an endpoint after it succeeds, and you get alerted if no ping arrives within the expected window. Several uptime and cron-monitoring services offer this, or you can build a simple version on a server you already monitor. If you already have basic server checks in place, as described in Simple Monitoring for a Small Server, scheduled-job check-ins fit in the same place.
Keep logs from growing forever
Appending to a log on every run is fine until the disk fills up. On Linux, add a logrotate entry for your job logs. On macOS, the simplest fix is to have the script trim its own log:
LOG="$HOME/Library/Logs/nightly-backup.log"
if [ -f "$LOG" ]; then
tail -n 5000 "$LOG" > "$LOG.tmp" && mv "$LOG.tmp" "$LOG"
fiTo choose a good line count, look at how many lines one run writes and keep a few weeks of history.
A short checklist for every new job
- The logic is in a script with
set -euo pipefail, an explicit PATH, and absolute paths. - You have run the script by hand, and it worked.
- stdout and stderr go to a log file, and that log is rotated or trimmed.
- Overlapping runs are prevented with
flockor a lock directory. - The schedule's timezone is written down next to the schedule.
- A failure sends a notification, and a missing success check-in raises an alert.
- The crontab or plist is saved in a private ops repository so you can rebuild the machine.
- You have triggered one run through the scheduler itself (
launchctl kickstart, or a temporary schedule a couple of minutes ahead in cron) and read the log afterward.
Wrapping up
cron and launchd are reliable tools. Nearly all scheduled-job problems come from the gaps around them: a different PATH, output that goes nowhere, two runs at once, or a job that quietly stopped being scheduled. Put the logic in a standalone script, log every run, use a lock, and have each job report success to something that will notice when the reports stop. Doing this when you add a job is quick, and it saves you from discovering months later that your backups stopped.