#keeper — services, jobs and logs
The keeper is the platform's process supervisor. It starts every registered daemon, keeps its pid file and log, restarts what died or hung, runs the scheduled jobs and rotates the logs. Aegis does not use systemd: the keeper itself is started by a SysV init script at boot.
Cubes provide service definitions; the keeper never guesses a path. A cube with a daemon implements service(), a cube with periodic work implements jobs(), and both become supervised as soon as the code is on disk.
Output is human-formatted throughout: these commands print their own lines and tables and never consult the global --json flag. Exit codes follow Conventions: 0 success, 1 failure, 2 usage, 130 Ctrl+C.
#How supervision works
that is not running, then hands each due job to a pool of four worker threads.
PermissionError whileprobing a pid means the process exists but belongs to another account, so it is never reported as stopped.
daemon that forks and exits gets a 2.5-second grace period to write the file as the new process. A service with writes_pid=False has the keeper's own child pid recorded instead.
loop. The next attempt waits 0, 10, 30, 60 and then 300 seconds between consecutive failures, so a broken daemon cannot fill the log or the process table. Staying up for 60 seconds clears the penalty.
than its timeout is treated as hung and restarted. A missing heartbeat file is not stale: a daemon that has just started may not have written one yet.
try. A cube that raises while beinginspected cannot abandon the rest of the tick.
stop sends SIGTERM, waits up to 15 seconds, then sends SIGKILL.aegis-keeper, so ps, top and pgrepshow the supervisor instead of another python3 -m aegis.
#Daemon control
#aegis keeper start
Starts the keeper in the background. If a live keeper already owns <run>/keeper.pid, nothing is started and the running pid is reported.
aegis keeper start| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
The child runs bin/aegis keeper daemon, appends its output to <logs>/keeper.log and claims the pid file. The command returns as soon as the process is spawned; a later tick brings the services up.
Examples:
aegis keeper startaegis keeper start && aegis keeper services✔ keeper started (pid 679986)Already running:
ℹ keeper already running (pid 679986)#aegis keeper stop
Destructive. Stops the supervision loop. The supervised services keep running, but nothing restarts them until the keeper is started again.
Asks the keeper to exit with SIGTERM and waits until the pid file is gone. The wait is deliberate: a restart that let the old process live a moment longer would bring up a keeper that still holds the previous cube modules.
aegis keeper stop| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Examples:
aegis keeper stopaegis keeper stop && aegis keeper statusℹ keeper stopped (pid 679986)Not running:
ℹ keeper not runningIf the process ignores SIGTERM for 15 seconds:
✖ keeper did not stop (pid 679986)The command exits 1 in that case and does not escalate to SIGKILL.
#aegis keeper restart
Destructive. Stops the loop, waits for the old process to leave, then starts a fresh one. Services are unsupervised during the gap.
aegis keeper restart| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
This is what a deploy needs: the daemon imports the cube modules once and keeps them for its whole life, so new code, a new service or a fixed path only takes effect after a restart. If the stop fails, the command exits 1 and does not start a second keeper.
Examples:
aegis keeper restartaegis keeper restart && aegis keeper servicesℹ keeper stopped (pid 679986)✔ keeper started (pid 681204)When the old loop was already gone:
ℹ keeper not running✔ keeper started (pid 681204)#aegis keeper status
Reports whether the keeper is alive. Exits 0 when running and 1 when stopped, which makes it usable in a script.
aegis keeper status| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Examples:
aegis keeper statusaegis keeper status || aegis keeper start✔ keeper is running (pid 679986)Stopped:
ℹ keeper is stopped#aegis keeper daemon
Runs the supervision loop in the foreground. This is the process that keeper start and the boot script launch.
aegis keeper daemon| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
The loop writes its own lines to <logs>/keeper.log, not to the terminal, so a foreground run looks quiet. It refuses to start a second copy: if the pid file names a live process, it logs already running (pid N) and exits 0. SIGTERM and SIGINT end it cleanly; the pid file is removed only while it still holds this process's pid.
Examples:
aegis keeper daemoncd /etc/aegis && ./bin/aegis keeper daemonThe log then contains:
2026-11-17 10:35:56 keeper started (pid 679986, tick 10s, 8 services)2026-11-17 10:36:07 bind: started (pid 680051)2026-11-17 10:40:12 aegis-tasker: no heartbeat, restarted (killed (pid 801564), started (pid 802341))2026-11-17 10:41:02 keeper stopped#aegis keeper enable
Writes /etc/init.d/aegis-keeper and registers it for the default runlevels with update-rc.d. The script forwards start, stop, restart and status to aegis keeper; no unit files and no systemd are involved.
aegis keeper enable| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Writing /etc/init.d requires root. If update-rc.d is missing or fails, the script is still written and the message says so:
✔ script written, update-rc.d failed: update-rc.d: not foundExamples:
aegis keeper enableaegis keeper enable && /etc/init.d/aegis-keeper status✔ enabled through /etc/init.d/aegis-keeper#aegis keeper disable
Destructive. Unregisters the boot hook and deletes
/etc/init.d/aegis-keeper. It does not stop a running keeper, and it does not touch the services.
aegis keeper disable| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Examples:
aegis keeper disableaegis keeper disable && aegis keeper stop✔ disabled and removed /etc/init.d/aegis-keeper#Services
#aegis keeper services
Lists every service the keeper would supervise, with its current state and pid file.
aegis keeper services| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
The list is sorted by service name. It contains every installed cube that provides service(), plus the collector services, the tasker, the AI daemon, pulse and Bird when those modules are enabled. A stopped service may be started by the next tick; the table shows the state at the moment of the call.
Examples:
aegis keeper servicesaegis keeper services | grep stoppedservice state pid file─────────────────────────────────────────────────────────aegis-tasker running (pid 8123) /aegis/run/tasker/tasker.pidbind stopped /aegis/run/bind/named.pidnginx running (pid 8044) /aegis/run/nginx/nginx.pidWith no cube installed:
ℹ no services registered#Scheduled jobs
#aegis keeper cron
Shows every enabled job with its effective interval, last run and last result.
aegis keeper cron| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Job definitions live in code. The effective interval, the enabled flag and the overlap guard live in aegis.db (cron_jobs); the panel edits the same rows. Before listing, the registry inserts jobs it has not seen and marks jobs that disappeared from the code as orphaned instead of deleting them. A disabled job is left out of this table.
Examples:
aegis keeper cronaegis keeper cron | grep logs-rotatejob every last run result──────────────────────────────────────────────────────────────logs-rotate 5m 2026-11-17 10:35:00 rotated 2 logs (48.3M)ssl-renew 6h 2026-11-17 08:00:00 nothing to renewA job that never ran shows never and -:
job every last run result──────────────────────────────────────ssl-renew 6h never -#aegis keeper cron-run
Runs one scheduled job immediately, whether its interval has elapsed or not.
aegis keeper cron-run NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | job name as shown by aegis keeper cron |
The run goes through the scheduler, so it takes the job's lock and is recorded in cron_logs like a scheduled run. Overlap protection is on by default: a second run while the first still holds the lock answers previous run is still in progress. A job that is disabled is not in the enabled list, so it is reported as unknown.
Examples:
aegis keeper cron-run logs-rotateaegis keeper cron-run ssl-renew✔ logs-rotate: nothing to rotateFailure or an unknown name exits 1:
✖ unknown job: ssl-reneww#Log rotation
#aegis keeper logs
Lists the logs the rotation job manages, with the policy that applies to each one. This is the default verb when no verb is given.
aegis keeper logs VERB NAME| Argument | Default | Meaning |
|---|---|---|
VERB | list | list, rotate or show |
NAME | none | part of a log path; required by show |
The verb is a positional argument, not a subcommand, so aegis keeper logs, aegis keeper logs list and aegis keeper logs show nginx all work. rotate and show are described below.
The listing uses stat only, so it never opens a file a daemon is writing. Rows are sorted by total disk cost, largest first. The file column is shortened relative to the log root it lives under.
Examples:
aegis keeper logsaegis keeper logs listfile class size limit gens disk─────────────────────────────────────────────────────────────nginx/access.log access 12.4M 32.0M 3 51.2Mnginx/error.log error 1.2M 16.0M 2 2.4Mkeeper.log service 512K 8.0M 1 1.0Mℹ 3 logs, 54.6M on diskWith no *.log under any root:
ℹ no log files#aegis keeper logs rotate
Runs the logs-rotate job now, through the scheduler, so it takes the job's lock and records the run. Files below their limit are left alone.
aegis keeper logs rotate| Argument / option | Default | Meaning |
|---|---|---|
| — | — | no arguments or options |
Examples:
aegis keeper logs rotateaegis keeper logs rotate && aegis keeper logs✔ rotated 2 logs (48.3M)Nothing reached its limit:
✔ nothing to rotateA disabled job or a run that still holds the lock is reported as an error and exits 1:
✖ logs-rotate: previous run is still in progress#aegis keeper logs show
Shows the policy of every log whose path contains the given text, and the generations that already exist.
aegis keeper logs show NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | case-insensitive part of a log path, for example access_json |
The match is a plain substring of the full path, so a directory name works too.
Examples:
aegis keeper logs show access_jsonaegis keeper logs show nginxlog /aegis/logs/nginx/access_json.logclass accesssize 12.4Mrotate at 32.0Mkeep 7compress yesdelaycompress yesgeneration size──────────────────────────access_json.log.1 12.1Maccess_json.log.2.gz 3.4MNo name or no match exits 1:
✖ show needs a part of the path, for example access_json✖ no log matches access-json#How rotation works
The job is registered in code as logs-rotate. It runs every [logs] interval seconds (300 by default, never below 10); the enabled flag and an overridden interval live in aegis.db like every other job.
It discovers *.log files under three kinds of root, without following symlinks:
[aegis] logs_dir — keeper, panel, tasker, AI, pulse, bird, collector;/aegis/logs) — nginx, PHP, databases, mail, FTP,certbot.
Each file is classified by its name and path, and each class has its own limit and generation count:
| Class | Recognised by | Default |
|---|---|---|
access | access in the file name | 32 MiB, 7 generations |
error | error in the file name | 16 MiB, 5 |
mail | postfix, dovecot, or a name starting with mail. | 64 MiB, 10 |
service | everything else | 8 MiB, 4 |
The method is copytruncate, because a supervised daemon keeps its log open for its whole life and most have no signal that reopens it. When a file reaches its limit:
.1 through a .part file, then the original istruncated — a crash during the copy leaves the log untouched;
compress, generations are gzipped. With delaycompress, .1 staysplain so it opens without unpacking, and .2 upward are .gz. Without delaycompress, compression starts at .1.
The generation past keep is deleted, so the disk cost of a log has a ceiling. One unreadable file does not stop the others; the result reports the rotated count and the failed count separately.
Relevant configuration:
[logs]interval = 300compress = truedelaycompress = true[logs.classes.mail]size_mb = 64keep = 10#Files
| Path | Content |
|---|---|
<run>/keeper.pid | pid of the supervision loop |
<logs>/keeper.log | supervision and job log |
database/storage/aegis/aegis.db | cron_jobs (schedule, locks) and cron_logs (history) |
<run>/<app>/<daemon>.pid | pid of each service |
<run>/<daemon>.heartbeat | liveness of a service that declares one |
<run>/<daemon>.lock | single-instance lock, when the daemon uses one |
<logs>/<app>/… | service output |
cron_logs keeps the newest 2000 rows; older runs are pruned as new ones arrive. A job lock is considered stale after one hour, and a live run renews it well before that, so a process that died without releasing the lock cannot block the job forever.
#Operational notes
aegis keeper restart. The daemon does not reload cubemodules.
keeper stop and keeper disable do not stop the supervised services. Useaegis restart for a full restart of the keeper, every service and the panel.
writes_pid=False still gets a pid file: the keeperwrites the pid of the process it started.
account is reported as running, not stopped.