Events
Every change the daemon sees becomes an event: a container starting, a
deployment being installed, a node being lost, a replica being moved. shc events lists the newest ones and returns. The listing is bounded, so it
always ends.
$ shc events ls -n 5...Each line opens with the time and the node that reported the event, then a
sentence, then the deployment it belongs to. shc events without ls is the
same listing; -n bounds it and defaults to 100.
Cause two changes and read them back. A restart is an audit event and the docker events of the container it restarts; a protect is one audit event. The docker rows arrive within a few seconds of the restart.
$ shc restart webrestarting deployment "web"✔ restarted deployment "web"$ shc protect placedstack "placed" protected$ shc events ls -T audit,docker -s web -n 42026-10-09T06:58:28Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 stopped, deployment prod/web/prod2026-10-09T06:58:28Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 exited with code 0, deployment prod/web/prod2026-10-09T06:58:30Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 started, deployment prod/web/prod2026-10-09T06:58:30Z home01 restarted stack web, deployment prod/web/prod, by shc-T picks the event types. The default set is docker, audit and the four
placement types; name one or several to narrow it. -s keeps the events of
one deployment. -q hides the exec events docker raises for every
healthcheck, which is most of the stream on a busy node.
$ shc events ls -T docker -n 3...$ shc events ls -T audit -n 22026-10-11T02:45:57Z home01 restarted stack web, deployment prod/web/prod, by shc2026-10-11T02:46:00Z home01 armed the destroy guard on stack placed, deployment prod/placed/prod, by shc$ shc events ls -T placement_bind,placement_move,placement_move_cleared,placement_retire -n 3...$ shc events ls -s web -n 32026-10-11T02:45:55Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 exited with code 0, deployment prod/web/prod2026-10-11T02:45:56Z home01 container prod_prod_web-nginx-r0-nginx-r0-1 started, deployment prod/web/prod2026-10-11T02:45:57Z home01 restarted stack web, deployment prod/web/prod, by shc$ shc events ls -q -n 3...--node keeps the events one node reported. It takes the node’s name, or
the id shc node info prints. Its docker rows depend on what the node’s
containers did last, so read its audit rows: the two changes above are the
newest home01 reported.
$ shc node info home01...$ shc events ls --node home01 -T audit -n 22026-10-11T02:45:57Z home01 restarted stack web, deployment prod/web/prod, by shc2026-10-11T02:46:00Z home01 armed the destroy guard on stack placed, deployment prod/placed/prod, by shc-f follows instead of listing. It opens a stream and prints events as they
happen, and it does not return on its own, so run it in a tmux session, cause
an event from this shell and read the session’s screen. --since with -f
replays everything newer than a sequence id before going live; 1 replays
from the start of the window the daemon keeps.
$ tmux new -d -x 200 -y 50 -s ev shc events -f -q --since 1$ shc unprotect placedstack "placed" unprotected$ tmux capture-pane -pt ev...2026-10-09T05:24:22Z home01 disarmed the destroy guard on stack placed, deployment prod/placed/prod, by shc$ tmux kill-session -t ev--audit reads a different thing: the audit chain, the tamper-evident record
of what was done and by whom. It is a table, filtered by the deployment with
-s, by code with --event, by actor with --actor and by date with
--since and --until. -a drops the deployment filter your context would
add.
$ shc events --audit -n 3CREATED AT CODE ACTOR STACK MESSAGE ID TENANT ENVIRONMENT...$ shc events --audit -s placed -n 2CREATED AT CODE ACTOR STACK MESSAGE ID TENANT ENVIRONMENT2026-10-11T02:46:21.788130215Z A200404STKUNP shc placed disarmed the destroy guard on stack placed 1b5020cd-136d-4e53-9621-08464ccb2425 prod prod2026-10-11T02:46:00.083941739Z A200403STKPRO shc placed armed the destroy guard on stack placed e9252918-474a-4fc9-9efe-b390160558c6 prod prod$ shc events --audit --event A200403STKPRO -n 1CREATED AT CODE ACTOR STACK MESSAGE ID TENANT ENVIRONMENT2026-10-11T02:46:00.083941739Z A200403STKPRO shc placed armed the destroy guard on stack placed e9252918-474a-4fc9-9efe-b390160558c6 prod prod$ shc events --audit --actor shc -a -n 2...$ shc events --audit --since 2026-10-01 --until 2027-10-01 -n 2...The actor is shc here because every command on this ladder runs as the
node’s root through the daemon’s socket. On a cluster with users signed in
through Keycloak, the actor is the user.
An event can also leave the cluster as a notification. Two kinds of config
row make one: a transport under notification.providers, named by you and
typed webhook, email, ntfy, slack or discord, and a rule in notifications
that names the event codes it watches and the transport that carries them.
Write a webhook transport called ops and a rule that sends it the test
event’s code.
$ shc config set notification.providers.ops.type webhookKEY VALUE SCOPEnotification.providers.ops.type webhook global$ shc config set notification.providers.ops.url http://127.0.0.1:18099/hookKEY VALUE SCOPEnotification.providers.ops.url http://127.0.0.1:18099/hook global$ shc config set notifications '[{"name": "tell-ops", "provider": "ops", "on": ["V200700NTFSNT"]}]'KEY SCOPEnotifications global
┌─ value ───────────────────────────────┐│ NAME ON PROVIDER ││ tell-ops V200700NTFSNT ops │└───────────────────────────────────────┘$ shc notification lsNAME CHANNEL ON DESTINATION PROVIDERtell-ops generic V200700NTFSNT http://127.0.0.1:18099/**** opsbackup-failed none X500473BKPNOA,X500474BKPSRQ,X500467BKPHKF nowhere to send: notification.providers.operator is not defined operatorbackup-fire-dropped none X500204BKSCSK,X500205BKSCTO nowhere to send: notification.providers.operator is not defined operatorbackup-unprotected none X500470BKPCOV,X500478BKPPRO,X200091BKPCOW nowhere to send: notification.providers.operator is not defined operatorshc notification ls lists each rule with the codes it watches and where it
sends them, the path of the address hidden. Your rule comes first. The three
after it ship with SHC and watch the backup failure codes: a run that left
no archive, a scheduled run that was skipped or cancelled, and a deployment
no backup protects. They send through a provider named operator, and until
you define one they have nowhere to send. A rule of yours with one of their
names replaces it. shc notification test sends a
rule one event now, with the code, message and payload you give it. Nothing
listens on port 18099 here, so the daemon answers with the receiver’s
refusal; pointed at a real receiver, the same command delivers.
$ shc notification test tell-ops --code V200700NTFSNT --message 'a test from learn' --payload '{"from": "learn"}'shc: [X500701NTFSND] notification send failed webhook Post "http://127.0.0.1:18099/hook": dial tcp 127.0.0.1:18099: connect: connection refusedRemove the rule and the transport.
$ shc config unset notificationsKEY SCOPE REMOVEDnotifications global true$ shc config unset notification.providers.ops.typeKEY SCOPE REMOVEDnotification.providers.ops.type global true$ shc config unset notification.providers.ops.urlKEY SCOPE REMOVEDnotification.providers.ops.url global true$ shc notification lsNAME CHANNEL ON DESTINATION PROVIDERbackup-failed none X500473BKPNOA,X500474BKPSRQ,X500467BKPHKF nowhere to send: notification.providers.operator is not defined operatorbackup-fire-dropped none X500204BKSCSK,X500205BKSCTO nowhere to send: notification.providers.operator is not defined operatorbackup-unprotected none X500470BKPCOV,X500478BKPPRO,X200091BKPCOW nowhere to send: notification.providers.operator is not defined operatorThe shipped rules stay. shc doctor says so at info while they have
nowhere to send and names the two commands that give them somewhere. An
info line does not fail the run.
$ shc doctor run --category notification[info] notification.operator_provider info: the shipped notification rules backup-failed, backup-fire-dropped, backup-unprotected have nowhere to send, notification.providers.operator is not defined, so a failed, skipped or cancelled backup notifies nobody shc config set notification.providers.operator.type webhook, then shc config set notification.providers.operator.url <the receiver's URL>✔ ran 1 diagnosis, 0 passed, 1 infoThis page left the cluster as it found it: placed is unprotected again and
the notification rows you wrote are removed.
Next: Logs.