Provided by: debian-goodies_0.88.2ubuntu1_all 
NAME
checkrestart - list processes that need to be restarted after an upgrade
SYNOPSIS
checkrestart [ OPTIONS ]
DESCRIPTION
checkrestart finds processes that are using files that have been deleted.
This is particularly 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 remain in
memory until the process is restarted: the processes is likely to be vulnerable until it is restarted.
Consequently, checkrestart is sometimes 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 (see BUGS below).
checkrestart needs to run as root in order to obtain a complete list of deleted files that are in use. If
run as a non-root user the output will be incomplete: programs started by other users are likely to be
omitted.
checkrestart will also warn you if other packages have indicated that a reboot is required.
OUTPUT
checkrestart will output:
• 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.
• 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.
-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.
-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).
-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 programe, 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 initscipt 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 a this comment are potentially disruptive: The command does need
to be run, but doing to 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).
unit, which excudes all programs started by the systemd unit whose name matches REGEXP.
For example, under systemd, you can exclude /usr/sbin/exim4 using -x
unit:^exim4\.service$ . This will work even if the package only provided an
initscript (systemd will generate a virtual unit using systemd-sysv-generator(1)).
This option requires that version 2 of the cgroups feature is in use (which is the
default in Debian). It has no effect if systemd(1) is not being used.
program, which excludes all programs whose path matches REGEXP.
For example, use `-x program:^/usr/local/bin/' to exclude a whole directory.
pid, which excludes the process with a process id (pid) matching REGEXP. For example, -x
pid:^1\$ excludes the init. Note that REGEXP is still a regular expression so use of
^ and $ are recommended to avoid excluding too much.
file, which excludes processes using deleted files that match REGEXP.
For example, `-x file:libz\.so\..+' will exclude everything using (any version of)
the libz library. If no TYPE is specified then it is the same as using file.
dangerous-unit
which does not exclude anything from being reported as using deleted files, but
instead marks any commands involving that unit with a CAUTION warning. This is
intended to be used when restarting a unit is potentially disruptive. For example,
restarting gdm3.service will terminate the entire gnome session. It still needs to
be done to ensure gnome stops using deleted files, but the user will want to pick
their moment.
dangerous-initscript
which does not exclude anything from being reported as using deleted files, but
instead marks any commands involving that initscript with a CAUTION warning. This is
intended to be used when restarting an initscript is potentially disruptive. For
example, restarting gdm3 will terminate the entire gnome session. It still needs to
be done to ensure gnome stops using deleted files, but the user will want to pick
their moment.
suggested-unit,
which does not 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 to systems running systemd and not
using cgroups version 2. On such systems, if a process is found to be started by a
unit then that unit will always be suggested as the way to restart the process. 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.
For example, /usr/libexec/gdm-session-worker from the gdm3 package is started by
gnome but does not appear in the cgroup created by the gdm3.service. However,
gdm3.service will still be suggested as a way to restart this process. Setting -x
done-suggest:^gdm3.service\$ will prevent that suggestion being made.
suggested-initscript,
which does not exclude anything from being reported as using deleted files, but
instead stops checkrestart from suggesting that an initscript matching REGEXP can
restart a programme. If systemd is not being used, or a process was not 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. For 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 will be used to find exactly which unit started each process.
-i REGEXP, --exclude-package REGEXP
Is the same as -x package:REGEXP
--exclude-unit REGEXP
Is the same as -x unit:REGEXP
--exclude-program REGEXP
Is the same as -x program:REGEXP
-e PID, --exclude-pid REGEXP
Is the same as -x pid:REGEXP
--exclude-file REGEXP
Is the same as -x file:REGEXP
--dont-suggest-unit REGEXP
Is the same as -x suggested:REGEXP
--dangerous-unit REGEXP
Is the same as -x dangerous-unit:REGEXP
--dangerous-initscript REGEXP
Is the same as -x dangerous-initscript:REGEXP
--dont-suggest-initscript REGEXP
Is the same as -x initscript:REGEXP
-a, --all
Prevents the exclude.conf and local-exclude.conf files from being read and removes the effect of
all --exclude* and -b arguments given earlier on the command line. This means nothing will be
excluded. This can then be followed by further uses of those arguments to rebuild the 'exclusion'
settings exactly how you want them. It does not reset anything added through the --dont-suggest-*
or --dangerous-* options, or prevent the suggestions.conf or local-suggestions.conf files from
being read (see 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 ignored. (If you want to exclude an individual
package, see the -x option.)
-n, --no-lsof
Do not use lsof(8) to find deleted files. lsof may be slow if there are a large number of open
files, and this option will cause checkrestart to use an alternative mechanism for finding deleted
files. If lsof(8) is not installed the alternative mechanism with be used automatically.
-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 '#' are skipped. This option can be used multiple times.
CONFIGURATION FILES
If they exist, the files /etc/checkrestart/local-exclude.conf, /etc/checkrestart/exclude.conf,
/etc/checkrestart/local-suggestions.conf, and /etc/checkrestart/suggestions.conf files are read to
provide defaults for the -x option. Blank lines and lines starting with a # are ignored, and any other
line is passed to the -x option.
The idea is that Debian provides defaults for --exclude-* in exclude.conf, defaults for (for and
--dont-suggest-* and --dangerous-* in suggestions.conf, and you can add your own via the two local-*.conf
files.
However 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.
The -b option also allows you to add another file with the same syntax, and again this can contain
anything understood by -x.
EXIT STATUS
The program will exit with error status 1 when there are deleted open files, 0 when there are none (after
filtering out anything excluded through the --exclude options), and 3 if rheee are errors. This provides
compatibility with automated monitoring tools such as Nagios (for which you may wish to use the -t option
to get a single line of output).
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')
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
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
BUGS
checkrestart will not detect if a script was itself deleted.
checkrestart will be 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.
checkrestart will believe whatever a process writes into /proc/pid/cmdline, so may report the wrong
program name. (See proc(5)).
checkrestart can only report that processes using deleted files, and assumes that these always indicate
that a restart is needed: it cannot tell whether deleted files are expected or whether they should be
flagged (other than what you tell it via the various -x options).
If you find a bug, please provide the following information when submitting a bug report against the
checkrestart package (using reportbug(1)):
• The output from checkrestart --debug (include any other options that trigger the bug)
• 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. It 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).
needrestart is also intended to do the restarting automatically, whereas checkrestart is for
reporting and will leave taking action to the humans.
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.
COPYRIGHT AND LICENSE
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.
debian-goodies December 19 2006 checkrestart(8)