Appendix 4.B Wire Vocabulary

4 min read

Every enumerated value that appears on the control channel. All are lower snake case. Except for status warning types and granted rights, these sets are closed: a manager MUST NOT emit a value outside them without the version negotiation in §4.21, and a client MUST treat one it does not recognise as an error for that request rather than mapping it onto a value it knows. The open sets state their handling rules below.

These sets are the control channel's. The same words appear in the manager's structured events in kebab-case, as every event value is (PGSS §6.5): explicit_start on the channel is explicit-start in an event.

4.B.1 Response status #

ok, error

4.B.2 Service state #

Exactly four states satisfy dependents: active, reloading, completed and skipped. A client deciding whether something depending on this service could be running MUST use that set and no other.

4.B.3 Transition cause #

explicit_start, dependency_start, restart_policy, binds_to_recovery, timer, explicit_stop, explicit_reload, explicit_reset, conflict_eviction, binds_to_propagation, shutdown_wave, process_crash, clean_exit, clean_exit_restart, readiness_timeout, watchdog_timeout, health_check_failure, pre_hook_failure, parent_setup_failure, pre_exec_failure, dependency_failure, restart_budget_exhausted, cycle_detected, validation_error, assertion_error, condition_skipped, tty_unavailable, process_unkillable, internal_error

A cause may also be null, for a service that has not transitioned.

4.B.4 Service health #

healthy, unhealthy, unknown

health is null when the service has no health check configured, which is distinct from unknown — the latter means one is configured and has not produced a result yet.

4.B.5 Job type #

service_main, pre_exec_hook, post_exec_hook, reload_hook, health_check, submitted

Only service_main appears in current_job. Only submitted appears in a job view (§7.7); a job's state and cause vocabularies are §7.B's.

4.B.6 Operation type #

start, stop, restart, reload, reset

4.B.7 Operation state #

4.B.8 Operation source #

admin, boot, shutdown, dependency_propagation, restart_policy, timer, binds_to_recovery, binds_to_propagation, conflict_resolution, on_failure, tty_release

admin is the only source a client's own command produces. The rest describe operations the manager created for its own reasons, and a client observing one has learned something about what the manager is doing rather than about anything it asked for.

4.B.9 Reload mode #

confirmed, advisory, failed

4.B.10 Status warning type #

service_tree, health, hooks, helper

These name what part of a service's process containment could not be reclaimed, service_tree being the whole of it and therefore the most serious. A client MUST accept a value outside this set and MUST NOT discard the warning (§4.21).

4.B.11 Granted right #

In a status's granted: query_status, start, stop, interrogate

In a job view's granted, on this channel: query, stop, signal

Each names a right of §4.7 or §7.8, lowercased and without its SERVICE_ or JOB_ prefix, and they appear in the order given here (§4.14). A client MUST ignore a name outside these sets rather than treat it as an error: an unrecognised right is one it has no command for, and the rights it does know are still correctly reported.

4.B.12 Shutdown type #

poweroff, reboot, halt

Request-only; the manager does not echo it.

4.B.13 Boot mode #

full, safe, recovery

The modes §4.15 defines. Only boot returns one, and a manager in recovery does not serve this channel, so in practice a client reads full or safe.

4.B.14 Boot mode reason #

Edit this page