psrelated — Search for related processes.
psrelated [
-p
TEXT
| --process TEXT
] [
-n
TEXT
| --match-name TEXT
] [
-r
[true]|false
| --recurse [true]|false
] [ --kill [true]|false
] [ --include-root [true]|false
] [
-o
TEXT
| --format TEXT
] [
-h
[true]|false
| --help [true]|false
] [
-H
[true]|false
| --help-long [true]|false
] [
-v
[true]|false
| --verbose [true]|false
] [ --version [true]|false
]
At a point in time, we were faced with the problem of determining how to kill a wmmemload dockapp process which was running on a particular X desktop. The general ps command did not seem to provide the necessary methods to easily distinguish one wmmemload process from another. In addition, we discovered that we could not find the parent X server by following the parent process ID chain from the wmmemload process.
This left us with the fundamental question: How does one find all of the processes related to a single X server?
After reviewing the problem, we were able to generalize the problem to: How does one find all of the processes directly related to process ABC?
By reviewing the output of the ps
command, we came to the conclusion that we could find all of
the processes related to a particular X
server by recursively looking for all processes whose parent
process traced its way back to the X
server OR (and this is critical) whose real
group ID (as generated from the %r output
format of ps) could be traced back to the our
X server.
The psrelated script was then created to help display and manage subsets of these related processes.
The psrelated command is used to display and or kill a
subset of processes related a initial root
process. The root process is specified by the
user and used as a starting point. From there, we look for ALL
processes in the following manner:
The root process is always included in our collection of related processes. However, its not displayed in the output unless the user specifically requests it.
If the parent process of a process in question has been included in our collection of related processes, then the process in question will be included as well.
If the real group ID a process in question matches the real group ID of a process already included in our collection of related processes, then the process in question will be included as well.
If the --recurse (or
-r) option has been specified, we will
recursively search for more related processes for each
candidate process we accept.
You have several ways to specify the root process to start the search from.
You may specify a integer process ID. This is
the preferred and most accurate way to get reliable results. For
example: -p 2388.
You may specify the name of a file whose first
line contains a integer process ID. For example: -p
/var/run/httpd.pid.
You may specify a X
DISPLAY (typially in the form of ":0.0"), and
we'll try our best to track down its root process. For example:
-p ${DISPLAY}. NOTE: This is the default
assumption if you don't include the -p
option.
When you run the psrelated script. You will specify (or
take the default) initial root process and
tell us whether or not you want us to perform a recursive search
via the --recurse option. We will then build an
array of ALL related processes.
From the collection of related
processes, you can then filter what processes we keep
in the collection via the --name MATCH and/or
--include-root options.
By default, we will print the collection of related
processes showing the process ID followed by the process name (you
can adjust the format a bit if required). If you specify the
--kill option, we will kill the matching
processes (instead of printing them).
Related processes are not necessarily all of the descendents. This is due to the fact that we look at the real group ID of each process as well as the parent process ID. In the real world, its been shown that the X server will be included as a related process if you start your search from the fluxbox window manager.
This script was designed and tested on a Linux
distribution produced by http://www.networksecuritytoolkit.org/. It
may or may not work on other Unix like operating systems. It is
HIGHLY recommended that you experiment with just printed results
prior to using the --kill option.
The following finds ALL running processes on the system which are directly related to process 28086 including process 28086 in the output:
[pkb@probe ~]$psrelated -p 28086 -r --include-root28086 xterm 28087 bash[pkb@probe ~]$
The following finds ALL processes related to the httpd service:
[pkb@probe ~]$psrelated -p /var/run/httpd.pid -r --include-root1986 httpd 2014 httpd 2015 httpd 2016 httpd 2017 httpd 2018 httpd 2019 httpd 2020 httpd 18383 httpd 18424 httpd 18426 httpd 18428 httpd 18429 httpd 18430 httpd 18431 httpd 18432 httpd 18433 httpd 18435 httpd 18437 httpd 18438 httpd 18440 httpd[pkb@probe ~]$
The following kills the gkrellm application running on the current X server:
[pkb@probe ~]$psrelated --kill -r -n ^gkrellm[pkb@probe ~]$
The following demonstrates the running processes on the system which are directly related to the current X server (no recursion):
[pkb@probe ~]$psrelated2372 fluxbox[pkb@probe ~]$
The following finds ALL running processes on the system which are directly related to the current X server (with recursion):
[pkb@probe ~]$psrelated -r2372 fluxbox 3164 xterm 3165 bash 2129 emacs-x 8116 aspell 31514 xterm 31515 bash 6809 gkrellm 9525 psrelated 9537 psrelated 9538 ps 17865 xterm 17866 bash 3431 ssh 28086 xterm 28087 bash 26291 xterm 26292 bash 2080 ssh[pkb@probe ~]$
The following finds ALL running processes on the system which are directly related to the current X server including the X server itself:
[pkb@probe ~]$psrelated -r --include-root2360 Xvnc 2372 fluxbox 3164 xterm 3165 bash 2129 emacs-x 8116 aspell 31514 xterm 31515 bash 6809 gkrellm 9550 psrelated 9562 psrelated 9563 ps 17865 xterm 17866 bash 3431 ssh 28086 xterm 28087 bash 26291 xterm 26292 bash 2080 ssh[pkb@probe ~]$
The following command line options are available:
-p TEXT] | [--process TEXT]
This option is used to specify the parent process
which you want to find all of the related descendents of. You
have several choices on how you specify the parent process
ID. You may specify a integer process ID (like 1782). You may
specify a X DISPLAY (like ":0.0", "${DISPLAY}", or "flan:2.0").
You may specify the name of a file containing a integer process
ID (like /var/run/httpd.pid).
-n TEXT] | [--match-name TEXT]
Sometimes, you are looking for a child process which has a specific name. If you specify this matching string (like '^wmmemload$'), we'll only display results for the related processes whose name matches. If you omit this option (or specify 'ALL'), we'll display ALL related processes.
-r [true]|false] | [--recurse [true]|false]
By default, we only look at the immediate descendants of the root process. If you include this option, we will recursively search each descendaant process resulting in the entire "family tree" of processes related to the original starting point. For example, if you start with PID 1 and include the recurse option, you should end up seeing ALL of the running processes on most Linux boxes.
--kill [true]|false]
By default, we only display information about the
processes found and matched. If you include this option, we will
attempt to kill the matching processes. For example, if you want
to kill the wmmemload dockapp process running on your X display,
you could specify psrelated -r -n '^wmmemload$'
--kill. BE VERY CAREFUL! Its very easy to kill more
processes than you really want. NOTE: Don't forget to use the
--include-root option if you want to kill the
root process as well.
--include-root [true]|false]
By default, we only display the related child processes to the original process specified. If you include this option, the original process (parent) will also be included in the output.
-o TEXT] | [--format TEXT]
This option allows one to plug in their own custom awk output format. If omitted, the default format will be used (which displays process ID followed by process name). You may refer to 4 different awk variables (ps_name, ps_pid, ps_ppid, and ps_rgid) in your awk output line.
-h [true]|false] | [--help [true]|false]
When this option is specified, psrelated will display a short one line description of psrelated, followed by a short description of each of the supported command line options. After displaying this information psrelated will terminate.
-H [true]|false] | [--help-long [true]|false]
This option will attempt to pull up additional
psrelated documentation within a text based
web browser. You can force which browser we use setting the
environment variable TEXTBROWSER, otherwise,
we will search for some common ones.
-v [true]|false] | [--verbose [true]|false]
When you set this option to true, psrelated will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.
--version [true]|false]
If this option is specified, the version number of the script is displayed.