Units and Targets

## The shape of a unit file A unit file is an INI-style text file: `[Section]` headers, `Key=Value` lines, `#` or `;` comments, and a trailing backslash to continue a long line. A minimal service looks like this: ```ini [Unit] Description=Example API server After=network-online.target [Service] ExecStart=/usr/local/bin/apid --config /etc/apid.toml User=apid [Install] WantedBy=multi-user.target ``` Three sections, three different jobs, three different readers. ## [Unit] — who this unit is and how it relates to others `[Unit]` is generic: every unit type may have one. It carries the human-facing metadata — `Description=`, which is the text `systemctl status` prints, and `Documentation=`, which holds man-page or URL references — and the keys that express relationships to other units, such as `After=` for ordering and `Wants=` for a dependency. `ConditionPathExists=` and its siblings also live here: they let a unit skip cleanly instead of failing when a precondition is absent. One rule catches people out: `Description=` is free text used only for display, so it does not need quoting, and putting a value there has no effect on anything systemd does. It is nonetheless worth writing, because on an unfamiliar host `systemctl status` output is the first thing anyone reads. ## [Service] — how the process runs `[Service]` is the type-specific section, valid only in a `.service` unit. It answers "what do I execute and under what conditions": - `ExecStart=` — the command line. It is not a shell command: systemd executes it directly, so the binary must be an absolute path and shell features like pipes, globs and variable expansion do not apply unless you deliberately invoke a shell. - `Type=` — how systemd decides startup is complete (`simple`, `exec`, `forking`, `oneshot`, `notify`, `dbus`, `idle`). - `User=`, `Group=` — the identity the process runs as. - `WorkingDirectory=`, `Environment=`, `EnvironmentFile=` — the process's environment. - The sandboxing and resource keys — `ProtectSystem=`, `PrivateTmp=`, `MemoryMax=` and so on. Because `ExecStart=` is not run through a shell, `ExecStart=/usr/bin/foo > /var/log/foo.log` does not redirect anything; the `>` is passed to `foo` as an argument. Output handling belongs to `StandardOutput=`/`StandardError=` instead. ## [Install] — read only by enable and disable `[Install]` is the section the running manager never consults. `systemctl enable` reads it to work out which symlinks to create, and `systemctl disable` reads it to work out which to remove. `WantedBy=` is the usual content. A unit with no `[Install]` section runs perfectly well when started by hand or pulled in by another unit; it simply cannot be enabled. ## What happens when a key is in the wrong section The parser knows which keys belong to which section, and it does not move them for you. Writing `ExecStart=` under `[Unit]` produces a log line to the effect that the key name is unknown in that section and is being ignored — and then the unit fails to load, because a service unit with no `ExecStart=` has nothing to run and systemd refuses it. A misspelling behaves identically: `ExecStrat=` is simply an unknown key, silently dropped apart from that warning. That failure mode — a warning in the journal rather than a hard parse error — is why misplaced keys survive review. Two habits catch them: ``` systemd-analyze verify /etc/systemd/system/apid.service systemctl show -p ExecStart -p User apid.service ``` `systemd-analyze verify` loads the unit the way the manager would and reports unknown keys and unresolvable dependencies without touching the running system. `systemctl show -p` prints the value systemd actually resolved for a property, which is how you prove a setting took effect rather than assuming it did. ## Section names are case-sensitive `[service]` is not `[Service]`, and `execstart=` is not `ExecStart=`. Section and key names are matched case-sensitively; values generally are not (booleans accept `yes`/`true`/`1`). This trips people who copy a unit out of a blog post that lost its capitalisation.