Zero‑Config Fedora Microservice with Systemd Socket Activation

Problem & Takeaway

You need a lightweight microservice on Fedora that starts with the first client connection, runs as an unprivileged user, and is tightly sandboxed. Systemd socket activation provides zero‑config startup, while SELinux enforces that only the intended service can use the socket. The key takeaway is: a single unit file with a [Socket] and [Service] section, coupled with SELinux type enforcement, gives you a secure, self‑starting service with clear operational checks.

Requirements

• Fedora 39 (or newer) with systemd 253+ and SELinux in enforcing mode.
• Service binary listening on a TCP port (e.g., 8080).
• Unprivileged service user (e.g., myapp).
• SELinux policy that allows the service to bind to the socket and accept connections.
• Optional health‑check script that curls localhost:8080.

Minimal Design

The simplest viable architecture is a single unit file that defines both the socket and the service. Systemd creates the listening socket, then starts the service on the first connection.

# /etc/systemd/system/myapp.service
[Unit]
Description=MyApp Zero‑Config Service
After=network.target

[Socket]
ListenStream=8080
SocketUser=myapp
SocketGroup=myapp
SocketMode=0660

[Service]
ExecStart=/usr/local/bin/myapp --port 8080
User=myapp
Group=myapp
Restart=on-failure
Environment=MYAPP_CONFIG=/etc/myapp/config.yml
PassEnvironment=MYAPP_CONFIG
PrivateTmp=yes
ProtectSystem=full
ProtectHome=yes
SELinuxContext=system_u:object_r:myapp_t:s0

[Install]
WantedBy=multi-user.target

Key points:

• ListenStream=8080 creates a TCP socket bound to port 8080.
• The socket is owned by myapp and has 0660 permissions, preventing other users from binding.
• When a client connects, systemd spawns myapp and passes the socket via FD 3.
• SELinux context myapp_t must be defined in the policy to allow the service to use the socket.

Trust & Data Boundaries

Trust boundaries are enforced at two layers:

1. Socket ownership: Only the myapp user can bind to the port. Systemd sets the socket’s UID/GID and mode before the service starts.
2. SELinux policy: The type myapp_t restricts file and socket access. No other process with a different type can read/write the socket file or accept connections.

Because the socket file is created in /run/systemd/sockets/ and owned by the service, the risk of accidental exposure is minimal.

Operational Checks

Use the following commands to verify the service is healthy:

# Check unit status and recent logs
sudo systemctl status myapp.service
sudo journalctl -u myapp.service --since=10m

# Verify socket listening state
sudo ss -ltnp | grep 8080

# Quick health check via curl (if health script is configured)
sudo curl -s http://localhost:8080/health

Expected results:

• systemctl status shows Active: active (running) and the process ID.
• ss lists LISTEN on 0.0.0.0:8080 with the service UID.
• Health endpoint returns JSON or a 200 OK.

Failure Modes & Conditions That Change the Design

• SELinux block: If the policy does not allow myapp_t to bind or accept connections, systemd will log a permission error and the unit will exit. Fix by adding the appropriate allow rules or adjusting the type.
• Missing socket file: If the socket unit is removed or corrupted, systemd will retry until the file is present. The service will never start, and logs will show a Failed to open listening socket error.
• Port conflict: If another service already uses port 8080, systemd will fail to create the socket. Check with ss -ltnp | grep 8080 before enabling the unit.
• SELinux policy changes in newer Fedora releases: New default booleans may alter the required type enforcement. Verify by temporarily setting setenforce 0 and observing that the service starts; then re‑enable enforcing mode to catch policy violations.

Practical Verification Workflow

1. Create the unit file as shown above and reload systemd: sudo systemctl daemon-reload.
2. Enable and start: sudo systemctl enable --now myapp.service.
3. Run the operational checks from the previous section.
4. Simulate a failure: Rename the socket file (sudo mv /run/systemd/sockets/myapp.socket /run/systemd/sockets/myapp.socket.bak) and restart the unit. Observe systemd retry and journal logs for Failed to open listening socket.
5. Test SELinux enforcement: Temporarily set permissive mode (sudo setenforce 0), restart the unit, and confirm it starts. Re‑enable enforcing mode and verify that the service fails if the policy is incomplete.

Limitations & Caveats

• Socket activation only supports TCP and Unix domain sockets; UDP activation is not supported.
• The service must explicitly use the passed socket (FD 3). If it ignores it and opens its own listening socket, the design loses its zero‑config advantage.
• SELinux policy updates in future Fedora releases may require re‑examining the type enforcement for the socket and service.
• Health checks that rely on external endpoints (e.g., upstream services) are not covered by this design and should be added as separate systemd timers or watchdog units.

Conclusion

By bundling socket activation, unprivileged execution, and SELinux confinement into a single unit file, you achieve a minimal, secure, and easily auditable microservice on Fedora. Operational checks are straightforward, and failure modes are well documented, making this pattern ideal for production deployments where zero‑config startup and strong isolation are paramount.