> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration file reference

> Every section and key of /etc/filetrace/config.toml with its type, default and accepted range, plus file precedence, value syntax and validation.

The agent reads its settings from one TOML file, `/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:

1. The file named with `--config <path>`, on `filetrace-agent` or as the global option of `filetrace`.
2. The file named by `$FILETRACE_CONFIG`.
3. `/etc/filetrace/config.toml`.

When no file exists at the default location, the built-in defaults apply. A file named with `--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:

| Option | Overrides |
| - | - |
| `--socket <path>` | `[agent] socket` |
| `--mode <mode>` | `[agent] mode` |
| `--probes <kind>` | `[agent] probes` |
| `--flush-interval <time>` | `[agent] flush_interval` |
| `--queue-size <size>` | `[agent] ring_buffer_size` |
| `--event-log-size <size>` | `[agent] event_log_size` |
| `--correlation-window <time>` | `[correlation] window` |
| `--log-level <level>` | `[agent] log_level` |

The agent reads the file once, when it starts. A change takes effect after a restart:

```bash systemd theme={null}
sudo filetrace config validate && sudo systemctl restart filetrace-agent
```

```bash OpenRC theme={null}
sudo filetrace config validate && sudo rc-service filetrace-agent restart
```

The command-line interface reads the same file. It takes the default output format (`[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 `true` and `false`.
* 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.

Every setting is optional. A key that is left out keeps its default, and a section may be left out entirely.

## 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:

| Unit | Bytes |
| - | - |
| none, `B` | 1 |
| `K`, `KB` | 1024 |
| `M`, `MB` | 1024² |
| `G`, `GB` | 1024³ |
| `T`, `TB` | 1024⁴ |

The number may have a fraction: `"1.5MB"`. A unit outside quotes is an error:

```toml theme={null}
ring_buffer_size = "4MB"     # accepted
ring_buffer_size = 4194304   # accepted, bytes
ring_buffer_size = 4MB       # error: quote sizes and durations
```

### Durations

A duration is always a quoted string of a number and one of the units `ms`, `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.

```bash theme={null}
filetrace config validate /tmp/bad.toml
```

```text theme={null}
/tmp/bad.toml:2: [agent] mode: expected "minimal" or "standard"
```

An error names the file, the line and what was expected. These are errors, with exit code 6:

* 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.

The keys of features this build does not include are accepted (they are marked below). Setting one of them to `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]`](#prometheus), [`[otlp]`](#otlp) and [`[grpc]`](#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:

```bash theme={null}
filetrace config show | sudo tee /etc/filetrace/config.toml >/dev/null
```

## \[agent]

How the agent collects, where it listens, and how much memory its queues and event log take.

**enabled** `boolean` (default: true)

With `false`, the agent logs that it is not collecting and exits with code 0 right after reading the file.

**mode** `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](#mode-dependent-defaults)). Option: `--mode`.

**probes** `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](https://filetrace.mintlify.site/concepts/kernel-probes.md). Option: `--probes`.

**socket** `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`.

**ring\_buffer\_size** `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`.

**event\_batch\_size** `integer` (default: 512)

Counters read from the kernel per call, from 16 to 65536.

**flush\_interval** `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`.

**event\_log\_size** `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`.

**log\_level** `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.

**tcp** `boolean` (default: true)

Record TCP sockets.

**udp** `boolean` (default: true)

Record UDP sockets.

**ipv4** `boolean` (default: true)

Record IPv4 sockets.

**ipv6** `boolean` (default: true)

Record IPv6 sockets.

**tc\_egress** `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`.

**track\_read** `boolean` (default: true)

Follow reads of regular files, for read-write attribution (`INFERRED` transfers).

**track\_sendfile** `boolean` (default: true)

Follow `sendfile`, for exact attribution (`EXACT` transfers).

**track\_open** `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.

**track\_mmap** `boolean` (default: false)

Not available in this build. `true` is ignored with a warning: data read through memory mappings is not observed.

**track\_splice** `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](https://filetrace.mintlify.site/concepts/attribution.md) explains the rules.

**enabled** `boolean` (default: true)

File attribution as a whole. `false` turns off both read and `sendfile` tracking, whatever `[file]` says.

**window** `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`.

**confidence\_threshold** `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.

**inferred\_min\_bytes** `size` (default: 1KB)

A read-write association is reported once it covers at least this many bytes, from 0 to 1GB.

**inferred\_min\_percent** `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.

**track\_process\_lifecycle** `boolean` (default: true)

Always on. `false` is ignored with a warning: process lifetimes are always followed.

**track\_fd\_lifecycle** `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.

**track\_io\_uring** `boolean` (default: false)

Not available in this build. `true` is ignored with a warning: file reads through io\_uring are not observed.

## \[storage]

> [!WARNING]
>
> Persistent history is not included in this build. History is kept in memory only and starts when the agent does. The section and its keys are accepted and checked for their kind and range, and have no other effect.

**enabled** `boolean` (default: false)

`true` is ignored with a warning.

**path** `string` (default: /var/lib/filetrace)

Accepted; has no effect.

**retention** `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](https://filetrace.mintlify.site/guides/performance.md) covers the memory they take.

**processes** `integer` (default: 4096)

Processes the agent keeps.

**sockets** `integer` (default: 16384)

Sockets the agent keeps.

**flows** `integer` (default: 16384)

Flows (one process's traffic with one remote endpoint on a socket) the agent keeps.

**files** `integer` (default: 16384)

Files the agent keeps.

**transfers** `integer` (default: 16384)

Transfers the agent keeps.

**kernel\_counters** `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`.

**kernel\_files** `integer` (default: 16384)

File identities the kernel remembers as already described to the agent.

**metric\_series** `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.

**format** `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](https://filetrace.mintlify.site/cli/output-formats.md).

**timestamps** `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](#patterns).

**exclude\_processes** `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.

**exclude\_paths** `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](https://filetrace.mintlify.site/integrations/prometheus.md).

**enabled** `boolean` (default: false)

Serve the metrics page on `http://<listen>/metrics`.

**listen** `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)](https://filetrace.mintlify.site/integrations/opentelemetry.md).

**enabled** `boolean` (default: false)

Run the OTLP exporter. It does not start when both `logs` and `metrics` are `false`.

**endpoint** `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.

**logs** `boolean` (default: true)

Send each event of the types in `events` as an OTLP log record.

**metrics** `boolean` (default: true)

Send the metrics.

**events** `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](https://filetrace.mintlify.site/reference/event-types.md). An unknown name is an error.

**file\_paths** `boolean` (default: true)

`false` leaves file paths out of the log records; device and inode remain.

**batch\_size** `integer` (default: 1024)

Records per export request, from 16 to 4096.

**flush\_interval** `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.

**metrics\_interval** `duration` (default: 30s)

How often metrics are sent, from 1s to 1h. Values are cumulative since the agent started.

**timeout** `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](https://filetrace.mintlify.site/integrations/grpc-api.md).

**enabled** `boolean` (default: false)

Serve the gRPC API.

**listen** `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.

| Setting | Option | standard | minimal |
| - | - | - | - |
| `[agent] ring_buffer_size` | `--queue-size` | 4MB | 1MB |
| `[agent] event_log_size` | `--event-log-size` | 1MB | 256KB |

## 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.

```toml theme={null}
[agent]
enabled = true
mode = "standard"
probes = "auto"
socket = "/run/filetrace/agent.sock"
ring_buffer_size = "4MB"
event_batch_size = 512
flush_interval = "250ms"
event_log_size = "1MB"
log_level = "info"

[network]
tcp = true
udp = true
ipv4 = true
ipv6 = true

[file]
track_read = true
track_sendfile = true

[correlation]
enabled = true
window = "2s"
confidence_threshold = "inferred"
inferred_min_bytes = "1KB"
inferred_min_percent = 5

[limits]
processes = 4096
sockets = 16384
flows = 16384
files = 16384
transfers = 16384
kernel_counters = 16384
kernel_files = 16384
metric_series = 2048

[output]
format = "table"
timestamps = true

[filters]
exclude_processes = ["filetrace-agent"]
exclude_paths = ["/proc/*", "/sys/*"]

[prometheus]
enabled = true
listen = "127.0.0.1:9464"

[otlp]
enabled = true
endpoint = "127.0.0.1:4317"
logs = true
metrics = true
events = ["file_transfer", "event_loss"]
file_paths = true
batch_size = 1024
flush_interval = "5s"
metrics_interval = "30s"
timeout = "10s"

[grpc]
enabled = true
listen = "unix:/run/filetrace/api.sock"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.