Linux Services with systemd

Pathrule3 Rules • 2 Memories • 1 Skill

A long-running process needs an operating-system contract for identity, environment, startup ordering, readiness, shutdown, restart, resource limits, filesystem access, logging, and recovery after host reboot. This pattern constrains service identity, restart behavior, and secret loading; it records dependency and logging ownership and provides a unit verification and rollout procedure. It differs from Docker by focusing on host-native process supervision and cgroup policy rather than image construction and container orchestration.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

verify-systemd-service

deploy/

systemd/

Run one foreground process under a dedicated identity

Make restart policy classify failure

Load secrets without exposing them in unit text or process arguments

Startup ordering is not dependency readiness

ops/

runbooks/

journald is the structured service event stream

Rules

Run one foreground process under a dedicated identity/deploy/systemdhighstrictLet systemd own process lifecycle and grant the service only the user, groups, paths, capabilities, and devices it needs.

1	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.
2
3	- Start the application in foreground mode and choose the service type that matches its actual readiness and notification behavior.
4	- Create a dedicated non-login user and group and grant ownership only to required state, cache, log, socket, and configuration paths.
5	- Use filesystem, capability, syscall, namespace, and device hardening from measured needs, then verify startup and runtime under the restrictions.
6	- Set an explicit working directory and executable path; do not depend on an interactive shell profile or caller's current directory.
7
8	See /src for the adjacent decision or procedure that completes this constraint.

Make restart policy classify failure/deploy/systemdhighstrictRestart transient crashes with bounded delay while allowing invalid configuration and deliberate stops to remain visible.

1	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.
2
3	- Choose restart conditions that match the application and exclude clean deliberate shutdown and known permanent configuration exits.
4	- Add a delay and start-rate limit so repeated failure enters a visible failed state instead of a hot loop.
5	- Validate configuration in a pre-start step or separate command and fail before replacing the healthy process where deployment permits it.
6	- Alert on restart count, failed state, and time since last successful readiness rather than treating process presence as service health.
7
8	See /ops/runbooks for the adjacent decision or procedure that completes this constraint.

Load secrets without exposing them in unit text or process arguments/deploy/systemdhighstrictReference protected credential or environment sources and keep secret values out of repositories, status output, and command lines.

1	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.
2
3	- Use the platform's credential mechanism or a root-managed protected file with narrow service access for secret material.
4	- Pass secret file descriptors or paths where supported instead of values in command-line flags.
5	- Keep non-secret configuration separate from credentials so ordinary unit review and version control remain safe.
6	- Rotate credentials through a staged reload or restart procedure and verify old material is no longer readable by the service.
7
8	See /src for the adjacent decision or procedure that completes this constraint.

Memories

Startup ordering is not dependency readiness/deploy/systemdUse unit relationships for lifecycle ordering and make the application retry or fail clearly when remote dependencies are not ready.

1	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.
2
3	- Declare hard local dependencies only when the service cannot operate at all without their unit lifecycle.
4	- Let the application use bounded retry and backoff for remote services and expose a readiness signal that reflects its own usable state.
5	- Avoid using a broad network-online target as a substitute for robust reconnect behavior; networks can disappear after startup too.
6	- Design service startup to tolerate host reboot ordering and dependency restarts without requiring manual unit sequencing.
7
8	See /src for the rule or workflow that puts this decision into practice.

journald is the structured service event stream/ops/runbooksWrite process logs to standard streams with stable fields and let the supervisor attach unit, process, boot, and host identity.

1	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.
2
3	- Emit one structured event per line with level, event name, correlation identity, and bounded fields while excluding secrets and unnecessary personal data.
4	- Use journald fields and unit filters to separate services, boots, priorities, and time windows during diagnosis.
5	- Set retention and forwarding from host capacity and compliance requirements instead of relying on unlimited local disk.
6	- Keep start, readiness, signal, shutdown, dependency, and fatal configuration events explicit so service lifecycle is reconstructable.
7
8	See /deploy/systemd for the rule or workflow that puts this decision into practice.

Skills

verify-systemd-service/rootValidate unit syntax, permissions, hardening, startup, failure, restart, shutdown, logging, and reboot behavior.

1	---
2	name: verify-systemd-service
3	description: Verify a new or changed systemd unit before broad host rollout.
4	---
5
6	# Verify Systemd Service
7
8	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.
9
10	1. Render and verify the unit and drop-ins, inspect dependency relationships and effective properties, and confirm referenced files and users exist.
11	2. Start under the dedicated identity with hardening enabled and exercise required filesystem, network, socket, device, and capability operations.
12	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.
13	4. Trigger clean exit, crash, invalid configuration, missing dependency, secret denial, and rate-limited restart and verify each final state.
14	5. Reboot a representative host and confirm ordering, recovery, logs, resource limits, health signals, and rollback to the prior unit or binary.
15
16	## Exit criteria
17
18	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.

Why this pattern

AI agents often daemonize under systemd, run as root, depend on network-online as a substitute for retry logic, or create restart loops that hide permanent configuration failure.

Built for Infrastructure teams operating host-native application processes, workers, gateways, or internal agents.

Keeps your assistant from:

Granting a service unnecessary root and filesystem access
Forking away from the supervisor and losing process identity
Restarting a permanently invalid configuration forever
Killing work without honoring the application's shutdown contract

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25