Filetrace command-line interface

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

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.

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.

boolean

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

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.

Using the CLI

Monitoring commands

Agent and system

Filetrace command-line interface

Synopsis

Global options

Environment variables

Running filetrace without a command

Commands

Privileges

Getting help

Exit codes

Command reference

watch

files

transfers

processes

connections

flows

top

events

inspect

agent

filetrace-agent

stats

doctor

capabilities

config

version

​Synopsis

​Global options

​Environment variables

​Running filetrace without a command

​Commands

​Privileges

​Getting help

​Exit codes

​Command reference

watch

files

transfers

processes

connections

flows

top

events

inspect

agent

filetrace-agent

stats

doctor

capabilities

config

version

Synopsis

Global options

Environment variables

Running filetrace without a command

Commands

Privileges

Getting help

Exit codes

Command reference