SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

How to fix systemd Type simple forking notify error

If your systemd unit show active but the daemon don die, you fit choose wrong Type. Learn how simple, forking, notify, and oneshot dey work so you fit track main PID.

Wetin make systemd report unit as active when process don die

With the default ExitType=main and RemainAfterExit=no, systemd service unit go remain active as long as the one process wey systemd call the main process dey alive, and Type= for the [Service] section decide which process be that. If you pick wrong value, systemd fit end up dey watch shell wrapper or short-lived parent while the daemon wey you care about don die inside the same unit. The unit dey tell you the truth about the process wey you instruct am to watch.

Changing restart policy no go solve this one. Restart= dey react to process exits and failures like timeouts, but e no fit detect when background daemon don exit while main PID (process identifier) belong to something wey still dey run. Fix Type= first. Wetin systemd go do after main process really exits na separate decision, and the guide to Restart= and RestartSec= cover am.

Wetin Type= really decide

Every Type= value dey answer two questions at once. When systemd fit consider this unit started, and which process be the main one.

The first answer dey control ordering. A unit wey name your own for After= go wait until systemd call your unit started. A Type= wey report say "started" too early fit make dependent units run before your service fit answer dem.

The second answer dey control supervision. systemd dey put every process wey unit spawn inside a cgroup (control group), na kernel feature wey group processes so dem fit limit and kill dem together. Na the cgroup systemctl stop dey use do cleanup: KillMode= default to control-group, so when system stop one unit, e dey send signal to every process inside am. The main PID get narrower meaning. With default ExitType=main and RemainAfterExit=no, na the one process wey e exit go end the unit, and whose exit status go contribute to the unit result. Confusion dey start when person read the cgroup as if na the main PID.

Type=simple report say e don start before the binary run

Type=simple na the default when ExecStart= dey set, neither Type= nor BusName= dey present, and the unit no dey use credentials. Unit wey load credentials, for example with LoadCredential=, get Type=exec implied instead. Under simple, systemd dey create the process, count the unit as started immediately, and treat that process as the main PID. Follow-up units go start immediately, before the service binary even execute.

Na this last detail dey explain one common surprise. Typo for the ExecStart= path still fit make the start job succeed, and the failure go show a moment later when execution fail. systemd dey record this case with exit code 203. Its own table call am EXIT_EXEC and define am as failure to execute the actual process. So, if systemctl start return without error, e no prove say your binary dey exist.

Use simple for program wey dey stay for foreground and never move itself go background. This one cover most modern daemons and almost anything wey you write yourself.

Type=exec dey wait make program really start

Type=exec na simple plus one extra step. systemd go count the unit as started only after both fork and execution of the binary don succeed. If binary dey miss or User= no fit resolve, the start job go fail directly instead of reporting success and failing quietly some moments later.

Type=exec enter upstream for systemd 240, but distribution backports make am available for older versions: RHEL 8 add am for systemd-239-15.el8. Some older releases wey dey supported still fit no get am: Ubuntu 18.04 remain under ESM until April 2028, and the systemd 237 manual for am no list exec as supported type. Ubuntu 24.04 ships systemd 255 and Debian 13 ships systemd 257, as of October 2026. Check your own with systemctl --version and the distribution's systemd.service manual.

The cost na one extra synchronisation step when e start. The benefit na honest exit status from systemctl start. For foreground program, prefer exec instead of simple.

Type=forking, and how the main PID dey get lost

Type=forking dey tell systemd say the process for ExecStart= go fork one child, then e go exit on purpose. systemd dey wait make that first process exit before e call the unit started. The child wey remain na the daemon. This practice come from SysV era, when nothing dey supervise daemon after init script return, and PID file na the only record of wetin dey run. This limitation dey near the centre of why systemd replace init scripts.

The problem na identity. The process wey systemd launch don comot, so systemd gats figure out which survivor na the main one. Set PIDFile= to the file wey daemon dey write, normally a path under /run, and systemd go read the PID from there. When unprivileged user own that file, systemd still checks say the PID inside am point to process wey already belong to this service. So, e go reject stale or planted file wey name unrelated process instead of trusting am.

Without PIDFile=, GuessMainPID= go apply, and e dey default to yes. This guess reliable only when the service settle as one process. The manual talk the limit clearly: the guess fit reach wrong conclusion if daemon get more than one process. If systemd no fit determine the main PID, failure detection and automatic restarting no go work reliably. Unit fit also end up with main PID of 0. This mean systemd no dey track any main process at all, even if daemon processes still dey run inside the unit cgroup.

Most daemons wey fork get switch wey keep dem for foreground. Use that switch with Type=exec and delete the PIDFile= line. Fewer moving parts mean fewer ways to lose the PID.

Type=oneshot for work wey go finish

Type=oneshot expect the process to run and exit. systemd dey call the unit started only after e don exit, so oneshot na the correct shape for anything wey another unit must wait for. E still be the implied default when unit no specify Type= or ExecStart=.

Two behaviours dey specific to oneshot. Na the only type wey fit accept more than one ExecStart= line, and dem lines dey run one after another. E start timeout dey disabled by default too, so oneshot wey hang go wait forever unless you set TimeoutStartSec= by yourself.

After the process exits, the unit go return to inactive. RemainAfterExit=yes dey keep am active even when no process dey run at all. Na the deliberate version of the symptom for the top of this page, and e correct when the unit job na to leave state behind instead of keeping something running: loading a firewall ruleset, or bringing up a container stack. Na the pattern behind Docker Compose stack wey come back after reboot, where the unit run the compose command, exit, and remain active because the containers wey e start outlive am. oneshot unit still fit handle work wey schedule trigger, wey na the other half of running a job with systemd timer instead of cron.

Type=notify service fit tell system when e don ready

Type=notify move the decision go the service. systemd go keep the start job open until the process send READY=1 through a Unix socket wey path dey inside the NOTIFY_SOCKET environment variable. The C interface na sd_notify(3), and many servers already support am.

This na the correct answer to the question "e don start?". simple and exec report say service don start before e read configuration or open the listening socket, so dependent unit fit start too early and fail the first connection. notify report say e don start for the exact time wey the service itself say e ready.

systemd dey accept that message only from the main process, na wetin NotifyAccess=main mean, and Type=notify imply am. If na child or helper send the message, set NotifyAccess=all. Shell script fit call systemd-notify --ready. When e get the needed privileges, systemd-notify go send the message with the PID of its parent, so if the script na the main process by itself, e go pass NotifyAccess=main; otherwise e go use its own PID, and the unit need NotifyAccess=all. By default, e dey wait until systemd process the message before e exit, so leave out --no-block, wey dey turn off that wait. Service wey speak the protocol by itself dey more reliable.

Two related settings dey worth knowing. Type=notify-reload, wey dey available since systemd 253, extend the same handshake to reloads, so systemctl reload go return when service report say reload don finish, instead of returning when signal don send. Since systemd 262, released for September 2026, notify-reload service wey send READY=1 without catching or blocking its reload signal (SIGHUP unless ReloadSignal= talk otherwise) go fail to start with protocol error, instead of that signal killing am during its first reload. WatchdogSec= ask notifying service to send keep-alive message for a fixed interval, and systemd dey treat missed deadline as failure.

Type=dbus and Type=idle

Type=dbus dey wait until the service take name for D-Bus, di message bus wey system and desktop services dey use talk to each other. E require BusName=, and e go become di default as soon as BusName= dey set. Use am only for service wey truly register bus name.

Type=idle dey behave like simple, but e dey delay di program until dem don dispatch queued jobs, with five seconds limit. E dey exist so console output for boot no go mix with status messages. E no be ordering tool, and e no suppose dey for normal service.

Why wrapper script dey make systemd track wrong PID

Dis na di pattern wey dey cause di wahala.

[Service]
Type=simple
ExecStart=/opt/app/run.sh
#!/bin/bash
export APP_ENV=production
/opt/app/bin/server --config /etc/app.yaml &
/opt/app/bin/exporter --port 9101

systemd dey record di shell as di main PID. Di shell go still dey run while exporter dey work for foreground. If server die, di shell no go know, so di main PID go still dey active, di unit go still show as active, and Restart= no go get anytin to do. Both processes go still dey inside di unit cgroup, so systemctl stop go still fit clean up well. Na supervision break, no be cleanup.

Di way to fix am depend on how many long-running processes di unit get.

If na only one, replace di shell wit am.

#!/bin/bash
export APP_ENV=production
exec /opt/app/bin/server --config /etc/app.yaml

exec go replace di shell wit di program wey you name and e go keep di same PID, so di PID wey systemd record go now belong to di daemon. Better still, comot di wrapper. Environment= and EnvironmentFile= fit carry di variables, and ExecStartPre= fit handle di setup step, so systemd fit launch di daemon directly and know di PID from di start.

If dem be two, no single PID fit represent di unit. Split dem into two units and arrange dem wit After= and Wants=. One unit per process na di arrangement wey systemd sabi supervise well, and na only dat way each process go fit get im own restart behaviour.

Wetin ExitType=cgroup change

ExitType= enter systemd 250. The default na main: system dey see the unit as stopped when the main process comot. With ExitType=cgroup, system dey see the unit as still running as long as any process for its cgroup dey alive.

[Service]
Type=simple
ExitType=cgroup
ExecStart=/opt/app/launcher

This dey solve one specific problem. Launcher wey start the real work and then comot go make systemd see the unit as stopped under ExitType=main, then kill the processes wey remain. With ExitType=cgroup, the unit dey follow the whole group instead.

Make you understand wetin e no solve. ExitType=cgroup keep unit active as long as at least one process dey alive, so unit wey dey hold two daemons go remain active after one of dem die. E fix the launcher case. E no turn one unit into supervisor for several independent processes. You no fit combine ExitType=cgroup with Type=oneshot too.

The cgroup na where resource accounting dey happen too, so limits like MemoryMax= and CPUQuota= apply to every process wey the unit spawn, no matter wetin Type= talk about the main PID. That part dey explained for how to limit service memory and CPU with systemd.

How to find the process wey systemd dey actually watch

Follow these steps for the unit wey you dey debug, in order. Read the unit files first, then read wetin systemd dey track, then compare am with the process table.

systemctl cat app.service
systemctl show -p Type,ExitType,GuessMainPID,PIDFile,MainPID,RemainAfterExit app.service

systemctl cat dey print the unit file together with every drop-in wey apply to am from disk; these fit different from wetin systemd load if files change without daemon-reload. systemctl show dey print the effective values, including defaults wey you never write down. Note the value of MainPID before you continue.

systemd-cgls --unit=app.service
ps -o pid,ppid,stat,etime,args -p "$(systemctl show -p MainPID --value app.service)"

systemd-cgls dey list every process for the unit cgroup. The ps line dey describe the one process wey systemd dey supervise. Read both together. MainPID of 0 mean say systemd no dey track any main process, even if systemd-cgls still dey list processes for the unit cgroup. MainPID wey resolve to a shell while the cgroup still hold your daemon na the wrapper case wey we mention before. If cgroup get more processes than you expect, launcher or forking daemon dey involved.

systemctl status app.service
journalctl -u app.service -b

systemctl status dey print the state line and cgroup tree together, so e often answer both questions at once. journalctl -u limited to this boot with -b dey show the start and stop events wey systemd record for the unit, together with the exit codes wey e see. If daemon dey write to im own log file instead of the journal, read that file too, because systemd fit only record wetin reach am.

When you change Type=, reload and restart.

systemd-analyze verify /etc/systemd/system/app.service
sudo systemctl daemon-reload
sudo systemctl restart app.service

systemd-analyze verify dey parse the file and report settings wey e no fit accept. daemon-reload make systemd read unit files from disk again. A changed Type= no go apply to unit wey already dey run, so restart dey required; e no be optional.

Then test the change. Take the PID of the process wey you actually care about from systemd-cgls and kill am. Run systemctl is-active app.service immediately after. With ExitType=main and RemainAfterExit=no, killing the main process go end that running instance, although restart policy fit bring am back before you check. If e remain active without restarting, check whether systemd dey watch another thing or the unit dey use ExitType=cgroup or RemainAfterExit=yes.

Which systemd service Type= you suppose use

  • Program wey dey stay for foreground: Type=exec.
  • Program wey support readiness notification: Type=notify, and notify-reload if e dey confirm reloads too.
  • Daemon wey insist say e go move enter background: Type=forking with PIDFile=, or use e foreground switch with Type=exec.
  • Script wey dey do work then exit: Type=oneshot, plus RemainAfterExit=yes when na to leave state behind be the aim.
  • Launcher wey dey exit while e children still dey run: Type=simple with ExitType=cgroup.

If you no sure which one third party daemon need, first read the unit file wey dem package. If you run systemctl cat on unit wey the distribution ship, e go show the packaged Type= choice together with local overrides.

FAQ

Why my systemd unit dey remain active after the process don die?

With the default ExitType=main and RemainAfterExit=no, this one dey happen because the process wey systemd dey treat as the main one still dey alive. Under those defaults, systemd dey follow one main PID for each service, and Type= determine how e choose am. Wrapper script wey start with Type=simple na the usual cause: the shell na the main PID, so the unit dey remain active when daemon wey the shell start for background exits. Run systemctl show -p MainPID app.service, then list the unit cgroup with systemd-cgls --unit=app.service, and compare both of dem.

Wetin be the difference between Type=simple and Type=exec?

Type=simple dey treat the unit as started immediately systemd create the process, before e execute the binary. Because of this, wrong path for ExecStart= still fit give successful start job, followed by failure. Type=exec dey wait until the execution succeed, so the start job itself go report that failure. Both of dem dey treat the same process as the main PID. Type=exec enter upstream systemd for version 240, but distributions fit backport am to older versions, like RHEL 8 do for systemd-239-15.el8.

I still need PIDFile= with Type=forking?

Yes, anytime the daemon dey write one. If you no set am, systemd go fall back to GuessMainPID=. Na guess be that, and e only reliable for service wey settle as one process. If the guess wrong or e no possible, failure detection and automatic restart no go work reliably for that unit. Point PIDFile= to the exact path wey the daemon dey write, normally under /run.

When I suppose use RemainAfterExit=yes?

Use am when the unit purpose na to change system state instead of keeping process dey run. A Type=oneshot unit wey load firewall rules or start container stack go exit as soon as e finish the work. Without RemainAfterExit=yes, the unit go move straight from starting to stopping. So any ExecStop= cleanup go run immediately the work finish, instead of when you choose to stop the unit, and systemctl stop no get anything left to stop. With am, the unit dey remain active without processes, and na the intended behaviour for this case.

Changing Type= need daemon-reload?

Yes, and you need restart the unit too. systemctl daemon-reload make systemd read the unit files again from disk, but running instance dey keep the Type= wey e start with. Run sudo systemctl daemon-reload and then sudo systemctl restart app.service before you test am. Otherwise, you still dey observe the old supervision behaviour.

Dis article help you?