Home Original page

GitHub - deshaw/procfd: Linux lsof replacement to list open file descriptors for processes

Introduction

procfd is a Linux tool to query open file descriptors for processes. It is a rust replacement for the lsof command. Compared to lsof, procfd:

  • Is very fast
  • Is safe against blocking operations and never hangs
  • Has easy to use command-line options and filters
  • Shows endpoints of pipes and unix sockets by default
  • Can export data as json

Examples

Filter by PID

$ procfd --pid 710156
 PID    | User     | Name | Type         | FD | Mode | Target
--------+----------+------+--------------+----+------+---------------------------------------------------------------------------------
 710156 | maverick | sshd | path         | 0  | rw   | /dev/null
 710156 | maverick | sshd | path         | 1  | rw   | /dev/null
 710156 | maverick | sshd | path         | 2  | rw   | /dev/null
 710156 | maverick | sshd | path         | 3  | rw   | /dev/ptmx
 710156 | maverick | sshd | socket[inet] | 4  | rw   | TCP: my-host.com:22 -> remote-host.com:63706 (ESTABLISHED)
 710156 | maverick | sshd | path         | 5  | r    | /etc/krb5/db/data.mdb
 710156 | maverick | sshd | socket[unix] | 6  | rw   | stream (ESTABLISHED)
 710156 | maverick | sshd | socket[unix] | 7  | rw   | stream -> sshd[710152][9] (ESTABLISHED)
 710156 | maverick | sshd | path         | 8  | w    | /run/systemd/sessions/349.ref
 710156 | maverick | sshd | pipe         | 9  | r    | pipe -> [10]
 710156 | maverick | sshd | pipe         | 10 | w    | pipe -> [9]
 710156 | maverick | sshd | path         | 14 | rw   | /dev/ptmx
 710156 | maverick | sshd | path         | 15 | rw   | /dev/ptmx
 710156 | maverick | sshd | pipe         | 16 | r    | pipe -> sleep[2813702][1],bash[3964926][1]
 710156 | maverick | sshd | pipe         | 17 | r    | pipe -> sleep[2813702][2],bash[3964926][2]
 710156 | maverick | sshd | exe          |    |      | /usr/sbin/sshd
 710156 | maverick | sshd | cwd          |    |      | /
 710156 | maverick | sshd | root         |    |      | /
 710156 | maverick | sshd | mmap         |    |      | /usr/lib64/ld-2.28.so
 710156 | maverick | sshd | mmap         |    |      | /usr/lib64/libaudit.so.1.0.0
 710156 | maverick | sshd | mmap         |    |      | /usr/lib64/libblkid.so.1.1.0
 710156 | maverick | sshd | mmap         |    |      | /usr/lib64/libc-2.28.so

Filtering examples

  • procfd --type {socket,cwd,root,exe,path,pipe,mmap} - Filter by socket type
  • procfd --socket-domain {unix,inet,inet4,inet6,other} - Filter sockets by domain
  • procfd --socket-type {tcp,udp,unix-stream,unix-dgram} - Filter by socket type
  • procfd --socket-state {listen,established,close} - Filter by socket state
  • procfd --src-host 10.77.10.3 --src-port 1044 --dst-host google.com --dst-port 443 - Filter by source AND destination host/port
  • procfd --port 443 - Filter by source OR destination port
  • procfd --cmd ssh - Filter by command (exact match)
  • procfd --cmd /ssh/ - Filter by command (regex match)
  • procfd --user maverick - Filter by username
  • procfd --pid 3964924 - Filter by process ID

Other options

  • procfd --no-dns - Disable DNS lookups
  • procfd --json - Render results as JSON
  • procfd --pid-only - Only show PIDs

Installation

procfd is not yet available as a distro package, but you can install it using Cargo or download it from the Releases page

Cargo

Crates.io

procfd can be installed directly from crates.io with:

Cargo will build the procfd binary and place it in your CARGO_INSTALL_ROOT. For more details on installation location see the cargo book.

Nix

nixpkgs unstable package

nix-env -iA nixpkgs.procfd

Manual

Download the binary on the releases page and put them in your $PATH. Or run the shell command:

wget -c https://github.com/deshaw/procfd/releases/latest/download/procfd-x86_64-unknown-linux-gnu.tar.gz -O - | tar xz

Comparison to lsof and lsfd

  • lsof is the original cross-platform command to list open file handles
  • lsfd is a Linux-only rewrite of lsof by one of the main contributors to lsof which addresses many usability issues with lsof

Below is an incomplete (and biased) comparison of these tools:

Feature procfd lsof lsfd
Language rust C C
Platform support Linux only Cross-platform Linux only
Speed Very fast Variable 1 Variable
JSON output Yes No Yes
Avoids blocking operations Yes Partial 2 No
Display endpoint of unix sockets Yes Partial 3 Partial
Display endpoint of pipes Yes Yes (with lsof -E) Yes
Usability Easy Complicated Medium
Filter by expression No Partial Yes
DNS Lookups Yes Yes No
Show mount points No Yes Yes
Protocol support Partial4 Full Full
Filter by path No5 Yes Yes
Filter by command Yes with regex Yes exact match Yes with regex
Filter by src/dst host/port Yes No Yes

History

procfd was contributed back to the community by the D. E. Shaw group.

D. E. Shaw Logo

License

This project is released under a BSD-3-Clause license.

We love contributions! Before you can contribute, please sign and submit this Contributor License Agreement (CLA). This CLA is in place to protect all users of this project.

Notes

  1. Fast with local disks, but can be very slow with lots of mounted network filesystems ↩

  2. lsof -b avoids blocking calls, but also fails to display any socket information ↩

  3. lsfd and lsof +E display limited information about the socket endpoint including the command, socket number, and fd number, but not the socket endpoint path. lsfd may miss some endpoints if process filters are applied ↩

  4. List of unsupported protocols is listed in #12 ↩

  5. Not currently implemented, but can use grep to filter output of procfd --type path ↩