procfd

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

procfd can be installed directly from crates.io with:

cargo install procfd

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

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.

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

Footnotes

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 ↩