Bridging a System-Level systemd Target to the User Instance

Overview of the Approach

Systemd commonly relies on network-online.target before starting services, but this target operates at the system level while modern workflows often utilize user systemd instances for long-lived services. This solution bridges the gap, triggering a user-level target when the system reaches network online status.

The architecture comprises an installation script, a user-level marker target, and a system-level templated service facilitating reliable automation at boot. This prevents inconsistent state where user services attempt to start before the network is available, leading to failures and requiring manual intervention.

Why This Matters

Traditionally, user systemd instances required an active login to function, hindering automated startup of user-managed services. This approach resolves this limitation with loginctl enable-linger, enabling user services to start at boot with proper network dependencies, avoiding common errors and increased operational overhead. Without this, developers risk unstable services or complex workarounds more prone to failure.

Key Insights

• loginctl enable-linger $USER: Enables user systemd instances even without an active login session.
• Systemd targets act as synchronization points: network-online.target ensures dependencies are met before service startup.
• Templated services ([email protected]) dynamically generate units based on user ID (UID), optimizing resource utilization and configuration.

Working Example

[Unit]
Description=Trigger user-level network-online.target for %i
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
User=%i
Environment=XDG_RUNTIME_DIR=/run/user/%i
ExecStart=/usr/bin/systemctl --user start network-online.target
[Install]
WantedBy=multi-user.target

Practical Applications

• Company/system: Stripe utilizing per-user agents needing network access before initialization.
• Pitfall: Directly depending on network availability within a user service leads to race conditions and intermittent failures.

References:

• https://dev.to/vast-cow/bridging-a-system-level-systemd-target-to-the-user-instance-1601