Get started with Filetrace

This quickstart takes a Linux machine from nothing to its first answer: you install Filetrace, check that the kernel supports it, start the agent, and list the files that processes send over the network. You need root access and Linux 6.1 or later.

Install Filetrace

The installer sets up the package repository that fits the system (apt, dnf, yum, zypper or apk), installs the filetrace package and starts the filetrace-agent service.

curl -fsSL https://filetrace.eorlov.org/install.sh | sudo sh

To install without starting the service, append -s -- --no-start. Installation covers manual repository setup, Homebrew and release archives.

Check the kernel

filetrace doctor loads and attaches every probe, reports what the kernel accepted, and removes the probes again.

sudo filetrace doctor

The report ends with a status line. STATUS: READY means every probe is attached:

PROBES
  [OK] tracepoint sched_process_exec
  [OK] tracepoint inet_sock_set_state
  [OK] fexit inet_sendmsg
  [OK] fexit vfs_read
  [OK] fexit do_splice_direct
  ...

STATUS: READY

Any other status is explained in Troubleshooting.

Make sure the agent is running

Run filetrace without arguments. It reports whether the agent is running and which probe set it uses:

sudo filetrace

● RUNNING   Linux eBPF (trampolines), standard mode
  0 active transfers   0 processes   0 B/s outbound   100.0% of events delivered

If it reports NOT RUNNING, start the service with sudo systemctl enable --now filetrace-agent, or run the agent in the foreground with sudo filetrace agent run.

Watch transfers live

The live view lists the file transfers in progress with their process, destination, method, rate and confidence. Press q to quit.

sudo filetrace watch

ACTIVE FILE TRANSFERS
PROCESS      FILE                         DESTINATION    METHOD           RATE  CONFIDENCE
nginx 1245   /var/www/stream.bin          203.0.113.25   sendfile    6.67 MB/s  EXACT
nginx 1245   /var/www/video.mp4           198.51.100.10  sendfile        0 B/s  EXACT
python 892   /data/export/customers.csv   203.0.113.50   read-write      0 B/s  INFERRED

Ask about what happened

The agent keeps a bounded history in memory from the moment it started. List the files that were sent, then look at one of them from every side:

sudo filetrace files --since 1h
sudo filetrace inspect file /var/www/video.mp4

TRANSFER HISTORY
────────────────────────────────────
TIME                 PROCESS  PID   REMOTE               BYTES    METHOD    CONFIDENCE
2026-11-11 12:00:04  nginx    1245  198.51.100.10:48175  47.7 MB  sendfile  EXACT

Next steps

Find who sends a file

Go from a file path to the processes and addresses involved.

Investigate an address

Go from a remote address or network to the files sent to it.

Understand confidence

Learn what EXACT, INFERRED and UNKNOWN rest on.

Export telemetry

Send metrics and events to Prometheus or OpenTelemetry.

Get started

Concepts

Guides

Get started with Filetrace

Next steps

Find who sends a file

Investigate an address

Understand confidence

Export telemetry

​Next steps

Find who sends a file

Investigate an address

Understand confidence

Export telemetry

Next steps