checkrestart(8)

📦
version 0.88.2ubuntu2 · 3 versions
, in debian trixie, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 NAME 💅

checkrestart — list processes that need to be restarted after an upgrade. That's the whole job description, bestie. This is the manual for checkrestart(8), from debian-goodies, and we're going through every single line together. 🫶

🦋 SYNOPSIS 🦋

checkrestart [ OPTIONS ]

✨ DESCRIPTION ✨

okay so picture this: checkrestart hunts down processes that are using files that have been deleted. Yes, actually deleted. The file is gone off disk but the process is still out here holding onto it like it's a situationship. 💀

And this is so important after security upgrades, because many debian packages do not restart processes after an upgrade: files that were used by processes started before the upgrade will just stay chilling in memory until the process is restarted. Which means the process is likely to be vulnerable until it is restarted. no cap, that's the whole danger. 😭

Which is why checkrestart sometimes gets used as an audit tool — to find services that need to be restarted after security upgrades. Administrators should not, however, rely on its output alone though (go read the BUGS section below, I'm being fr fr).

Also it needs to run as root to get a complete list of deleted files that are in use. Run it as a non-root user and the output will be incomplete: programs started by other users are likely to be omitted. So like, half the receipts. 🙈

And one more thing — checkrestart will also warn you if other packages have indicated that a reboot is required. 👑

🌈 OUTPUT 🌈

here's what checkrestart is gonna show you, bestie:

  • Whether any packages have indicated that the system needs rebooting, and if so, which packages have done so. This relies on the packages adding themselves to /run/reboot-required.pkgs and creating /run/reboot-required.
  • The number of processes that need restarting. count 'em.
  • Which processes are using deleted files. Processes are grouped by the systemd unit that started them or the debian package that provided them. The --exclude option can be used to exclude processes from the results.
  • If the -f option was given then the deleted files used by each process will also be listed. The --exclude option can be used to ignore the use of individual files.
  • Which commands to run to restart packages. These will be commands to restart systemd units or initscripts. If the system has departed from the Debian default and is not running systemd with the cgroups(7) feature then the commands should be considered 'suggestions' only: it is not possible to reliably determine which initscript started any given process (the --exclude option can be used to control such suggestions). Where commands are potentially disruptive (e.g., restarting systemd-logind may result in users being immediately logged out) they can be marked with a CAUTION note — the --exclude option can control which commands this applies to.

If the -m option is given then the output is tab-separated and machine-readable (see the description of that option below). If the -t option is given then the output is restricted to one line.

🎀 OPTIONS 🎀

  • -h, --help — Show the program help and exit. bye bestie 🫶
  • -f, --show-files — List the deleted files and which program is using them. The list excludes anything excluded by the --exclude option. Without this only the name of the program using the deleted files is reported.
  • -v, --verbose — Generate detailed output. This turns on the -f option and also indicates why any exclusions were made. receipts for the receipts. 🧾
  • -d, --debug — Include debugging details in output. This is intended for investigating bugs and turns on the -v option.
  • -t, --terse — Generate just one line of output: this is suitable for monitoring tools such as Nagios (see EXIT STATUS). one (1) line. minimal. clean. ✨
  • -m, --machine — Generate machine readable output. Each line is a tab-separated list.

First the output shows what needs to be restarted in the form:

TYPE  source  pid  program  exe  [cmdline] deleted type

Here the exe is what is actually running. For scripts this will be the interpreter, but if it can be determined, the name of the script will be reported as the programme and the cmdline as reported by /proc/pid/cmdline will be shown. This can be manipulated by the programme itself, unlike the exe which is from /proc/pid/exe. type will be Program or Script. The deleted field is usually blank but will be Deleted if the exe itself is deleted (this does not work for scripts). The source indicates which systemd unit or Debian package is responsible for the programme.

The TYPE is one of:

  • SYSTEMD, if the program was started by the systemd unit named in source. Restarting that unit will restart the program. These lines will only be produced if systemd is being used and version 2 of the cgroups(7) feature is in use (this is the default in Debian).

For example,

SYSTEMD foo.service 614 /usr/bin/foo /usr/bin/python3 ['python' 'foo']  Script

means that restarting the foo.service unit will restart the python script foo with pid 614.

  • PACKAGE_SYSTEMD, if program is part of the package named in source and the package also ships a systemd unit: restarting that unit may restart the programme, but this is only a suggestion — it is not guaranteed that it will work. You can control which units are suggested using the -x option. These lines will only be produced if systemd(1) is in use without version 2 of the cgroups(7) feature.

For example, PACKAGE_SYSTEMD gdm3 206 /usr/libexec/gdm-session-worker ... means that the gdm3 package provides gdm-session-worker and some unit in that package that may restart that programme.

  • SERVICE, if program is part of a package named in source that ships an initscript. Restarting the initscript may therefore restart the program, but this is not known for sure (there is no way to tell which initscript started a program). You will only see these lines if you do not run systemd. These lines are produced if you run systemd without cgroups version 2: if systemd is in use you will then get PACKAGE_SYSTEMD in preference to SERVICE lines when packages provide both units and initscripts. If systemd is not in use you will only get SERVICE lines.
  • OTHER, if program is in none of the above categories. These programs, whether or not they are from packages, still need restarting but the user will need to do so by hand. These lines can be produced whether systemd is in use or not. A program not in any package is treated as if it was in a package named Unpackaged: program, the part after the colon being the name, not the path, of the program. (If -p is in use then unpackaged programs are excluded).

For example, OTHER emacs-gtk 206706 /usr/bin/emacs-gtk... could be emitted if emacs(1) is using deleted files.

The next set of lines show the commands that will restart programs in the SYSTEMD lines, and which may restart programs in the PACKAGE_SYSTEMD or SERVICE lines. These look like:

  • SYSTEMD_COMMAND systemctl restart unit — produced by any SYSTEMD lines
  • SYSTEMD_COMMAND systemctl restart unit # suggested - from package package — produced by any PACKAGE_SYSTEMD lines: the comment shows which package contains the suggested unit. If a package provides multiple units they will all be listed on separate lines. You can use the --dont-suggest-unit option to remove these lines.
  • SERVICE_COMMAND service restart initscript # suggested - from package package — which relate to SERVICE lines: the comment shows which package contains the suggested initscript. If a package provides multiple initscripts they will all be listed on separate lines. You can use the --dont-suggest-initscript option to remove these lines.
  • # CAUTION: ... — Lines prefixed by this comment are potentially disruptive: The command does need to be run, but doing so may cause issues (such as terminating your whole gnome session): see the --dangerous-unit and --dangerous-initscript options.

If the -f option is also present the output will include a line for each deleted files, these are tab-separated lines that look like: file path pid exe [cmdline] deleted type showing the path to the file and then details of the process using it (fields are explained above).

If the -v option is also present there will include lines explaining anything excluded. These are also tab separated and are similar to the fields used above.

  • -x, --exclude [TYPE:]REGEXP — Exclude all things of the given TYPE that match REGEXP. This option can be used multiple times to make multiple exclusions, and anything added is combined with entries from the various configuration files (see the CONFIGURATION FILES section below) and from any files loaded with -b. You may need to insert single quotes around the whole argument if it contains characters such as $ that your shell treats specially. (e.g., checkrestart -x 'file:(\.sh$|foo)') The word TYPE can be one of the following:
    • package, which excludes programs from the debian package whose name matches REGEXP.

For example, to exclude /usr/bin/sshd you can use: -x package:^openssh-server\$. Programs not from any package are treated as if they were provided by a package called Unpackaged: program, so you can ignore them in the same way as packaged programs (for example, -x package:^Unpackaged:\sfoo will ignore a locally installed /opt/foo).

…and the TYPE list just keeps going, bestie, so buckle up 💖

  • unit — this one yeets out every program that was started by the systemd unit whose name matches REGEXP. Say you're under systemd and you wanna exclude /usr/sbin/exim4, you'd do -x unit:^exim4\.service$. And it still works even if the package only shipped an initscript — because systemd will just cook up a virtual unit using systemd-sysv-generator(1). Iconic of it honestly.
Heads up, bestie: this option requires version 2 of the cgroups feature to be in use (which is the default in Debian). And it does nothing if systemd(1) isn't the thing running your show.
  • program — nopes out every program whose path matches REGEXP. Wanna ghost a whole directory? -x program:^/usr/local/bin/ and you're done. Slay.
  • pid — excludes the process whose process id (pid) matches REGEXP. So -x pid:^1\$ drops the init. But listen — REGEXP is still a regular expression, so you really wanna use ^ and $ or you'll accidentally exclude way too much. Don't do that to yourself. 😭
  • file — excludes processes that are using deleted files matching REGEXP. Like, -x file:libz\.so\..+ will exclude everything using (any version of) the libz library. And if you don't specify a TYPE at all? It's the same as using file. Default behaviour, we love her.
  • dangerous-unit — okay so this one doesn't actually exclude anything from being reported as using deleted files. Instead it marks any commands involving that unit with a CAUTION warning. This is for when restarting a unit is potentially disruptive. Example: restarting gdm3.service will terminate your entire gnome session. It still needs to happen so gnome stops using deleted files, but the user probably wants to pick their moment. 🙈
  • dangerous-initscript — same energy, but for initscripts. Doesn't exclude anything from the report, just slaps a CAUTION warning on any commands involving that initscript. Again, for when restarting an initscript is potentially disruptive. Example: restarting gdm3 will terminate the whole gnome session. Still gotta be done so gnome stops using deleted files, but pick your moment, bestie.
  • suggested-unit — doesn't exclude anything from being reported as using deleted files, but instead stops checkrestart from suggesting that a systemd service matching REGEXP can restart any programme. This is only relevant on systems running systemd and not using cgroups version 2. On those systems, if a process is found to be started by a unit, that unit always gets suggested as the way to restart it. But when a process is not started by a service, checkrestart looks in the package providing the unit and suggests all units as possible ways to restart the process. Example: /usr/libexec/gdm-session-worker from the gdm3 package is started by gnome but does not appear in the cgroup created by gdm3.service. Still, gdm3.service gets suggested as a way to restart it. Setting -x done-suggest:^gdm3.service\$ will prevent that suggestion from being made.
  • suggested-initscript — doesn't exclude anything from being reported as using deleted files, but stops checkrestart from suggesting that an initscript matching REGEXP can restart a programme. If systemd isn't being used, or a process wasn't found in a systemd cgroup, then checkrestart suggests that all initscripts from the relevant package can restart the process — unless their path matches a suggested-initscript REGEXP. Example: the default settings include -x 'initscript:\.sh$' so that /etc/init.d/hwclock.sh will never be (incorrectly) suggested as a way to restart /sbin/getty, even though both are from the util-linux package.

This is mostly useful for non-systemd systems, since on systemd the cgroups mechanism is used to find exactly which unit started each process. Precision queen. 👑

  • -i REGEXP, --exclude-package REGEXP — literally the same thing as -x package:REGEXP. Same girl, different outfit. 💅
  • --exclude-unit REGEXP — same as -x unit:REGEXP.
  • --exclude-program REGEXP — same as -x program:REGEXP.
  • -e PID, --exclude-pid REGEXP — same as -x pid:REGEXP.
  • --exclude-file REGEXP — same as -x file:REGEXP.
  • --dont-suggest-unit REGEXP — same as -x suggested:REGEXP.
  • --dangerous-unit REGEXP — same as -x dangerous-unit:REGEXP.
  • --dangerous-initscript REGEXP — same as -x dangerous-initscript:REGEXP.
  • --dont-suggest-initscript REGEXP — same as -x initscript:REGEXP.
  • -a, --all — bestie, this one is the reset button. It stops the exclude.conf and local-exclude.conf files from being read, and it removes the effect of all --exclude* and -b arguments you gave earlier on the command line. So basically: nothing gets excluded. From there you can hit it with more of those arguments to rebuild your 'exclusion' settings exactly how you want them. 🎀 BUT — and this is the important part — it does not reset anything added through the --dont-suggest-* or --dangerous-* options, and it does not prevent the suggestions.conf or local-suggestions.conf files from being read (peep the CONFIGURATION FILES section below 👀).
  • -p, --package — only report things that belong to a package. This applies to files, programmes, initscripts and units: anything not from Debian packages is simply ignored. (And if you wanna exclude one specific package instead? See the -x option, babe.)
  • -n, --no-lsof — do not use lsof(8) to find deleted files. lsof can be slow if there are a lot of open files, and this option makes checkrestart use an alternative mechanism for finding deleted files instead. Oh and — if lsof(8) isn't even installed, that alternative mechanism gets used automatically. Convenient. ✨
  • -b FILE, --blocklistfile FILE — any deleted files matching patterns (Python regular expressions) in FILE will be ignored. Lines in FILE that are blank or start with # get skipped. This option can be used multiple times. Stack 'em up. 🫶

💖 CONFIGURATION FILES 💖

If they exist, these four files get read to provide defaults for the -x option:

  • /etc/checkrestart/local-exclude.conf
  • /etc/checkrestart/exclude.conf
  • /etc/checkrestart/local-suggestions.conf
  • /etc/checkrestart/suggestions.conf

Blank lines and lines starting with a # are ignored, and any other line is passed straight to the -x option. Simple as that.

The whole idea is that Debian provides the defaults for --exclude-* in exclude.conf, and defaults for --dont-suggest-* and --dangerous-* in suggestions.conf, and then you can add your own via the two local-*.conf files. Cute, right? 🎀

But plot twist — you can actually put anything understood by -x into either file. The only difference is that the -a option prevents the two exclude.conf files from being read, but does not affect the two suggestions.conf files at all. That's the whole distinction, bestie.

And the -b option also lets you add another file with the exact same syntax, and again, that file can contain anything understood by -x. Sky's the limit. 🌈

🎀 EXIT STATUS 🎀

  • The program exits with status 1 when there are deleted open files.
  • It exits with 0 when there are none (after filtering out anything excluded through the --exclude options).
  • And it exits with 3 if there are errors.

Why does this matter? Because it gives you compatibility with automated monitoring tools like Nagios. (And for Nagios you might wanna use the -t option to get a single line of output. Iykyk.) 👑

✨ EXAMPLES ✨

🌸 Running as a normal user

$ checkrestart
WARNING: This program should be run as root: information will be incomplete
1 non-ignored program(s) or unit(s) need restarting (see checkrestart(8))

The following are using deleted files but there is no suggested way to restart them:
emacs-gtk:
        Program /usr/bin/emacs-gtk (PID: 655075, CMDLINE: 'emacs -nw')

Yeah see — run it as a user and it'll warn you that the info is gonna be incomplete. It's giving "I can only tell you so much". 😭

🌸 Running as root

# checkrestart
3 non-ignored program(s) or unit(s) need restarting (see checkrestart(8))

The following systemd units started programmes that are using deleted files:
cron.service:
  Program /usr/sbin/cron (PID: 626, CMDLINE: '/usr/sbin/cron -f')
dbus.service:
  Program /usr/bin/dbus-daemon (PID: 627, CMDLINE: '/usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only')

The following are using deleted files but there is no suggested way to restart them:
emacs-gtk:
  Program /usr/bin/emacs-gtk (PID: 655075, CMDLINE: 'emacs -nw')

Systemd commands:
systemctl restart cron.service
# CAUTION: systemctl restart dbus.service

Look at that # CAUTION: line. That's the dangerous-* machinery doing its thing. Respect the caution. 💅

🌸 Excluding things from the results, and listing files with -f

# checkrestart -x 'unit:^dbus.service$' \
               -x 'program:^/usr/bin/(emacs|vim)' \
               --dangerous-unit '^(ana)?cron.service$' \
               --show-files
1 non-ignored program(s) or unit(s) need restarting (see checkrestart(8))

The following systemd units started programmes that are using deleted files:
cron.service:
  Program /usr/sbin/cron (PID: 626, CMDLINE: '/usr/sbin/cron -f')
    /lib/x86_64-linux-gnu/ld-2.31.so

Systemd commands:
# CAUTION: systemctl restart cron.service

See how --show-files popped out that /lib/x86_64-linux-gnu/ld-2.31.so line? Chef's kiss. 🌟

🐛 BUGS 🐛 (bestie, read this before you @ me)

Okay so checkrestart is iconic but she is NOT perfect, and she wants you to know it. Lowkey a vibe check on her own limits:

  • checkrestart will not detect if a script was itself deleted. 💀
  • checkrestart will generate false positives if non-deleted files or programs have names ending in (deleted).
  • checkrestart may report the wrong name if a program is actually a script. Common scripts will be detected, so that's something.
  • checkrestart will believe whatever a process writes into /proc/pid/cmdline, so she may report the wrong program name. (See proc(5) for the receipts.)
  • checkrestart can only report that processes are using deleted files, and she assumes that these always indicate that a restart is needed. She cannot tell whether deleted files are expected or whether they should be flagged — other than what you tell her via the various -x options. So yeah, it's giving "trust me bro" energy and you gotta configure her.

If you find a bug, please provide the following info when you submit a bug report against the checkrestart package (using reportbug(1)):

  1. The output from checkrestart --debug — and include any other options that trigger the bug too, bestie, don't be shy.
  2. The output from running the following command as root:
lsof | grep -E 'delete|DEL|path inode'

👀 SEE ALSO 👀

  • needrestart(8) — is a similar tool to checkrestart. She runs when new versions of debian packages are installed, whereas checkrestart can run at any time. The two can be used together, and may give different results — although if needrestart finds something that checkrestart does not, then that is a bug in checkrestart: please report such instances using reportbug(1). Also, needrestart is intended to do the restarting automatically, whereas checkrestart is for reporting and will leave taking action to the humans. No cap. 🙈
  • lsof(8) — is a generic tool for investigating which files are in use. checkrestart uses this (unless the -n option is given).
  • pmap(1) — is another tool for inspecting which files are loaded. The -n option uses this.
  • proc(5) — is a pseudo filesystem that contains information about running processes.
  • cgroups(7) — explains the control groups mechanism used by systemd(1) to keep related processes together. checkrestart assumes version 2 is in use if systemd is running.
  • systemctl(1) — is the generic tool to restart services under systemd(1).
  • service(1) — is the generic tool to restart services if systemd is not in use.

👑 AUTHOR 👑

checkrestart was written by Matt Zimmerman for the Debian GNU/Linux distribution. It was later improved by Javier Fernandez-Sanguino with contributions from many different users and developers of the Debian GNU/Linux distribution. Literally a group project that ate. 💅

Copyright (C) 2001 Matt Zimmerman <mdz@debian.org> Copyright (C) 2007-2020 Javier Fernandez-Sanguino <jfs@debian.org> Copyright (C) 2013-2020 Axel Beckert Copyright (C) 2022 Richard Lewis

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

On Debian systems, a copy of the GNU General Public License version 2 can be found in /usr/share/common-licenses/GPL-2.

And that's the whole page, bestie — we ate and left no crumbs. 🍓✨

This one's from debian-goodies, dated December 19 2006, and it's the checkrestart(8) manual. Go restart something. 🫶💖

📦 where this page comes from