A .NET 10 worker runs as a systemd unit with Type=notify; what does AddSystemd change, and what goes wrong if the call is missing?
answer
- readiness is a message, not a fork
- NOTIFY_SOCKET and READY=1
- SystemdLifetime replaces ConsoleLifetime
- journal priority prefix on log lines
- WorkingDirectory decides the content root
basics
~20 sAddSystemd swaps in SystemdLifetime, which sends READY=1 over systemd's NOTIFY_SOCKET once the host has started and STOPPING=1 when it stops, and switches console logs to the systemd formatter. Without it a Type=notify unit never hears READY=1 and its start times out.
solid answer
~40 s`AddSystemd()` (package `Microsoft.Extensions.Hosting.Systemd`) acts only when the process runs under systemd: its parent is `systemd`, or it is PID 1 with `NOTIFY_SOCKET` or `LISTEN_PID` set. It then registers `SystemdNotifier` and `SystemdLifetime` as `IHostLifetime`, and sets the console logger's formatter to `systemd`. `SystemdLifetime` sends `READY=1` to the socket named by `NOTIFY_SOCKET` when the host raises `ApplicationStarted`, after every hosted service's `StartAsync` has completed, and `STOPPING=1` when it raises `ApplicationStopping`. With `Type=notify`, systemd keeps the unit in the activating state until `READY=1` arrives, so units ordered after it wait for real readiness. Leave the call out and `ConsoleLifetime` never sends that message: the start job hangs until the unit's start timeout and the unit is marked failed. Logs also lose their syslog priority prefix, so journald files every line at its default priority.
code
ini · 13 lines[Unit]
Description=Queue consumer
[Service]
Type=notify
ExecStart=/opt/queue-consumer/QueueConsumer
WorkingDirectory=/opt/queue-consumer
Environment=DOTNET_ENVIRONMENT=Production
User=queueconsumer
Restart=on-failure
[Install]
WantedBy=multi-user.targetgo deeper
Know that a .NET worker becomes a systemd service through the Microsoft.Extensions.Hosting.Systemd package and AddSystemd(), with a unit file that starts it.
Explain what SystemdLifetime sends and when, how the systemd formatter prefixes priorities, and that the call is a no-op outside systemd.
Diagnose a unit stuck activating or a worker with no configuration: missing AddSystemd with Type=notify, or a working directory that moved the content root.
Standardise one service definition per platform, Type=notify with AddSystemd and an explicit working directory, so every worker reports readiness the same way.
## What `Type=notify` asks for A systemd service unit declares how systemd should decide the service has **started**. With `Type=simple`, the service counts as started as soon as the process is launched. With `Type=notify`, systemd hands the process a datagram socket path in the `NOTIFY_SOCKET` environment variable and keeps the unit **activating** until the process sends `READY=1` on it. Units ordered after the worker, and `systemctl start` itself, wait for that message. If it never arrives within the unit's start timeout (`TimeoutStartSec=`), systemd fails the start and stops the process. A .NET worker does not speak that protocol on its own. The default `ConsoleLifetime` handles signals and logs status lines, but sends nothing to systemd. ## What `AddSystemd()` registers The call comes from the `Microsoft.Extensions.Hosting.Systemd` package and is written `builder.Services.AddSystemd()` (or `UseSystemd()` on an `IHostBuilder`). When active, it: - registers **`SystemdNotifier`** as `ISystemdNotifier`; it reads `NOTIFY_SOCKET` and is a no-op when the variable is absent; - registers **`SystemdLifetime`** as `IHostLifetime`, replacing `ConsoleLifetime`; - sets `ConsoleLoggerOptions.FormatterName` to **`systemd`** (`ConsoleFormatterNames.Systemd`). `SystemdLifetime` then: 1. on `ApplicationStarted`, logs one line with the environment and content root and sends **`READY=1`**; 2. on `ApplicationStopping`, logs "Application is shutting down..." and sends **`STOPPING=1`**; 3. listens for **SIGTERM** only, because that is the signal systemd sends to stop a service. What happens during the stop itself is covered with application lifetime and shutdown. `ApplicationStarted` is raised after every hosted service's `StartAsync` (and any `StartingAsync`/`StartedAsync`) has completed, so readiness means "the host finished starting", not "the queue consumer has processed a message". Work that must finish before dependents start belongs in a hosted service's start-up path, not in its long-running loop. ## When it activates `SystemdHelpers.IsSystemdService()` decides once per process: 1. On any non-Unix OS, it returns `false`. 2. If the process is **PID 1** (a container with systemd-style activation), it returns `true` when `NOTIFY_SOCKET` or `LISTEN_PID` is set. 3. Otherwise it reads `/proc/<parent pid>/comm` and returns `true` only when the parent is `systemd`. Under `dotnet run`, in a terminal, or on Windows, the call does nothing, so it is safe to call unconditionally next to `AddWindowsService()` in a worker that one customer runs as a Windows Service and another as a systemd unit. ## How the combinations behave | Unit type | `AddSystemd()` | Result | |---|---|---| | `Type=notify` | present | unit becomes active after `READY=1`; journal lines carry priorities | | `Type=notify` | missing | no `READY=1`; start hangs, then fails at the start timeout | | `Type=simple` | present | systemd passes no `NOTIFY_SOCKET`, so the notifier stays silent; the unit is active as soon as the process starts | | `Type=simple` | missing | works, but dependents may start before the worker is ready | ## Journal-friendly logging The `systemd` console formatter writes each entry on **one line**, without colours, prefixed with the syslog priority: `<6>` for information, `<4>` for warning, `<3>` for error. journald reads that prefix and stores the entry at that priority, so `journalctl -p warning` filters correctly. The default simple formatter writes each entry over two lines with no priority prefix, so journald records them line by line at the unit's default priority. ## The working-directory trap On Linux the generic host takes the **current directory** as the content root unconditionally; the fallback to `AppContext.BaseDirectory` exists only on Windows. A system unit without `WorkingDirectory=` is not started in the app folder, so the content root points elsewhere and `appsettings.json`, being optional, silently loads nothing. Set `WorkingDirectory=` to the install folder, pass `--contentRoot` in `ExecStart=`, or set `HostApplicationBuilderSettings.ContentRootPath` in code. ## Checking it on a server - `systemctl status <unit>` showing **activating (start)** for a long time on a `Type=notify` unit means no `READY=1` has arrived: check that `AddSystemd()` is called and that its package is referenced. - The start-up line "Application started. Hosting environment: …; Content root path: …" in `journalctl -u <unit>` confirms both readiness and the content root in one place. - `journalctl -u <unit> -p warning` listing the worker's warnings and errors confirms the priority prefix is honoured; if logged errors are missing from that view, every line was stored at the default priority and the systemd formatter is not active. - After a deploy, compare the content root in that line with the install folder before suspecting configuration values.
- Does READY=1 wait for a BackgroundService's loop to finish its first iteration?No. `READY=1` is sent when the host raises `ApplicationStarted`, which happens after each hosted service's `StartAsync` returns. A `BackgroundService` returns from `StartAsync` without waiting for `ExecuteAsync` to finish, so anything that must be ready first, such as opening the queue connection, belongs in a start-up step rather than inside the loop.
- How does `HostOptions.ServicesStartConcurrently` affect when systemd sees the worker as ready?By default hosted services start one after another, so `ApplicationStarted`, and therefore `READY=1`, waits for the sum of their `StartAsync` times. Setting `ServicesStartConcurrently = true` (or the `servicesStartConcurrently` configuration key) starts them concurrently, so readiness arrives after the slowest one.
- Type=notify works with any .NET worker because the runtime notifies systemd itself.
- AddSystemd() must be wrapped in an OperatingSystem.IsLinux() check to run on Windows.
- READY=1 is sent as soon as the process starts, before hosted services start.
- The systemd formatter writes JSON that journald parses into fields.
- On Linux the host falls back to the executable's folder when started from /.