Filetrace command-line interface

Synopsis, global options, environment variables, the command list, the privileges each command needs and how to get help for the filetrace command.

filetrace is the command-line interface to Filetrace. Most commands ask the running agent (filetrace-agent) over a local socket and print what it has observed; a few check the machine or the configuration without an agent. This page covers what all commands share: the synopsis, the global options and environment variables, the privileges they need and how to get help.

​

Synopsis

filetrace [--socket <path>] [--config <path>] <command> [options]

Global options go before the command. Every option that takes a value accepts it as the next argument or after an equals sign, so --since 1h and --since=1h are the same.

​

Global options

--socket · string · default: "/run/filetrace/agent.sock"

Path of the agent socket to connect to. Without this option, the command uses $FILETRACE_SOCKET, then the [agent] socket setting of the configuration file, then the default. The macOS build, which has no collection, uses /var/run/filetrace/agent.sock as its default.

--config · string · default: "/etc/filetrace/config.toml"

Configuration file to read. The commands take their default output format and the agent socket from it. A file named with this option must exist; see config.

-h, --help · boolean

Print the overview of commands and options. After a command, print that command’s help.

--version · boolean

Print version and build information, the same as filetrace version.

​

Environment variables

Variable	Effect
FILETRACE_SOCKET	Agent socket to connect to. --socket takes precedence over it, and it takes precedence over the configuration file.
FILETRACE_CONFIG	Configuration file to read instead of /etc/filetrace/config.toml. --config takes precedence over it. If the file does not exist, the built-in defaults apply.
NO_COLOR	Any non-empty value turns off colors and bold text.
TERM	The value dumb turns off colors and bold text.

Output that does not go to a terminal is never styled.

​

Running filetrace without a command

filetrace alone reports whether an agent is serving the socket and lists the commands. With an agent running, the status line names the backend, the probe set and the mode, followed by the number of active transfers and processes, the outbound rate and the share of events the agent received without loss:

sudo filetrace

Filetrace - File-to-Network Observability

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

Main commands:
  watch         Live monitoring
  files         File transfers
  processes     Process activity
  connections   Network connections
  flows         Network flow details
  inspect       Inspect a file, process, socket, flow or address
  events        Raw events
  stats         Agent statistics
  doctor        System diagnostics
  config        Show or validate the configuration
  version       Version and build information

More commands:
  top           Highest-volume processes, files or destinations
  transfers     Transfer records, with unattributed bytes
  capabilities  Supported features
  agent         Run or control the background agent
  help          Help for a command

See 'filetrace help' for the options, and 'filetrace help <command>' for a
command's own.

Without an agent, the status line says how to start collecting:

○ NOT RUNNING   'sudo filetrace watch' collects for as long as it runs;
                'sudo filetrace agent run' collects in the background

When an agent is running but its socket is not accessible to your user, the status line says RUNNING and asks you to use sudo. The command exits with 0 in every case.

​

Commands

The help lists the commands in two groups. The main commands cover everyday work:

Command	Shows
watch	Live view of the file transfers in progress, with process, destination, method and rate
files	Files associated with network transfers
processes	Outbound rate, files sent and open connections per process
connections	Open and recently closed sockets, by their local and remote ends
flows	Bytes per process, socket and remote endpoint
inspect	Everything known about one file, process, socket, flow or address
events	The agent’s records in the order they were made
stats	The agent’s own events, losses, CPU, memory and table usage
doctor	Whether this machine can be monitored: kernel, every probe, features, pipeline
config	The configuration in effect; validates a file
version	Version, build and platform

More commands:

Command	Shows
top	Highest-volume processes, files, destinations or connections
transfers	Transfer records, including sent bytes that no file accounts for
capabilities	Each feature as FULL, PARTIAL, UNAVAILABLE or DISABLED, with the reason
agent	Run the agent in the foreground, report its status or stop it
help	The overview, or the help of one command

The agent itself is a separate program, filetrace-agent.

​

Privileges

Only the agent needs the privileges to load BPF programs. The agent creates its socket so that only its owner can open it, and accepts connections only from root and from the user it runs as. When the agent runs as root, as the packaged service does, every command that queries it needs sudo:

sudo filetrace files

A command that cannot open the socket reports Permission denied and exits with 3.

When no agent is serving the socket, the query commands exit with 4 and say how to start one:

filetrace --socket /run/filetrace/agent.sock files

The Filetrace agent is not running (/run/filetrace/agent.sock: No such file or directory).

Start it with:
  sudo filetrace agent run

To check what this machine supports:
  sudo filetrace doctor

Two commands collect on their own instead: watch and events --follow start a collector in the foreground for as long as they run when no agent is running. Such a collector needs the same privileges as the agent, uses the [agent] settings of the configuration file, shows only activity from the moment it starts and exports nothing.

Some commands do not need an agent at all:

Command	Without an agent
doctor	Checks the machine directly; loading the probes needs root, or CAP_BPF with CAP_PERFMON
capabilities	Checks the machine directly, with the same privileges as the agent
config	Reads the configuration file only
version	Reports Not running for the agent

The command and the agent speak one protocol version. If they differ, the command reports that the agent speaks a different protocol version; upgrade filetrace and filetrace-agent together.

​

Getting help

filetrace help prints the overview of commands and global options. filetrace help <command> prints a command’s usage, options, examples and exit codes:

filetrace help files

-h or --help anywhere among a command’s arguments does the same, so filetrace files --since 1h --help prints the help of files. The exception is filetrace agent run --help, which prints the help of the agent itself.

​

Exit codes

The commands share one set of exit codes:

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Permission denied
4	Agent unavailable
5	Unsupported platform or capability
6	The configuration file cannot be read or is invalid
9	Partial results: events were lost in the queried time range

With code 9 the output is still printed; a warning on standard error gives the number of lost events and the affected time window, so standard output stays parseable. doctor, config and agent status give some codes a meaning of their own. Exit codes lists them all.

​

Command reference

watch

Live view of the transfers in progress.

files

Files associated with network transfers.

transfers

Transfer records, with unattributed bytes.

processes

Network activity per process.

connections

Open and recently closed sockets.

flows

Bytes per process, socket and remote endpoint.

top

Highest-volume processes, files, destinations or connections.

events

The agent’s records in order, past or live.

inspect

One file, process, socket, flow or address from every side.

agent

Run the agent, report its status or stop it.

filetrace-agent

The agent program and its options.

stats

The agent’s own events, losses and resources.

doctor

Whether and how well this machine can be monitored.

capabilities

Each feature and its status, with the reason.

config

Show, validate or locate the configuration file.

version

Version, build and platform information.

Filters and output formats describe the options that the listing commands share.