tinytap on tinytap docs

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

Install#

curl -fsSL https://raw.githubusercontent.com/shinagawa-web/tinytap/main/scripts/install.sh | sh

Run#

Grant it the capabilities it needs, then run it (no full root required):

sudo setcap cap_dac_read_search,cap_perfmon,cap_bpf,cap_sys_admin,cap_syslog=eip $(command -v tinytap)
tinytap

That’s the full set: plaintext HTTP and HTTPS (via the libssl uprobes, cap_sys_admin) both work out of the box. See Running Without Full Root if you want the smaller plaintext-only set instead, or a breakdown of what each capability actually covers.

With no config file, that opens the TUI (j/k to scroll, Enter for the detail panel, q or Ctrl-C to quit) as long as your terminal is at least 120x24. In a smaller or non-interactive terminal it prints guidance and exits instead of silently streaming; see Configuration to switch to the line-oriented stdout mode.

Use Cases

Mon, 01 Jan 0001 00:00:00 +0000

Use Cases#

tinytap attaches to a process’s socket syscalls and libssl uprobes and decodes what it sees as HTTP/1.1; see How It Works for the mechanism. That gives it a few concrete uses beyond “watch traffic go by.”

See exactly what your app sent, including over HTTPS#

An app makes an HTTPS call and you need to know precisely what went out: the request line, every header (including Authorization), the JSON body as sent. Normally that means a proxy (mitmproxy, Charles) with a CA certificate installed in the app’s trust store, which is extra setup and doesn’t work at all against apps that pin certificates.

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Usage#

Quick Start gets tinytap running. This page covers what to do once it’s up: reading the TUI, reading the stdout JSONL format, and when to reach for doctor.

TUI#

output = "auto" (the default) opens the TUI whenever stdout/stdin are an interactive terminal of at least 120x24. See Configuration to force it with output = "tui" or opt out with output = "stdout".

Request table#

Every captured exchange is a row: timestamp, process[pid], method, path, status, response size, latency. New rows arrive at the bottom; the view follows the newest row automatically until you scroll away from it.

Where tinytap Runs

Mon, 01 Jan 0001 00:00:00 +0000

Where tinytap Runs#

tinytap requires a Linux kernel. It cannot run natively on macOS or Windows, because eBPF is a Linux kernel technology. But that’s less restrictive than it sounds, because Linux kernels are everywhere:

Where the user works	How tinytap runs there
Linux (desktop, laptop, workstation, or server)	Native. Just run the binary.
Mac (Intel or Apple Silicon)	Inside a Linux VM (Docker Desktop’s VM, OrbStack, Lima, UTM, Multipass, etc.).
Windows	Inside WSL2 (which is a real Linux kernel).

Does tinytap see inside containers?#

A common question: “if my dev stack runs in Docker on my Mac, can tinytap see inside the containers?”

Running Without Full Root

Mon, 01 Jan 0001 00:00:00 +0000

Running Without Full Root#

sudo ./tinytap is the simplest path, but tinytap doesn’t need full root.

The minimal set#

Plaintext HTTP capture (syscall tracepoints, ringbuf) needs three capabilities on every architecture, on a 5.11+ kernel. On an older kernel (5.8–5.10, still within tinytap’s documented floor) a fourth capability, cap_sys_resource, is additionally needed. See Why cap_sys_resource turned out not to matter below for why:

sudo setcap cap_dac_read_search,cap_perfmon,cap_bpf=eip ./tinytap
./tinytap # no sudo

That’s enough for the core capture path everywhere, and for the optional sendfile payload-capture kprobe on arm64, but not for that same kprobe on x86_64, which additionally needs cap_syslog (see the table below). Its failure degrades gracefully either way (sendfile events just carry no payload bytes), so this only matters if you want full-fidelity sendfile capture on x86_64:

How It Works

Mon, 01 Jan 0001 00:00:00 +0000

How It Works#

tinytap attaches eBPF probes to a process’s socket syscalls (accept4/read/write/close/recvfrom/sendto/recvmsg/sendmsg), parses the payload bytes as HTTP/1.1, pairs each request with its response, and renders the exchange live, either in the terminal TUI or as JSONL (one JSON object per exchange) on stdout:

{"reqTsNs":1754887677005000000,"latencyNs":300000,"pid":27122,"comm":"python3","method":"GET","path":"/","status":200,"resBytes":1304,"abandoned":false,...}

output = "auto" (the default) picks the TUI when stdout/stdin are an interactive terminal of at least 120x24; otherwise it prints guidance and exits rather than silently streaming; the JSONL stream is opt-in via output = "stdout". output = "tui" forces the TUI (and exits the same way if the terminal can’t host it). --version prints the build’s version, commit, and date, and exits without needing root.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Session settings (output and process filters) live in a TOML config file, not CLI flags. tinytap config init && tinytap just works. See config init in CLI surface below.

CLI surface#

The only CLI surface is one-shot actions, not session settings:

Flag / command	What it does
`--config <path>`	Point at an alternate config file
`--version`	Print build metadata, exiting before any eBPF load
`config init`	Write a fully-populated default config file
`doctor`	Read-only preflight checks (see Troubleshooting)

Search order and defaults#

Search order when --config <path> isn’t given: ./tinytap.toml, then $XDG_CONFIG_HOME/tinytap/config.toml (falling back to ~/.config/tinytap/config.toml). Finding neither is not an error, and the defaults below apply.

Server Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

Server Compatibility#

Which syscall a plaintext HTTP server uses to send its response body determines how much of it tinytap can see.

Compatibility table#

See Cross-server summary below for what each syscall means for visibility in practice.

Server	Syscall	Notes
Python `http.server`	`sendto`	Headers and body go out as separate `sendto` calls, no chunking
Go `net/http`	`write` / `sendfile`	`write` for small bodies, `sendfile` above ~512 B
Node.js `http.createServer`	`writev`	Chunked encoding when `Content-Length` is unknown
nginx (static, `sendfile on`)	`writev` + `sendfile`	Default nginx config
nginx (static, `sendfile off`)	`writev`	Body lives in `iovec[1+]`
nginx (reverse proxy)	`writev`	`proxy_pass` never touches `sendfile`
Caddy	`write` / `sendfile`	Same syscall shape as Go `net/http`
Bun.serve	`sendto`	No `sendfile` despite `Bun.file()`
Uvicorn (ASGI)	`sendto`	Same shape as Python `http.server`
Gunicorn (WSGI)	`sendto`	Same shape as Python `http.server`/Uvicorn
Axum (Rust / hyper)	`writev`	`Content-Length` always known, no chunking

Cross-server summary#

Across every server row in the table above, the outgoing syscall shape falls into one of three groups, not based on language or performance but on what each project treats as its core use case:

TLS Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

TLS Compatibility#

Which TLS-terminating servers/clients tinytap can capture via the SSL_write/SSL_read/SSL_free libssl uprobes, a separate mechanism from the Server Compatibility sample-cap table. The uprobe reads the plaintext buffer directly (up to its own 4096 B cap) before encryption or after decryption, rather than sampling wire bytes off the ciphertext syscalls underneath.

What’s covered#

tinytap has been verified against Python ssl-wrapped http.server, nginx (Debian-based and Alpine-based images), curl, and Node.js (NodeSource, official, and nvm builds): TLS traffic decrypts and pairs correctly for all of them. This only covers OpenSSL-based stacks; see Current Limitations for what’s not covered, such as Go’s crypto/tls.

Platform Support

Mon, 01 Jan 0001 00:00:00 +0000

Platform Support#

Which Linux distributions and kernel versions tinytap has been verified on. Every row in the table below is a real test run. Untested combinations are not listed.

arm64#

Distro	Kernel	Plaintext	TLS	Notes
Ubuntu 25.10	6.17.0-41-generic	✓	✓
Ubuntu 24.04	6.8.0	✓	✓
Ubuntu 22.04	5.15.0	✓	✓	sendfile body not captured (`BPF_PROG_TYPE_TRACING` not available in this kernel config)
Fedora 43	6.17.1	✓	✓
Debian 12	6.1.0	✓	✓	sendfile body not captured; `cap_sys_admin` required even for plaintext
AlmaLinux 9	5.14.0 (RHEL)	✓	✓	sendfile body not captured
Alpine 3.23	6.18.22-virt	✓	✓	sendfile body not captured; static binary required
Ubuntu 20.04 (GA kernel)	5.4.0	✗	✗	kernel 5.8+ required

amd64#

Distro	Kernel	Plaintext	TLS	Notes
Ubuntu 26.04	7.0.0	✓	✓	sendfile body requires `cap_syslog` (`kptr_restrict=1` blocks kprobe symbol lookup without it)
Fedora 43	6.17.1	✓	✓
Debian 12	6.1.0	✓	✓	`cap_sys_admin` required even for plaintext (`perf_event_paranoid=3`)
Ubuntu 24.04	6.17.0-azure	✓	✓
Ubuntu 22.04	6.8.0-azure	✓	✓

“sendfile body not captured” means GET /file.bin returns status and size correctly but body bytes are 0. Only static file serving via sendfile(2) is affected. All other capture paths work normally. See Server Compatibility.

Installing & Verifying Releases

Mon, 01 Jan 0001 00:00:00 +0000

Installing & Verifying Releases#

Installing a specific version or location#

Two env vars change the install script’s behavior. Set them on the sh side of the pipe, not before curl, since a VAR=val curl ... | sh prefix only reaches curl, not the piped-in script:

curl -fsSL https://raw.githubusercontent.com/shinagawa-web/tinytap/main/scripts/install.sh | TINYTAP_VERSION=v0.6.1 sh # pin a release instead of the latest
curl -fsSL https://raw.githubusercontent.com/shinagawa-web/tinytap/main/scripts/install.sh | INSTALL_DIR=~/bin sh # install somewhere other than /usr/local/bin

Verifying a release download#

The install script already verifies the downloaded archive’s SHA-256 checksum automatically. This section is for downloading a release archive by hand instead (from the releases page or in a script that intentionally avoids curl | sh) and confirming its full chain of trust, including the cosign signature the install script doesn’t check.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting#

If it didn’t work, run tinytap doctor first: read-only preflight checks (kernel version, BTF availability, the required capabilities, syscall tracepoint availability, a dry-run BPF load, and the host’s libssl execute bit), printed as a copy-paste-friendly report, without needing root or capabilities itself:

tinytap doctor

For example, on a host that hasn’t been granted any capabilities yet:

tinytap doctor — tinytap dev (commit none, built unknown)

[OK ] kernel version 6.17.0-41-generic (>= 5.8 required)
[OK ] kernel BTF /sys/kernel/btf/vmlinux present
[BLOCKING] cap_dac_read_search missing
 Affects: Everything — needed to open /sys/kernel/tracing/events/syscalls/*/id to resolve tracepoint IDs.
 Fix: sudo setcap cap_dac_read_search,cap_perfmon,cap_bpf,cap_sys_admin,cap_syslog=eip <path-to-tinytap> # adds cap_dac_read_search
[BLOCKING] cap_perfmon missing
 Affects: Everything — needed to attach the tracepoint/kprobe/fentry programs.
 Fix: sudo setcap cap_dac_read_search,cap_perfmon,cap_bpf,cap_sys_admin,cap_syslog=eip <path-to-tinytap> # adds cap_perfmon
[BLOCKING] cap_bpf missing
 Affects: Everything — needed to load BPF programs and maps.
 Fix: sudo setcap cap_dac_read_search,cap_perfmon,cap_bpf,cap_sys_admin,cap_syslog=eip <path-to-tinytap> # adds cap_bpf
[DEGRADED] cap_sys_admin missing
 Affects: TLS capture only. Plaintext HTTP capture is unaffected.
 Fix: sudo setcap cap_dac_read_search,cap_perfmon,cap_bpf,cap_sys_admin,cap_syslog=eip <path-to-tinytap> # adds cap_sys_admin
[OK ] cap_syslog not needed on arm64
[INFO ] perf_event_paranoid 4
[INFO ] unprivileged_bpf_disabled 2
[INFO ] RLIMIT_MEMLOCK soft=8388608 hard=8388608
[OK ] syscall tracepoints all 16 present
[OK ] architecture arm64 (sendfile kprobe + TLS uprobes supported)
[BLOCKING] BPF dry-run load remove memlock: failed to set memlock rlimit: operation not permitted
 Affects: Everything — this is the first step tinytap's real startup performs.
 Fix: run with the capabilities listed at https://shinagawa-web.github.io/tinytap/docs/running-without-root/, or as root
[OK ] libssl (host) /lib/aarch64-linux-gnu/libssl.so.3 executable

6 ok, 1 degraded, 4 blocking, 3 info

Granting the capabilities named in each Fix line (see Running Without Full Root) turns every BLOCKING/DEGRADED line above into OK.

Terminology

Mon, 01 Jan 0001 00:00:00 +0000

Terminology#

These terms appear throughout the docs, the code, and the issue tracker. They are deliberately process-relative, since “from whose point of view?” matters.

Term	Meaning
Outgoing syscall	A syscall that writes data out of a process address space: `write`, `sendto`, `sendmsg`, `writev`. The user buffer is already populated at `sys_enter`, so the payload can be sampled on entry.
Incoming syscall	A syscall that reads data into a process address space: `read`, `recvfrom`, `recvmsg`, `readv`. The user buffer is empty at `sys_enter`: the kernel fills it during the syscall, so the payload is only observable at `sys_exit` (with the return value telling us how much was actually filled).
send-side / receive-side	Synonyms for outgoing / incoming, common in libbpf and Pixie writing. Acceptable once a paragraph has already grounded the direction; avoid as the first mention because they sound like they refer to the protocol direction (request vs response) when they actually refer to the syscall family.

Protocol mapping (HTTP)#

tinytap is process-oriented, not protocol-aware. The same syscall carries the request on one side and the response on the other depending on who is calling it:

Current Limitations

Mon, 01 Jan 0001 00:00:00 +0000

Current Limitations#

HTTP/1.1 only#

No HTTP/2, gRPC, or other protocols yet.

TLS capture needs OpenSSL#

TLS capture needs OpenSSL to be reachable: either a dynamically linked libssl.so, or (confirmed for Node.js’s official/NodeSource/nvm builds) an unstripped binary that statically bundles OpenSSL and still exports its symbols. Stacks that don’t use OpenSSL at all remain invisible either way, which includes Go’s crypto/tls and therefore Go-based proxies like Traefik and Caddy. Clients that hand OpenSSL a custom BIO instead of calling SSL_set_fd (e.g. curl) are captured and paired, but keyed on the SSL* pointer rather than a socket fd, so their exchanges are marked [ssl-keyed, fd unverified]. See TLS Compatibility

Internals

Mon, 01 Jan 0001 00:00:00 +0000

Internals#

How eBPF and tinytap actually get the payload bytes: the three kernel-side observation points, the ring buffer design constraints that shaped them, and the libssl uprobe mechanism that decrypts TLS traffic. This page stops at capture; see How It Works for the eBPF background and build pipeline, and Usage for the JSONL shape the captured bytes end up in.

One picture#

┌──────────────────────────── kernel ─────────────────────────────┐
│ │
│ [A] tracepoint/syscalls/sys_{enter,exit}_* │
│ bpf/tinytap.bpf.c ────────────► ringbuf events (8 MiB)
│ accept4 read write close recvfrom sendto │
│ recvmsg sendmsg writev readv sendfile64 │
│ ▲ │
│ │ hash sendfile_sample_map (tid → 4096 B) │
│ │ │
│ [B] fentry/tcp_sendmsg_locked │
│ bpf/tinytap_kprobe.bpf.c (sendfile's body, read straight │
│ off the page cache, before it │
│ ever reaches a socket buffer) │
│ │
│ [C] uprobe/uretprobe on libssl.so │
│ bpf/tinytap_uprobe.bpf.c ────────────► ringbuf ssl_events (1 MiB)
│ SSL_write / SSL_read / SSL_set_fd / SSL_free │
│ ────────────► hash ssl_fd_map │
└────────────────────────────────────────────────────────────────┘
 │ events.Decode │ events.DecodeSSL
 ▼ ▼
 capture() (main pipeline) captureTLS() (one pair per pid)

Three independent observation points converge on the same downstream pipeline. It decodes the ring buffer record, feeds it to the HTTP parser, and pairs request with response. TLS support added a new entry point, not a second capture engine.