delphix / ptools

This repository contains a collection of Linux utilities for inspecting the state of processes, modeled after the tools by the same name which exist on Solaris/Illumos.

ptools

This repository contains a collection of Linux utilities for inspecting the state of processes, modeled after the tools by the same name which exist on Solaris/Illumos.

Getting Started:

To build ptools, run the following on an Ubuntu 18.04 VM:

$ git clone https://github.com/delphix/ptools.git
$ cd ptools/
$ curl https://sh.rustup.rs -sSf | bash -s -- -y
$ cargo build

The utilities can be run out of the target/debug directory, e.g.

$ ./target/debug/ptree 1

To install ptools, additionally run:

$ cargo install cargo-deb
$ cargo deb
$ sudo apt install ./target/debian/ptools_0.1.0_amd64.deb

Why ptools?

Linux already has a number of mechanisms which can be used to inspect the state of processes (the proc filesystem, ps, lsof, etc.). Why add a new set of tools?

The main advantage of ptools is consistency. The utilities provided by ptools are consistently named and have a consistent interface. Also, significantly, they can be run against core dumps where applicable, providing a uniform way to examine live processes and core dumps. This is very useful for those who rely heavily on core dumps to do postmortem debugging. The goal of this project is to make this same consistent debugging experience available on Linux.

Current State

Currently, this repository provides the following commands

• pfiles - shows the open files and sockets of the process, as well as their corresponding file descriptors
• pargs - shows the command line arguments passed to the process
• penv - shows the environment of the process
• ptree - shows the process tree containing the process

There are a number of other commands available on Solaris/Illumos which have not been implemented here yet, perhaps most notably pstack. Also support for examining core dumps has not yet been implemented.

Contribute

1. Fork the project.
2. Make your bug fix or new feature.
3. Add tests for your code.
4. Send a pull request.

Code of Conduct

This project operates under the Delphix Code of Conduct. By participating in this project you agree to abide by its terms.

Contributor Agreement

All contributors are required to sign the Delphix Contributor agreement prior to contributing code to an open source repository. This process is handled automatically by cla-assistant. Simply open a pull request and a bot will automatically check to see if you have signed the latest agreement. If not, you will be prompted to do so as part of the pull request process.

Reporting Issues

Issues should be reported in the GitHub repo's issue tab.

Statement of Support

This software is provided as-is, without warranty of any kind or commercial support through Delphix. See the associated license for additional details. Questions, issues, feature requests, and contributions should be directed to the community as outlined in the Delphix Community Guidelines.

License

This is code is licensed under the Apache License 2.0. Full license is available here.

ptools's Issues

testing and code style checks via GitHub Actions for PR context

It would be good to have code analysis and testing incorporated to this repo via GitHub Actions.

pfiles can crash when file descriptors are closed

If a file descriptor is closed between the time when pfiles reads the /proc/<pid>/fd/ directory and when it tries to read the particular entries, pfiles crashes instead of handling the race gracefully:

[New LWP 12645]
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
Core was generated by `/usr/bin/pfiles 3811'.
Program terminated with signal SIGABRT, Aborted.
#0  __GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:51
51	../sysdeps/unix/sysv/linux/raise.c: No such file or directory.
(gdb) bt
#0  __GI_raise (sig=sig@entry=6) at ../sysdeps/unix/sysv/linux/raise.c:51
#1  0x00007fe29e3e2801 in __GI_abort () at abort.c:79
#2  0x000055bc5f5f5807 in panic_abort::__rust_start_panic::abort () at src/libpanic_abort/lib.rs:48
#3  0x000055bc5f5f57f6 in __rust_start_panic (_payload=<optimized out>) at src/libpanic_abort/lib.rs:44
#4  0x000055bc5f614da6 in rust_panic (msg=...) at src/libstd/panicking.rs:521
#5  0x000055bc5f614d42 in std::panicking::rust_panic_with_hook (payload=..., message=..., file_line_col=<optimized out>) at src/libstd/panicking.rs:491
#6  0x000055bc5f61511d in rust_begin_unwind (info=<optimized out>) at src/libstd/panicking.rs:375
#7  0x000055bc5f5f1c5d in core::panicking::panic_fmt (fmt=..., location=0x7ffc02ceae50) at src/libcore/panicking.rs:84
#8  0x000055bc5f5ef386 in core::result::unwrap_failed (msg=..., error=...) at src/libcore/result.rs:1188
#9  0x000055bc5f600ad7 in ptools::print_files ()
#10 0x000055bc5f5fa4f8 in ptools::pfiles_main ()
#11 0x000055bc5f5eb513 in std::rt::lang_start::{{closure}} ()
#12 0x000055bc5f5f5b8f in main ()

pfiles: include socket state in output

It would be useful to include the state (ESTABLISHED, LISTEN, FIN_WAIT1, etc) for each tcp socket found by pfiles. This information can be found as in integer in /proc/net/tcp, and translated to a state using the enum in include/net/tcp_states.h in the kernel.

pfiles prints IP addresses in the wrong byte order

Example:

    3: S_IFSOCK mode:777 dev:0,9 ino:13922 uid:0 gid:0 size:0
       O_RDWR|O_CLOEXEC|O_NDELAY | O_NONBLOCK
         SOCK_STREAM
         sockname: AF_INET 1.0.0.127  port: 22

Note that 127.0.0.1 is printed as 1.0.0.127.

pfiles usage output is unhelpful

pfiles usage indicates to run with -h option:

delphix@ac60101:/opt/delphix/server/bin$ pfiles --help
Usage: pfiles [-h]

Running with the -h option just gives the usage again though:

delphix@ac60101:/opt/delphix/server/bin$ pfiles -h 
Usage: pfiles [-h]  

Unfortunately, there's no man page either:

delphix@ac60101:/opt/delphix/server/bin$ man pfiles No manual entry for pfiles See 'man 7 undocumented' for help when manual pages are not available. 

Even if there are no other options to the command, it still seems like a basic help message on the order of what pmap -h provides would be useful.