Cron · XB Field Notes

Cron system and user tables have different contracts

Wed, 12 Jan 2028 00:00:00 +0000

Cron accepts schedules from more than one kind of table. A user crontab belongs to one account, while system tables can name the account for each entry. Copying a line between them without adjusting its fields changes what cron interprets as the command. Identify the table format before debugging an apparently correct five-field calendar expression.

The account column changes the parser boundary

A conventional user entry contains minute, hour, day of month, month, day of week, then command text. The crontab command installs it for the selected user. Debian’s /etc/crontab and files under /etc/cron.d add a username after the five schedule fields. That username belongs to the system-table format; it is not an optional annotation in a user’s command.

The month constraint remains required. When both day-of-month and day-of-week fields are restricted, the Debian/Vixie day rule permits either day match; month and weekday are not alternatives. Check the scheduler’s documented dialect before transferring expressions to products with seconds fields or different day rules. Familiar-looking spacing does not establish compatible semantics.

System drop-ins have ownership, permission, filename, and final-newline requirements. On Debian, use root-owned files that are not group- or other-writable and accepted names rather than arbitrary backup suffixes. Periodic directories such as /etc/cron.daily are invoked through the distribution’s scheduling arrangement, commonly using run-parts; every script is not independently parsed as a crontab. Inspect the installed arrangement before deciding when it runs.

When it breaks

Putting root after the five fields in root’s user crontab asks the shell to execute a command named root. Installation success cannot prove that this command exists. Conversely, omitting the account from a system entry moves command text into the username position. Review both the parser boundary and the effective identity, especially when the job writes files or accesses protected data.

The job environment is also a contract. Do not assume interactive aliases, shell startup files, or variables from the daemon’s parent shell are available. Set required values explicitly and choose an intentional PATH and interpreter. Environment settings in a cron.d file should not be assumed to inherit those in /etc/crontab. Test permissions and outputs as the actual execution account.

Percent signs have special handling before the shell sees the complete command. Unescaped percent characters delimit standard input, with subsequent percents becoming newlines. Shell quoting alone does not remove cron’s interpretation. Keep complex commands in scripts and escape literal percent signs when they must appear directly in a table entry. Separate scheduling syntax checks from command execution and application outcome checks.

Check it quickly

Use a fresh disposable Debian 12 Docker container as root with python3, cron, procps, and passwd installed. Ensure it has no active cron daemon, root crontab, or account named xbtime. Save this as cron-tables.py and run python3 cron-tables.py. It creates only its temporary account, task table, and files, waits up to seventy-five seconds for a real scheduled minute, then removes them.

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import pwd
import shutil
import subprocess
import time

assert os.geteuid() == 0 and Path('/.dockerenv').exists(), 'use a disposable root Linux container'
assert subprocess.run(['pgrep', '-x', 'cron'], capture_output=True).returncode == 1
assert subprocess.run(['crontab', '-l'], capture_output=True).returncode != 0
assert shutil.which('root') is None
username = 'xbtime'
try:
 pwd.getpwnam(username)
except KeyError:
 pass
else:
 raise AssertionError('test account already exists')
system_table = Path('/etc/cron.d/xbcatm_time_test')
assert not system_table.exists()
subprocess.run(['useradd', '--create-home', '--shell', '/bin/sh', username], check=True)
account = pwd.getpwnam(username)
daemon = None
try:
 with TemporaryDirectory(prefix='cron-tables-') as directory:
 root = Path(directory)
 os.chown(root, account.pw_uid, account.pw_gid)
 worker = root / 'worker.py'
 worker.write_text('''from pathlib import Path
import json,os,sys
root=Path(__file__).parent
mode=sys.argv[1]
data={'uid':os.getuid(),'table':os.environ.get('LAB_TABLE'),
 'path':os.environ.get('PATH'),'shell':os.environ.get('SHELL'),
 'parent_only':os.environ.get('PARENT_ONLY')}
if mode=='percent': data['stdin']=sys.stdin.read()
(root/(mode+'.json')).write_text(json.dumps(data))
''')
 user_table = ('SHELL=/bin/sh\nPATH=/usr/bin:/bin\nLAB_TABLE=user\n'
 f'* * * * * /usr/bin/python3 {worker} user\n'
 f'* * * * * /usr/bin/python3 {worker} percent%first%second\n'
 f'* * * * * root /usr/bin/id >{root}/wrong-column.err 2>&1\n')
 subprocess.run(['crontab', '-'], input=user_table, text=True, check=True)
 invalid = subprocess.run(['crontab', '-'], input='* * * * * /bin/true',
 text=True, capture_output=True)
 assert invalid.returncode != 0
 assert subprocess.check_output(['crontab', '-l'], text=True) == user_table
 system_table.write_text('SHELL=/bin/sh\nPATH=/usr/bin:/bin\nLAB_TABLE=system\n'
 f'* * * * * {username} /usr/bin/python3 {worker} system\n')
 system_table.chmod(0o644)
 daemon = subprocess.Popen(['cron', '-f'], env={**os.environ, 'PARENT_ONLY': 'parent-demo'},
 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 try:
 deadline = time.monotonic() + 75
 names = ['user.json', 'system.json', 'percent.json', 'wrong-column.err']
 while time.monotonic() < deadline:
 assert daemon.poll() is None
 if all((root/name).exists() and (root/name).stat().st_size for name in names):
 break
 time.sleep(0.2)
 else:
 raise AssertionError('scheduled table outputs were not produced')
 user = json.loads((root/'user.json').read_text())
 system = json.loads((root/'system.json').read_text())
 percent = json.loads((root/'percent.json').read_text())
 wrong = (root/'wrong-column.err').read_text()
 assert user['uid'] == 0 and user['table'] == 'user'
 assert system['uid'] == account.pw_uid and system['table'] == 'system'
 assert all(value['parent_only'] is None for value in (user, system))
 assert all(value['path'] == '/usr/bin:/bin' for value in (user, system))
 assert percent['stdin'] == 'first\nsecond\n'
 assert 'root: not found' in wrong
 print(json.dumps({'user_table': user, 'system_table': system,
 'missing_final_newline_rejected': invalid.returncode,
 'previous_table_preserved': True, 'percent_stdin': percent['stdin'],
 'username_in_user_table_fails': wrong.strip()}), flush=True)
 finally:
 daemon.terminate()
 daemon.communicate(timeout=5)
 daemon = None
finally:
 if daemon is not None:
 daemon.terminate()
 daemon.communicate(timeout=5)
 system_table.unlink(missing_ok=True)
 subprocess.run(['crontab', '-r'], capture_output=True)
 subprocess.run(['userdel', '--remove', username], capture_output=True, check=True)

The user-table job runs as UID zero. The system-table job runs as the newly created account, UID 1000 in this run. Each receives its own LAB_TABLE value and explicit PATH; neither receives the daemon parent’s PARENT_ONLY variable. A percent-bearing entry supplies first\nsecond\n on standard input. The wrongly inserted username produces root: not found, despite its table installing successfully.

An attempted replacement missing its final newline is rejected with exit one, and the previous table remains intact. All assertions passed on cron 3.0pl1-162. Separate probes found that this package accepted malformed minute text even with its dry-run option, so no universal field-validation guarantee is inferred from a zero exit status. The exercise verifies observed account, environment, parsing, and installation behavior; it does not test mail delivery, daylight-saving handling, or business success. Keep those additional requirements visible when deploying a real scheduled task.

Sources

Debian 12: crontab(5), user/system table syntax, environment and percent handling, checked 2026-09-13.
Debian 12: cron(8), system drop-ins, ownership and execution environment, checked 2026-09-13.
Debian 12: crontab(1), installation, dry-run behavior and newline requirements, checked 2026-09-13.

Cron repeats on the calendar

Thu, 30 Sep 2027 00:00:00 +0000

Cron matches calendar fields and launches commands at matching times. It does not inherently wait for an earlier invocation of the same command to finish. If a minute-level task takes seventy seconds, the next minute can launch another copy. Treat trigger policy, concurrency policy, and successful completion as separate responsibilities when operating recurring work.

Read fields as calendar selections

A conventional user crontab entry contains minute, hour, day of month, month, day of week, then the command. Asterisks select all values in their fields. A step such as */15 in minutes selects minute values within each hour; it is not a timer measuring fifteen minutes since the previous completion. A step that does not divide the field range evenly can produce unequal gaps across boundaries.

Day matching has a special rule in the Debian/Vixie format: when day of month and day of week are both restricted, either matching day can permit execution, while the minute, hour, and month constraints still apply. This is not a disjunction between month and weekday. Write representative dates down and verify the intended calendar before installing a terse expression.

Timezone, daylight-saving changes, and downtime affect calendar scheduling. Implementations differ in how they handle skipped or repeated times. Debian cron documents special handling for certain small clock changes and fixed-time jobs, so rules copied from another scheduler may be wrong here. This experiment does not change the clock or test those transition cases. A calendar trigger is also not a durable queue that automatically guarantees every missed run will be replayed.

When it breaks

Overlapping jobs can duplicate side effects, compete for resources, or overwrite shared files. If one invocation must run at a time, implement that policy explicitly. A nonblocking advisory lock can let a later invocation record a skip; a blocking lock can instead leave waiting processes. Neither choice provides exactly-once business effects or repairs a partially completed operation.

A local file lock only coordinates participants using the same relevant locking facility. It does not automatically serialize jobs on unrelated hosts, and network filesystem semantics require separate examination. Keep the lock held for the work’s lifetime, and make skipped work visible. Silently dropping every later trigger while one worker hangs can look like a healthy schedule unless completion age is monitored.

Cron is not universally log-free. Debian logs job starts to syslog by default and offers additional logging controls. Command output may be mailed when a working mail path exists, but a minimal container often lacks that path. Record useful start, completion, failure, and skip outcomes through an intentional destination. A start message proves dispatch, not completion of the application’s task.

Check it quickly

Use a fresh disposable Debian 12 Docker container as root, with no existing root crontab or cron daemon. Install python3, cron, and procps using apt, save the following as cron-overlap.py, and run python3 cron-overlap.py. Allow roughly two minutes: the script waits for actual calendar ticks rather than replacing cron with a simulated scheduler.

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess
import time

assert os.geteuid() == 0 and Path('/.dockerenv').exists(), 'use a disposable root Linux container'
assert subprocess.run(['pgrep', '-x', 'cron'], capture_output=True).returncode == 1
assert subprocess.run(['crontab', '-l'], capture_output=True).returncode != 0

with TemporaryDirectory(prefix='cron-overlap-') as directory:
 root = Path(directory)
 events_path = root / 'events.jsonl'
 stop = root / 'stop'
 worker = root / 'worker.py'
 worker.write_text('''from pathlib import Path
import fcntl,json,os,sys,time
root=Path(__file__).parent
kind=sys.argv[1]
def record(event):
 data=json.dumps({'event':event,'kind':kind,'pid':os.getpid(),'monotonic':time.monotonic()})+'\\n'
 fd=os.open(root/'events.jsonl',os.O_WRONLY|os.O_CREAT|os.O_APPEND,0o600)
 try: os.write(fd,data.encode())
 finally: os.close(fd)
lock=None
if kind=='locked':
 lock=open(root/'job.lock','a')
 try: fcntl.flock(lock,fcntl.LOCK_EX|fcntl.LOCK_NB)
 except BlockingIOError:
 record('skip')
 raise SystemExit(0)
record('start')
try:
 until=time.monotonic()+70
 while time.monotonic()<until and not (root/'stop').exists(): time.sleep(0.1)
finally:
 record('end')
 if lock: lock.close()
''')
 table = ''.join(f'* * * * * /usr/bin/python3 {worker} {kind} >>{root}/worker.log 2>&1\n'
 for kind in ('plain', 'locked'))
 subprocess.run(['crontab', '-'], input=table, text=True, check=True)
 daemon = subprocess.Popen(['cron', '-f'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 def read_events():
 if not events_path.exists():
 return []
 return [json.loads(line) for line in events_path.read_text().splitlines()]
 try:
 deadline = time.monotonic() + 140
 while time.monotonic() < deadline:
 assert daemon.poll() is None, 'cron exited'
 events = read_events()
 plain = [e for e in events if (e['kind'], e['event']) == ('plain', 'start')]
 locked = [e for e in events if (e['kind'], e['event']) == ('locked', 'start')]
 skipped = [e for e in events if (e['kind'], e['event']) == ('locked', 'skip')]
 if len(plain) >= 2 and skipped:
 break
 time.sleep(0.2)
 else:
 raise AssertionError('two real cron ticks were not observed')
 assert len(plain) == 2 and len(locked) == 1 and len(skipped) == 1
 assert plain[1]['monotonic'] - plain[0]['monotonic'] < 70
 assert not any(e['event'] == 'end' and e['pid'] == plain[0]['pid'] for e in events)
 print(json.dumps({'actual_cron_starts': len(plain), 'overlap_observed': True,
 'seconds_between_starts': round(plain[1]['monotonic']-plain[0]['monotonic'], 3),
 'locked_starts': len(locked), 'locked_skips': len(skipped)}), flush=True)
 finally:
 daemon.terminate()
 stop.touch()
 daemon.communicate(timeout=5)
 subprocess.run(['crontab', '-r'], check=True)
 deadline = time.monotonic() + 5
 while time.monotonic() < deadline:
 events = read_events()
 started = {e['pid'] for e in events if e['event'] == 'start'}
 ended = {e['pid'] for e in events if e['event'] == 'end'}
 if started <= ended:
 break
 time.sleep(0.1)
 else:
 raise AssertionError('test workers did not finish')

Two every-minute entries run workers that would last seventy seconds. The plain worker has no lock. The locked worker uses a shared file and a nonblocking exclusive flock, recording a skip when acquisition fails. Each event includes the worker PID and a monotonic timestamp, so distinct invocations and their overlap can be checked directly.

On Debian cron 3.0pl1-162, the plain worker started twice, 60.003 seconds apart, before its first invocation ended. The guarded worker started once and recorded one skip. All assertions passed. Cleanup stopped cron, signaled the test workers through their stop file, waited for their end records, and removed the temporary crontab. The experiment verifies local overlap and explicit exclusion; it does not implement durable retries, distributed locking, recovery after reboot, or exactly-once effects. Select those policies from the job’s actual business contract instead of assuming the calendar expression supplies them.

Sources

Debian 12: crontab(5), calendar fields, steps and the two day fields, checked 2026-09-13.
Debian 12: cron(8), daemon execution, logging and clock-change behavior, checked 2026-09-13.
Linux: flock(2), advisory locks and nonblocking acquisition, checked 2026-09-13.