UNIX domain socket tracing LD_PRELOAD wrapper, mirror from git://git.gnumonks.org/udtrace
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
titan
.gitignore
COPYING
Makefile
README.md
hooks.c
libc_overrides.c
sock_events.c
sock_events.h
utils.c
utils.h

README.md

udtrace - Unix Domain socket tracing

This is a LD_PRELOAD wrapper library which can be used to trace the data sent and/or received via unix domain sockets.

Unlike IP based communication that can be captured/traced with pcap programs like tcpdump or wireshark, there is no similar mechanism available for unix domain sockets.

This LD_PRELOAD library intercepts the C library function calls of dynamically linked programs. It will detect all file descriptors representing unix domain sockets and will then print traces of all data sent/received via the socket.

Usage

Simply build libudtrace.so using the make command, and then start your to-be-traced program with

LD_PRELOAD=libudtrace.so

e.g.

LD_PRELOAD=libudtrace.so systemctl status

which will produce output like this:

UDTRACE: Unix Domain Socket Trace initialized (TITAN support DISABLED) UDTRACE: Adding FD 4 UDTRACE: connect(4, "/run/dbus/system_bus_socket") 4 sendmsg W 00415554482045585445524e414c20 4 sendmsg W 3331333033303330 4 sendmsg W 0d0a4e45474f54494154455f554e49585f46440d0a424547494e0d0a [...]

Output Format

Currently, udtrace will produc the following output:

At time a FD for a unix domain socket is created:

UDTRACE: Adding FD 8

At time a FD for a unix domain socket is closed:

UDTRACE: Removing FD 8

At time a FD for a unix domain socket is bound or connected:

UDTRACE: connect(9, "/tmp/mncc")

When data is read from the socket:

9 read R 00040000050000004403000008000000680000001c0300002c03000000000000

When data is written to the socket:

9 write W 00040000050000004403000008000000680000001c0300002c03000000000000

Where

  • 9 is the file descriptor on which the event happened
  • read/write is the name of the syscall, could e.g. also be sendmsg / readv / etc.
  • R|W is Read / Write (from the process point of view)
  • followed by a hex-dump of the raw data. Only data successfully written (or read) will be printed, not the entire buffer passed to the syscall. The rationale is to only print data that was actually sent to or received from the socket.

TITAN decoder support

Getting hex-dumps is nice and fine, but normally one wants to have a more detailed decode of the data that is being passed on the socket.

For TCP based protocols, there is wireshark. But most protocols on unix domain sockets don't follow inter-operable / public standards, so even if one was to pass the traces into wireshark somehow, there would be no decoder.

In the Osmocom project, we already had some type definitions and decoders for our protocols written in the TTCN-3 programming language, using Eclipse TITAN. In order to build those decoders fro MNCC and PCUIF, please use

make ENABLE_TITAN=1

when building the code.

Please note that this introduces a run-time dependency to libttcn3-dynamic.so, which is (at least on Debian GNU/Linux) not installed in a default library search path, so you will have to use something like:

LD_LIBRARY_PATH=/usr/lib/titan LD_PRELOAD=libudtrace.so systemctl status

Related Work

stealth had implemented a kernel-based unix domain tracer in 2009, which you can find in http://www.suse.de/%7Ekrahmer/unixdump-0.42.tgz

While fundamentally, a kernel based tracer is much superior to the LD_PRELOAD approach of udtrace, I think there's little use of it if it's not merged into the mainline kernel, and hence available with stock distributions, as well as maintained for all kernel internal API changes.