Skip to content

README.template.md

Latest commit

 

History

History
217 lines (136 loc) · 7.43 KB

README.template.md

File metadata and controls

217 lines (136 loc) · 7.43 KB
Raw

tracexec

A small utility for tracing execve{,at} and pre-exec behavior.

tracexec helps you to figure out what and how programs get executed when you execute a command.

It's useful for debugging build systems, understanding what shell scripts actually do, figuring out what programs does a proprietary software run, etc.

Showcases

Perfetto Trace Export

tracexec supports exporting exec traces to perfetto trace format, which could be viewed in the Perfetto UI. The trace follows a tree format in the UI, where processes resulting from successful execs are represented as slices and exec failures are represented as instant events.

The following video shows analyzing the build process of tracexec with itself:

tracexec-pftrace.webm

The shape of the traces in the Perfetto UI could give you a rough idea of how parallel the build is at process-level. The trace tree and details of slices enable identification of bottlenecks, troubleshooting, and a deep understanding of how the build works.

Start collecting a perfetto trace with the following command:

tracexec collect --format=perfetto -o out.pftrace -- cmd

TUI mode with pseudo terminal

In TUI mode with a pseudo terminal, you can view the details of exec events and interact with the processes within the pseudo terminal at ease.

TUI demo

Tracing setuid binaries

With root privileges, you can also trace setuid binaries and see how they work. But do note that this is not compatible with seccomp-bpf optimization so it is much less performant. You can use eBPF mode which is more performant in such scenarios.

sudo tracexec --user $(whoami) tui -t -- sudo ls

Tracing sudo ls

Nested setuid binary tracing is also possible: A real world use case is to trace extra-x86_64-build(Arch Linux's build tool that requires sudo):

Tracing extra-x86_64-build

In this real world example, we can easily see that _FORTIFY_SOURCE is redefined from 2 to 3, which lead to a compiler error.

Use tracexec as a debugger launcher

tracexec can also be used as a debugger launcher to make debugging programs easier. For example, it's not trivial or convenient to debug a program executed by a shell/python script(which can use pipes as stdio for the program). The following video shows how to use tracexec to launch gdb to detach two simple programs piped together by a shell script.

gdb-launcher.mp4

Please read the gdb-launcher example for more details.

eBPF mode

Please check platform support status before using the eBPF backend.

The following examples shows how to use eBPF in TUI mode. The eBPF command also supports regular log and collect subcommands.

System-wide Exec Tracing

sudo -E tracexec ebpf tui
ebpf-system-wide-tui.webm

Follow Fork mode with eBPF

sudo -E tracexec --user $(whoami) ebpf tui -t -- bash
ebpf-follow-forks.webm

Log mode

In log mode, by default, tracexec will print filename, argv and the diff of the environment variables and file descriptors.

example: tracexec log -- bash (In an interactive bash shell)

asciicast

Reconstruct the command line with --show-cmdline

$ tracexec log --show-cmdline -- <command>
# example:
$ tracexec log --show-cmdline -- firefox

asciicast

Try to reproduce stdio in the reconstructed command line

--stdio-in-cmdline and --fd-in-cmdline can be used to reproduce(hopefully) the stdio used by a process.

But do note that the result might be inaccurate when pipes, sockets, etc are involved.

tracexec log --show-cmdline --stdio-in-cmdline -- bash

asciicast

Show the interpreter indicated by shebang with --show-interpreter

And show the cwd with --show-cwd.

$ tracexec log --show-interpreter --show-cwd -- <command>
# example: Running Arch Linux makepkg
$ tracexec log --show-interpreter --show-cwd -- makepkg -f

asciicast

Usage

General CLI help:

%{general}

TUI Mode:

%{tui}

Log Mode:

%{log}

Collect and export data:

%{collect}

eBPF backend supports similar commands:

%{ebpf}

Profile

tracexec can be configured with a profile file. The profile file is a toml file that can be used to set fallback options.

The profile file should be placed at $XDG_CONFIG_HOME/tracexec/ or $HOME/.config/tracexec/ and named config.toml.

A template profile file can be found at https://github.com/kxxt/tracexec/blob/main/config.toml

As a warning, the profile format is not stable yet and may change in the future. You may need to update your profile file when upgrading tracexec.

TUI themes can be configured in the tui section of the profile in one of two ways:

[tui]
theme-file = "nord.toml"

theme-file accepts either an absolute path or a path relative to the theme directories. Relative paths are resolved relative to the following absolute paths in order:

  1. $XDG_CONFIG_HOME/tracexec/themes/ (or $HOME/.config/tracexec/themes/)
  2. $XDG_DATA_HOME/tracexec/themes/ (or $HOME/.local/share/tracexec/themes/)
  3. /etc/tracexec/themes
  4. <path_to_tracexec_binary>/../share/tracexec/themes/

You can also inline the theme definition directly in the profile. Theme entries patch the built-in default theme, so you only need to specify the parts you want to change.

[tui]
theme = { app-title = { fg = "cyan" }, active-border = { fg = "light-cyan" } }

Example themes are available in the repository's themes/ directory.

Known issues

Origin

This project was born out of the need to trace the execution of programs.

Initially I simply use strace -Y -f -qqq -s99999 -e trace=execve,execveat <command>.

But the output is still too verbose so that's why I created this project.

Credits

This project takes inspiration from strace and lurk.