Bridging a System-Level systemd Target to the User Instance

Source: Dev.to

Overview

When using systemd, many services depend on network-online.target to ensure the network is fully up before they start.
network-online.target exists at the system level, but modern workflows often run long‑lived services in the user systemd instance (e.g., user‑managed daemons, development tools, per‑user agents).

The bridge described here triggers a marker target inside a specific user’s systemd instance as soon as the system reaches “network online,” allowing user services to depend on network-online.target reliably at boot.

Components

1. Installation script (install.sh) – sets up the required system and user units.
2. User‑level marker unit (network-online.target) – represents “network online” inside the user instance.
3. System‑level templated service (user‑network‑online@.service) – waits for the system’s network to be online and then starts the user‑level target for a given UID.

Together, these ensure that user services can declare dependencies on network-online.target even though the actual network‑readiness signal originates at the system level.

Handling User Systemd Lifecycles

By default, a user’s systemd instance is tied to an interactive login; if the user is not logged in, the instance may not exist, preventing user services from starting at boot.

The installation script enables linger:

loginctl enable-linger $USER

With linger enabled, the user’s systemd instance can run even when no session is active, which is a prerequisite for starting user services during the boot process.

User‑Level Marker Unit

Place the following file in ~/.config/systemd/user/network-online.target:

[Unit]
Description=User-level Network is Online (marker only)
Documentation=man:systemd.special(7)

This unit is intentionally simple—it does not perform any networking checks. Its sole purpose is to provide a synchronization point so that user services can declare:

After=network-online.target
Wants=network-online.target

System‑Level Service Template

Create /etc/systemd/system/user-network-online@.service with the following content:

[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

• The service runs after the system’s network-online.target, ensuring it triggers only once the system considers networking ready.
• It executes a one‑shot command that starts the user‑level network-online.target.
• Setting XDG_RUNTIME_DIR points systemctl --user at the correct runtime directory for the target user instance.

Installation Script

#!/bin/sh

# Enable linger for the current user
loginctl enable-linger $USER

# Install the system unit
sudo cp -t /etc/systemd/system/ user-network-online@.service
sudo systemctl daemon-reload

# Install the user target
USER_SYSTEMD_PATH="$HOME/.config/systemd/user"
mkdir -p "$USER_SYSTEMD_PATH"
cp -t "$USER_SYSTEMD_PATH" network-online.target
systemctl --user daemon-reload

# Enable and start the templated service for the current UID
sudo systemctl enable --now user-network-online@$(id -u).service

The script performs the following actions:

1. Enables linger for the current user.
2. Copies the system unit to /etc/systemd/system/ and reloads the system daemon.
3. Installs the user target into ~/.config/systemd/user/ and reloads the user daemon.
4. Enables and starts user-network-online@.service. Because the unit has WantedBy=multi-user.target, it runs automatically during the normal boot sequence. As soon as the system reaches network-online.target, it triggers the user’s network-online.target, allowing dependent user services to start in an orderly, dependency‑driven way.

Resulting Workflow

1. System decides when networking is “online.”
2. The system‑level service (user-network-online@.service) starts the user‑level marker (network-online.target).
3. User services that declare After=network-online.target (or Wants=network-online.target) can safely start, knowing the network is ready.
4. Everything runs automatically at boot, even if the user is not logged in, thanks to linger.

This lightweight pattern aligns with systemd’s dependency model and provides a solid foundation for user‑managed background services that must wait for reliable network availability.