Name

psrelated — Search for related processes.

Synopsis

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 ]

Background

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.

Description

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

Note

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.

Warning

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.

Examples

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-root
28086 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-root
1986 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 ~]$ psrelated
2372 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 -r
2372 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-root
2360 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 ~]$ 

Options

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.

Environment

TEXTBROWSER

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).

See Also

kill(1), ps(1), Network Security Toolkit