Check and Act on Stale Processes with needrestart

A library gets patched, apt finishes, and every process still mapping the old .so keeps running on it anyway, quietly unpatched. needrestart finds those stale processes so you do not have to guess which ones. This uses needrestart 3.6, packaged as 3.6-7ubuntu4.5. Give it fifteen minutes, a shell, and the package installed; the inspection commands themselves need no elevated privileges.

Start in list-only mode. It reports candidates without offering to restart anything, and that boundary matters, because an automatic restart can just as easily interrupt a database, a web service or someone's session. Keep the first pass read-only, then decide what to do with each item on its own.

1. Confirm the installed command

Check the binary and package version before trusting any example, this one included:

$ command -v needrestart
/usr/sbin/needrestart
$ needrestart --version
needrestart 3.6 - Restart daemons after library updates.
$ dpkg-query -W -f='${Package} ${Version}\n' needrestart
needrestart 3.6-7ubuntu4.5

The manual page installed with this package describes it as checking which daemons need restarting after a library upgrade. It also checks running interpreter processes and can flag an obsolete kernel. Output and available options change between package versions, so re-check this on a different distribution before folding the workflow into automation.

Checkpoint: If command -v shows a different path, or the version is not 3.6, read needrestart --help and the local manual page before touching the rest of this guide.

2. Run a scan that only lists

-r l selects list-only mode explicitly:

$ needrestart -r l
Your outdated processes:
at-spi-bus-laun[534150], dbus-daemon[2000], rtorrent main[2652583], xdg-document-po[534301], xdg-permission-[534363]
$ printf 'exit status: %s\n' "$?"
exit status: 0

Your own process names and PIDs will differ. A line under Your outdated processes just means needrestart considers that process stale, not that you should kill it on sight. A zero exit status only means the scan finished; it says nothing about whether every listed process is safe to restart right now.

-r takes a mode: l lists, i restarts interactively, a restarts automatically. Do not reach for -r a on a first run, or in any job that was not deliberately designed to disrupt a service. needrestart falls back to list-only if a configured interactive mode runs non-interactively anyway, but spelling out -r l makes the safety boundary visible in the command itself rather than relying on a fallback you have to remember exists.

3. Narrow the check to libraries or the kernel

-l checks obsolete libraries, -k checks for an obsolete kernel. Pair either with list-only mode while you are still investigating:

$ needrestart -l -r l
Your outdated processes:
at-spi-bus-laun[534150], dbus-daemon[2000], rtorrent main[2652583], xdg-document-po[534301], xdg-permission-[534363]
$ needrestart -k -r l
Pending kernel upgrade!

Running kernel version:
  6.8.0-139-generic

Diagnostics:
  The currently running kernel version is not the expected kernel version 6.8.0-142-generic.

Every name, version and diagnostic line here is host-specific. A pending kernel upgrade generally means the running kernel is older than the one your packages expect. List-only mode never reboots the machine on its own; treat the reboot itself as a separate action with a tested recovery path and a proper maintenance window, not something that follows automatically from this check.

Do not read a clean library check as proof every application is current: needrestart's interpreter checks are heuristic, and plenty of applications have their own update or reload mechanism outside its view. Use the result to decide what to look at next, not as a final verdict.

4. Get output a script can parse

For a non-interactive job, add -b for batch mode and keep -r l spelled out:

$ needrestart -b -r l
NEEDRESTART-VER: 3.6
NEEDRESTART-PID: at-spi-bus-laun=534150
NEEDRESTART-PID: dbus-daemon=2000
NEEDRESTART-PID: rtorrent main=2652583
$ printf 'exit status: %s\n' "$?"
exit status: 0

Batch output uses NEEDRESTART-VER and NEEDRESTART-PID style records. Do not hardcode the sample PIDs as if they were stable; parse the record names, keep the full value after the first equals sign, and leave room for record types a later package version might add.

-p is a separate mode for Nagios-style output and exit codes. Do not bolt it onto a general shell script just because both modes happen to target automation: pick the output contract your monitoring system actually expects, and test it against this specific installed version.

5. Know where list-only mode stops

List-only mode never fixes a stale process. The actual fix might be a service restart, an application-specific reload, a user logging out and back in, or a reboot for a kernel. Work out who owns it before you change anything:

$ ps -p PID -o pid=,user=,comm=,args=
$ systemctl status SERVICE_NAME

Swap in the real PID and SERVICE_NAME from your own scan. The first command is read-only; the second is also just inspection, though it can need elevated access for full detail on some systems. Do not feed a bare process name into a service command, a process name is not automatically a systemd unit.

Before touching interactive or automatic restart mode, write down the service's normal recovery command and confirm its data is backed up or otherwise recoverable. A restart drops connections. A reboot can interrupt every service on the box and surface a boot or filesystem problem you did not know was waiting. If a restart goes wrong, use that service's normal rollback procedure, check systemctl status SERVICE_NAME and its journal, and only restore a previous package or configuration through your system's documented change process.

6. Set configuration deliberately, not by guesswork

-c CONFIG_FILE picks a configuration file. The NEEDRESTART_MODE environment variable can override the configured restart mode, though a command-line flag still wins over it. For an apt hook specifically, a non-empty NEEDRESTART_SUSPEND stops the hook running needrestart after package installation or updates.

These two are easy to mix up. NEEDRESTART_MODE=l changes the mode for one invocation; it tells you nothing about the command's normal configuration. NEEDRESTART_SUSPEND=1 only silences the apt hook, it does not make a pending restart disappear and it has no effect on a direct invocation of the command.

$ NEEDRESTART_MODE=l needrestart -r l
$ NEEDRESTART_SUSPEND=1 apt-get ...

The first line is a read-only scan with an explicit mode. The second is a pattern showing where the suspend variable belongs in an apt hook, nothing more: do not run it as an incomplete package command, and do not treat suspension as a permanent way to stop dealing with restart notices. To test an apt transaction, use your normal change-control process and review the exact transaction before you confirm it.

Done means