/etc/filetrace/config.toml. This page lists every section and key the file accepts, with its type, default and accepted range, explains how the file is found and how its values are written, and describes what filetrace config validate reports. It ends with a complete example file.
Location and precedence
The agent looks for its configuration in this order:- The file named with
--config <path>, onfiletrace-agentor as the global option offiletrace. - The file named by
$FILETRACE_CONFIG. /etc/filetrace/config.toml.
--config must exist and be readable; otherwise the agent and the commands stop with exit code 6. filetrace config path prints which file is read.
The command-line options of filetrace-agent (and of filetrace agent run, which passes the global --config and --socket on to the agent) override the file, wherever they stand on the command line:
The agent reads the file once, when it starts. A change takes effect after a restart:
[output] format), the [output] timestamps setting and the socket to reach the agent on ([agent] socket) from it; --socket and $FILETRACE_SOCKET take precedence over [agent] socket. When a command collects in the foreground because no agent is running (watch, events --follow), it uses the file’s collection settings and exports nothing. A file that does not parse stops every command except config and help with exit code 6.
File format
The file is a subset of TOML:[section]lines open a section; every setting belongs to the section above it.- Settings are
key = value, one per line.#starts a comment. - Strings are quoted with
"or'. Inside double quotes,\n,\t,\\and\"are understood. - Booleans are
trueandfalse. - Whole numbers may carry a sign and
_between digits (16_384). Numbers with a fraction are not accepted. - Lists hold strings only, may span several lines and may end with a comma. A list holds at most 32 entries.
- Nested tables, dotted keys and inline tables are not accepted.
- The file is at most 256 KB.
Value syntax
Sizes
A size is either a whole number of bytes or a quoted string of a number and a unit. Units are powers of 1024 and are not case-sensitive:
The number may have a fraction:
"1.5MB". A unit outside quotes is an error:
Durations
A duration is always a quoted string of a number and one of the unitsms, s, m, h or d (lower case): "250ms", "2s", "5m", "7d". The number may have a fraction: "0.5s". A bare number is an error.
Patterns
The entries of[filters] are patterns. * matches any run of characters, including /, and ? matches one character. A pattern matches the whole name or path, so /data/* matches every file under /data.
Validation
filetrace config validate checks a file and exits with 0 when the agent can use it and 6 when it cannot. Without an argument it checks the file the agent would read.
- a section or a key the file format does not know;
- a value of the wrong kind, such as a number where a string is expected, or a value outside its range;
- a setting before the first section, or text the parser cannot read;
- a file that cannot be read or is larger than 256 KB.
true is not an error: config validate reports the file as valid with a warning, printed on standard error, and the agent logs the same warning when it starts and otherwise ignores the setting. The same applies to [correlation] track_process_lifecycle = false.
Some values are checked only when the agent starts: an exporter address that is not of the accepted form stops the agent with exit code 6 (see [prometheus], [otlp] and [grpc]). The deb, rpm and apk packages run filetrace config validate before they restart a running agent on upgrade, and the OpenRC and SysV init scripts run it before every start.
filetrace config show prints every setting with the value in effect, in this file’s format. Without a file it prints the built-in defaults, which makes it a starting point for a first file:
[agent]
How the agent collects, where it listens, and how much memory its queues and event log take.boolean
default:"true"
With
false, the agent logs that it is not collecting and exits with code 0 right after reading the file.string
default:"standard"
minimal or standard. minimal records processes, sockets and network byte counts only. standard adds file identity and file-to-network attribution. The defaults of ring_buffer_size and event_log_size are smaller in minimal mode (see Mode-dependent defaults). Option: --mode.string
default:"auto"
auto, trampoline or kprobe. auto traces kernel functions through BPF trampolines where the kernel can attach them and through kprobes where it cannot. trampoline and kprobe select one of the two sets, and kprobe selects its set on any kernel. See Kernel instrumentation. Option: --probes.string
default:"/run/filetrace/agent.sock"
The local socket on which the agent answers queries, at most 103 characters. The commands connect to it unless
--socket or $FILETRACE_SOCKET names another. Option: --socket.size
default:"4MB"
The kernel-to-agent event queue, through which process and socket lifecycle events travel. From 64KB to 1GB; the agent rounds it up to a power of two. Events that do not fit are lost and counted as
event queue overflow. The default is 1MB in minimal mode. Option: --queue-size.integer
default:"512"
Counters read from the kernel per call, from 16 to 65536.
duration
default:"250ms"
How often the agent collects the byte counters from the kernel, from 10ms to 60s. Each
network_send, network_receive and file_transfer event covers one such interval. Option: --flush-interval.size
default:"1MB"
Memory for the log of recent events that
filetrace events reads: 0, or from 64KB to 256MB. 0 keeps no events, so only filetrace events --follow prints anything. The log is split into separate shares: half for transfer events (file_seen, file_transfer, event_loss), three eighths for socket and network events, one eighth for process events. The default is 256KB in minimal mode. Option: --event-log-size.string
default:"info"
error, warn, info or debug. Option: --log-level.[network]
Which traffic the agent records. A socket of a protocol or address family that is turned off is not listed, produces no events and carries no transfers.boolean
default:"true"
Record TCP sockets.
boolean
default:"true"
Record UDP sockets.
boolean
default:"true"
Record IPv4 sockets.
boolean
default:"true"
Record IPv6 sockets.
boolean
default:"false"
Not available in this build.
true is ignored with a warning: bytes are counted at the socket, not per packet.[file]
Which file operations the agent follows for attribution. Both settings take effect only while[correlation] enabled is true.
boolean
default:"true"
Follow reads of regular files, for read-write attribution (
INFERRED transfers).boolean
default:"true"
Follow
sendfile, for exact attribution (EXACT transfers).boolean
default:"false"
Not available in this build.
true is ignored with a warning: opens are not traced; a file is identified when it is read or sent.boolean
default:"false"
Not available in this build.
true is ignored with a warning: data read through memory mappings is not observed.boolean
default:"false"
Not available in this build.
true is ignored with a warning: transfers through pipes with splice are not followed.[correlation]
How a file is associated with the bytes a socket sends, and when an association is reported. File attribution and confidence explains the rules.boolean
default:"true"
File attribution as a whole.
false turns off both read and sendfile tracking, whatever [file] says.duration
default:"2s"
The longest gap between a thread’s read of a file and its send that still associates the two, from 1ms to 60s. Option:
--correlation-window.string
default:"inferred"
The lowest confidence a transfer needs to be reported:
inferred, strong or exact. exact reports sendfile transfers only. A transfer below the threshold is not listed by files or transfers and not counted in the metrics; its file_transfer events carry no confidence.size
default:"1KB"
A read-write association is reported once it covers at least this many bytes, from 0 to 1GB.
integer
default:"5"
A read-write association is reported once it also covers at least this percentage of what the thread read from the file, from 0 to 100.
filetrace stats counts the associations still below either threshold as candidates.boolean
default:"true"
Always on.
false is ignored with a warning: process lifetimes are always followed.boolean
default:"false"
Not available in this build.
true is ignored with a warning: descriptors are not followed; transfers are keyed on the kernel’s file and socket objects.boolean
default:"false"
Not available in this build.
true is ignored with a warning: file reads through io_uring are not observed.[storage]
boolean
default:"false"
true is ignored with a warning.string
default:"/var/lib/filetrace"
Accepted; has no effect.
duration
default:"7d"
From 1s to 3650d. Accepted; has no effect.
[limits]
The capacity of each bounded table, as a number of entries from 64 to 4194304. A full table forgets its least recently updated entry.filetrace stats shows the entries, capacity and evictions of the agent’s tables. Overhead and sizing covers the memory they take.
integer
default:"4096"
Processes the agent keeps.
integer
default:"16384"
Sockets the agent keeps.
integer
default:"16384"
Flows (one process’s traffic with one remote endpoint on a socket) the agent keeps.
integer
default:"16384"
Files the agent keeps.
integer
default:"16384"
Transfers the agent keeps.
integer
default:"16384"
Entries of the kernel table in which byte counts accumulate between two collections. Updates that do not fit are lost and counted as
counter table full.integer
default:"16384"
File identities the kernel remembers as already described to the agent.
integer
default:"2048"
Label sets of the exported counters. What exceeds it is summed into one series per metric marked
otel.metric.overflow="true".[output]
Defaults of the command-line interface.string
default:"table"
The default output format:
table, json, jsonl, csv or quiet. A command that does not offer the configured format prints a table. --format, --json and --jsonl override it. See Output formats.boolean
default:"true"
Whether the text output of
filetrace events starts each event with its time, and whether filetrace watch --no-ui heads each snapshot with its time.[filters]
What the agent leaves out entirely. Each list holds at most 32 patterns.list of strings
default:"[]"
Patterns matched against the process name, the kernel’s name for the process as in the
PROCESS column. The agent keeps nothing of a matching process: no process, socket, network or transfer records, no events and no metrics. ["filetrace-agent"] leaves the agent’s own traffic out.list of strings
default:"[]"
Patterns matched against a file’s full path. Transfers of a matching file are not recorded, and the file produces no
file_seen event. The bytes still count as network traffic of the socket that sent them.[prometheus]
A metrics page for Prometheus to scrape. See Prometheus.boolean
default:"false"
Serve the metrics page on
http://<listen>/metrics.string
default:"127.0.0.1:9464"
An address and port: an IPv4 address or
localhost, or an IPv6 address in brackets such as [::1]:9464. Host names and Unix sockets are not accepted. At most 63 characters. The page has no authentication. A value that is not an address and port stops the agent with exit code 6 when it starts, and an address the agent cannot listen on with exit code 8.[otlp]
Events and metrics pushed to an OpenTelemetry collector over OTLP/gRPC. See OpenTelemetry (OTLP).boolean
default:"false"
Run the OTLP exporter. It does not start when both
logs and metrics are false.string
default:"127.0.0.1:4317"
The collector: a numeric address and port (
127.0.0.1:4317, [::1]:4317; localhost stands for 127.0.0.1), or unix: followed by a socket path. Host names are not resolved. The agent speaks gRPC without TLS, so the endpoint is meant to be a collector on the same host. At most 107 characters. A value of another form stops the agent with exit code 6 when it starts.boolean
default:"true"
Send each event of the types in
events as an OTLP log record.boolean
default:"true"
Send the metrics.
list of strings
default:"[\"file_transfer\", \"event_loss\"]"
The event types sent as log records. Any type that
filetrace events knows is accepted; see Event types. An unknown name is an error.boolean
default:"true"
false leaves file paths out of the log records; device and inode remain.integer
default:"1024"
Records per export request, from 16 to 4096.
duration
default:"5s"
How often log records are sent, from 100ms to 1h. The bytes of one transfer, or of one socket and peer, that arrive within an interval are summed into a single record.
duration
default:"30s"
How often metrics are sent, from 1s to 1h. Values are cumulative since the agent started.
duration
default:"10s"
The deadline of each export request, from 1s to 300s.
[grpc]
An API that lists and streams transfers. See gRPC API guide.boolean
default:"false"
Serve the gRPC API.
string
default:"unix:/run/filetrace/api.sock"
unix: followed by a socket path, or a numeric address and port such as 127.0.0.1:9500. At most 107 characters. A unix: socket admits only root and the agent’s user. An address and port admits whoever can connect, and the agent logs a warning saying so when it starts. A value of another form stops the agent with exit code 6.Mode-dependent defaults
Minimal mode queues only process and socket events, so two defaults are smaller. They apply only when neither the file nor the command line sets the value.Example
This file sets every key this build honours. It keeps the defaults except that it leaves the agent’s own traffic and the/proc and /sys pseudo-filesystems out, and turns on all three telemetry interfaces.