Scroll to navigation

checkrestart(8) debian-goodies checkrestart(8)

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

Show the program help and exit.

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.

Generate detailed output. This turns on the -f option and also indicates why any exclusions were made.

Include debugging details in output. This is intended for investigating bugs and turns on the -v option.

Generate just one line of output: this is suitable for monitoring tools such as Nagios (see EXIT STATUS).

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:
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.

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.

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.

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:
produced by any SYSTEMD lines

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.

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.

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:

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).

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.

For example, use `-x program:^/usr/local/bin/' to exclude a whole directory.

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.

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.

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.

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.

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.

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.

Is the same as -x package:REGEXP

Is the same as -x unit:REGEXP

Is the same as -x program:REGEXP

Is the same as -x pid:REGEXP

Is the same as -x file:REGEXP

Is the same as -x suggested:REGEXP

Is the same as -x dangerous-unit:REGEXP

Is the same as -x dangerous-initscript:REGEXP

Is the same as -x initscript:REGEXP

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).

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.)

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.

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

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).

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.

December 19 2006 debian-goodies