EXECUTION.md

Scope

This document defines how Kron executes scheduled work in non-Kubernetes mode (krond). It describes:

  • Daemon lifecycle

  • Job process model

  • Forking and execution

  • Concurrency handling

  • State management

  • Failure handling

This specification applies to krond. Kubernetes execution is delegated to native Job resources and is not defined here.

Process Model Overview

Kron consists of:

  • krond — long-running daemon

  • krontab — configuration manager (writes config files)

  • Child processes — spawned per scheduled execution

krond is the only persistent process.

Each scheduled execution results in exactly one fork/exec cycle.

krond Lifecycle

Startup

On startup, krond:

  1. Loads configuration files.

  2. Validates all schedule syntax.

  3. Loads persisted state from disk.

  4. Computes the next period and chosen execution time for each entry.

  5. Starts the scheduler loop.

  6. Optionally writes PID file.

If configuration is invalid, krond exits with non-zero status.

Scheduler Loop

krond maintains an in-memory priority queue ordered by next chosen execution time.

Main loop:

  1. Determine earliest scheduled execution.

  2. Sleep until that timestamp.

  3. Wake up.

  4. Recompute decision for that job to confirm it is still valid.

  5. Attempt execution.

  6. Compute next period and chosen time.

  7. Reinsert into queue.

Time is always compared in UTC internally.

If system clock jumps forward, missed-period logic is applied. If system clock jumps backward, the queue is recalculated.

Job Identity

Each schedule entry has a stable identity:

<config_path>:<name>

Where <config_path> is the absolute path to the configuration file and <name> is the name field defined in the entry. See KRONTAB.md for the file format specification.

This identity is used for:

  • Seed derivation

  • Locking

  • State files

  • Logging

Fork and Exec Model

When a job is triggered:

  1. krond calls fork().

  2. Child process calls execve() with configured command.

  3. Parent process:

    • Records child PID

    • Monitors exit status via waitpid()

No shell wrapping is performed unless explicitly configured.

Default behavior:

  • Command is executed directly.

  • Arguments are passed as defined.

  • Environment is inherited from krond unless overridden.

Execution Environment

Each job may define:

  • user

  • group

  • env

  • cwd

  • umask

  • timeout

Before execve():

  1. If running as root and user specified:

    • setgid()

    • setuid()

  2. Apply chdir() if cwd defined.

  3. Apply umask() if defined.

  4. Set environment variables.

If privilege drop fails, execution is aborted.

Concurrency Handling

Each job has a concurrency policy:

  • allow

  • forbid

  • replace

allow

Multiple child processes may run simultaneously.

forbid

If a previous child process is still active:

  • New execution is skipped.

  • Event is logged.

  • Period is marked as skipped.

replace

If a previous child process is active:

  1. Send SIGTERM to active PID.

  2. Wait configurable grace period.

  3. If still running, send SIGKILL.

  4. Start new process.

Timeout Handling

If timeout is defined:

  1. Parent tracks execution duration.

  2. When timeout expires:

    • Send SIGTERM.

    • Wait grace period.

    • Send SIGKILL if necessary.

  3. Log timeout event.

Timeout applies per execution instance.

State Persistence

State is stored in:

/var/lib/krond/<hash>.json

State file contains:

  • Last handled period identifier

  • Last chosen execution time

  • Last run time

  • Last exit code

  • Active PID (if any)

  • Concurrency state

  • Seed metadata

State is written:

  • After scheduling decision

  • After execution completes

  • After skip due to concurrency

  • After missed deadline

Writes are atomic:

  1. Write to temporary file.

  2. fsync().

  3. Rename.

Missed Period Handling

If krond is down during a chosen execution time:

On restart:

  1. Compute period for current time.

  2. Determine whether chosen time is in the past.

  3. Apply deadline policy.

If deadline is zero:

  • Missed periods are skipped.

  • Only future periods are scheduled.

If deadline is non-zero:

  • If now <= chosen + deadline:

    • Execute immediately.

  • Otherwise:

    • Skip period.

No historical backlog is ever replayed beyond one bounded period.

Output Handling

Child process STDOUT and STDERR are handled by:

  • Inherit mode (default)

  • Redirect to file

  • Redirect to syslog

  • Discard

If redirected to file:

  • File path may include time formatting tokens.

  • Files are opened before fork.

  • Parent ensures file descriptors are closed.

Exit codes are logged.

Signal Handling

krond handles:

  • SIGTERM

  • SIGINT

  • SIGHUP

SIGTERM / SIGINT

  1. Stop accepting new triggers.

  2. Allow active child processes to complete.

  3. Optionally terminate active processes if configured.

  4. Persist state.

  5. Exit cleanly.

SIGHUP

  1. Reload configuration.

  2. Validate new schedules.

  3. Recompute queue.

  4. Preserve active child processes.

Invalid new configuration does not replace old configuration.

Locking Model

krond enforces single-daemon per system using:

  • PID file with file lock.

  • Or advisory lock on state directory.

If lock acquisition fails, daemon exits.

Isolation and Security

  • No command is executed through shell by default.

  • No interpolation is performed unless explicitly configured.

  • Environment variables must be explicitly defined to override inherited values.

  • Privilege drop is required for user switching.

Resource Limits

krond may configure:

  • RLIMIT_NOFILE

  • RLIMIT_NPROC

  • Optional per-job limits if supported

System resource limits are not modified unless explicitly configured.

Crash Recovery

If krond crashes:

  • State files remain intact.

  • On restart:

    • Active PID in state is verified.

    • If PID exists and matches expected command, it is considered active.

    • If PID does not exist, state is corrected.

No duplicate execution occurs for the same period.

Determinism Guarantee

For each job and period:

  • The chosen execution time is stable across daemon restarts.

  • Seed derivation is stable.

  • Fork timing may vary slightly due to scheduler latency, but chosen timestamp is invariant.

Performance Model

krond must support:

  • Thousands of schedule entries.

  • Sub-second scheduling precision.

  • O(log n) insertion/removal from scheduling queue.

  • Minimal CPU usage when idle.

Memory usage scales linearly with number of entries.

Failure Guarantees

Kron guarantees:

  • At most one execution per period.

  • No uncontrolled backfill.

  • No duplicate execution due to restart.

  • No hidden implicit retries.

Execution failures are surfaced through logs and exit codes only.

Kron does not retry failed commands unless explicitly configured in future versions.

Summary

krond is:

  • A single-process scheduler.

  • Deterministic in decision-making.

  • Fork/exec based.

  • Policy-driven in concurrency.

  • Bounded in catch-up behavior.

  • Transparent in logging.

  • Safe by default.