Skip to main content

Scheduler status & sweeps

The scheduler is the periodic half of CertAutoPilot: it finds work and enqueues jobs; workers execute them. It runs in processes started with --mode=scheduler or --mode=all, and only one instance per component acts at a time — leadership is held via a MongoDB distributed lock (see Cluster instances for TTLs and failover timing). Sweep results are visible on Settings → System Status (how to read that page).

Sweep catalog​

Three leader-elected components, nine visible sweeps (plus an internal license-validation sweep hidden from the UI):

Main Scheduler​

All main-scheduler sweeps run once per cycle; the cycle interval is Settings → General → Renewal Check Interval (renewal_check_interval_minutes, default 60, range 5–1440).

SweepWhat it does
Renewal CheckFinds certificates due for renewal (see below) and enqueues renew_certificate / msca_renew_certificate jobs. Skipped entirely when the installation is over its certificate limit.
ARI Window RefreshRefreshes ACME Renewal Information windows for eligible certificates (up to 100 per cycle) and may move next_renewal_at earlier when the CA advises it.
Expiration CheckEnqueues one certificate_expiration_check job per hour (hourly idempotency key) — drives expiry notifications.
Revocation CheckEnqueues one hourly revocation status check job.
Distribution SweepEnqueues distribution jobs for certificates whose linked distributions are pending re-distribution, and reconciles fan-outs stuck mid-aggregation.
Zombie Certificate RecoveryResets certificates stuck in renewal_in_progress (> 45 min) or issuing (> 2 h) and re-enqueues them if auto-renew is on.
DNS Cleanup RetryRe-enqueues cleanup_dns jobs for workflows that finished issuance but left challenge TXT records behind.

Domain Checker​

SweepWhat it doesInterval
Domain WHOIS CheckFinds tracked domains due for a WHOIS expiration check and enqueues domain_expiration_check jobs in batches, rate-limited (2s between enqueues).domain_check_interval_minutes (default 60); batch size domain_check_batch_size (default 50)

Discovery Checker​

SweepWhat it doesInterval
Discovery Source ScanFinds discovery sources due for a scan and enqueues discovery_execute jobs.hourly (fixed)
Discovery Zombie RecoveryMarks discovery runs whose heartbeat is > 10 min stale (started > 30 min ago) as failed so the source can be re-scanned.hourly (fixed)

How the renewal sweep decides a certificate is due​

A certificate is picked up when all of these hold:

  • auto_renew is on,
  • status is active or renewal_pending,
  • next_renewal_at ≤ now,
  • renewal attempts haven't exhausted the maximum.

next_renewal_at is computed at issuance/renewal as expires_at − renewal_threshold_days, where the threshold is the certificate's own Renewal Threshold if set, otherwise the global default (Settings → General → Renewal Threshold, default 30 days). If the CA supports ACME ARI, the ARI sweep can override next_renewal_at with the CA's suggested window. Full lifecycle details: Renewal.

Detection latency

The sweep runs every renewal_check_interval_minutes. With the default 60, a certificate becomes eligible up to an hour before the scheduler notices — irrelevant against a 30-day threshold, but worth remembering when testing with tiny thresholds.

Manual vs scheduled work​

The scheduler is only one producer for the job queue. Manual actions — issuing, renewing, revoking from the UI or API, bulk renew, running a distribution — enqueue jobs directly and do not wait for a sweep. The same workers execute both kinds; the scheduler's job is exclusively the periodic discovery of due work. Consequently, a dead scheduler doesn't break manual operations — it silently stops automatic renewals, which is why the System Status health badge flips to critical when no leader holds the lock.

Status endpoint​

  • GET /api/v1/settings/scheduler-status (admin) — per-component health, active leader, and each sweep's last run with duration and counters (scanned, matched, enqueued, updated, cleaned, skipped, failed).
  • GET /api/v1/settings/scheduler-status/history?component=<c>&sweep=<s>&limit=N (admin) — recent runs for one sweep (default 20, max 100; retained 7 days).

Both feed the Settings → System Status page.

See also​