# Pathrule Pattern: Linux Services with systemd (1.0.0) # ::pathrule:package:linux-systemd-services ### [RULE] Run one foreground process under a dedicated identity (path: /deploy/systemd) A supervised service should not fork into the background or write a PID file unless its protocol requires that legacy model. Running as root turns any application defect into host-wide authority. - Start the application in foreground mode and choose the service type that matches its actual readiness and notification behavior. - Create a dedicated non-login user and group and grant ownership only to required state, cache, log, socket, and configuration paths. - Use filesystem, capability, syscall, namespace, and device hardening from measured needs, then verify startup and runtime under the restrictions. - Set an explicit working directory and executable path; do not depend on an interactive shell profile or caller's current directory. See /src for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Make restart policy classify failure (path: /deploy/systemd) An unconditional rapid restart can consume CPU, flood logs, and hide a permanent error behind an apparently active unit. The policy should distinguish recoverable process loss from operator action and bad configuration. - Choose restart conditions that match the application and exclude clean deliberate shutdown and known permanent configuration exits. - Add a delay and start-rate limit so repeated failure enters a visible failed state instead of a hot loop. - Validate configuration in a pre-start step or separate command and fail before replacing the healthy process where deployment permits it. - Alert on restart count, failed state, and time since last successful readiness rather than treating process presence as service health. See /ops/runbooks for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Load secrets without exposing them in unit text or process arguments (path: /deploy/systemd) Unit files are commonly readable and process arguments are observable. Embedding credentials directly in ExecStart or committed environment directives broadens access and leaks them into diagnostics. - Use the platform's credential mechanism or a root-managed protected file with narrow service access for secret material. - Pass secret file descriptors or paths where supported instead of values in command-line flags. - Keep non-secret configuration separate from credentials so ordinary unit review and version control remain safe. - Rotate credentials through a staged reload or restart procedure and verify old material is no longer readable by the service. See /src for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] Startup ordering is not dependency readiness (path: /deploy/systemd) After and Wants describe unit activation relationships, while network or another service being started does not prove its DNS, port, schema, leader, or data is ready for this application. - Declare hard local dependencies only when the service cannot operate at all without their unit lifecycle. - Let the application use bounded retry and backoff for remote services and expose a readiness signal that reflects its own usable state. - Avoid using a broad network-online target as a substitute for robust reconnect behavior; networks can disappear after startup too. - Design service startup to tolerate host reboot ordering and dependency restarts without requiring manual unit sequencing. See /src for the rule or workflow that puts this decision into practice. --- ### [MEMORY] journald is the structured service event stream (path: /ops/runbooks) Writing ad hoc log files from the service duplicates rotation and permission concerns and loses supervisor metadata. Standard streams keep lifecycle and application evidence queryable together. - Emit one structured event per line with level, event name, correlation identity, and bounded fields while excluding secrets and unnecessary personal data. - Use journald fields and unit filters to separate services, boots, priorities, and time windows during diagnosis. - Set retention and forwarding from host capacity and compliance requirements instead of relying on unlimited local disk. - Keep start, readiness, signal, shutdown, dependency, and fatal configuration events explicit so service lifecycle is reconstructable. See /deploy/systemd for the rule or workflow that puts this decision into practice. --- ### [SKILL] verify-systemd-service (path: /) --- name: verify-systemd-service description: Verify a new or changed systemd unit before broad host rollout. --- # Verify Systemd Service Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. 1. Render and verify the unit and drop-ins, inspect dependency relationships and effective properties, and confirm referenced files and users exist. 2. Start under the dedicated identity with hardening enabled and exercise required filesystem, network, socket, device, and capability operations. 3. Send the configured stop signal during active work and prove readiness drops, intake stops, work drains, and the timeout produces an observable forced path. 4. Trigger clean exit, crash, invalid configuration, missing dependency, secret denial, and rate-limited restart and verify each final state. 5. Reboot a representative host and confirm ordering, recovery, logs, resource limits, health signals, and rollback to the prior unit or binary. ## Exit criteria The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.