filetrace config: show, validate and locate the config file

Reference for filetrace config: print every setting in effect, validate a configuration file before the agent reads it, and print which file is read.

filetrace config works with the configuration file: show prints every setting with the value in effect, validate checks a file and reports what is wrong with it, and path prints which file is read. It reads the file itself and does not need a running agent.

​

Usage

filetrace config show
filetrace config validate [<file>]
filetrace config path

​

Which file is read

The file is /etc/filetrace/config.toml, or $FILETRACE_CONFIG, or the one named with the global option --config, which config also accepts after its action. The agent reads the file when it starts, and its own command-line options override it. The other commands take their default output format, [output] format, and the socket to reach the agent on, [agent] socket, from it.

If the default file, or the one $FILETRACE_CONFIG names, does not exist, the built-in defaults apply. A file named with --config must exist.

A setting that asks for something this build cannot do, such as [storage] enabled = true, is reported as a warning and ignored. An unknown setting or a value of the wrong kind is an error. Configuration file reference describes every setting.

​

show

config show prints every setting in the format of the configuration file, preceded by a comment that says where the values come from. Without a file, these are the defaults:

filetrace config show

# Built-in defaults; there is no configuration file at /etc/filetrace/config.toml.

[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
# Not available in this build; true is ignored with a warning.
tc_egress = false

The output continues with the [file], [correlation], [storage], [limits], [output], [filters], [prometheus], [otlp] and [grpc] sections. With a file, the first line names it:

filetrace --config /etc/filetrace/config.toml config show

# Settings in effect, read from /etc/filetrace/config.toml.

[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 = "warn"

Because the output is a complete, valid configuration file, it is a way to write a first one:

filetrace config show | sudo tee /etc/filetrace/config.toml >/dev/null

Warnings about settings this build ignores go to standard error, after the settings.

​

validate

config validate checks a file without starting anything. Without a file argument, it checks the file that would be read.

filetrace config validate /etc/filetrace/config.toml

/etc/filetrace/config.toml is valid.

A file with ignored settings is valid with warnings: the result line counts them, and each warning follows on standard error. Without a file at the default location, the command says that the built-in defaults apply.

An error names the file, the line, the section and the setting, and the command exits with 6. For a file that sets an unknown mode:

[agent]
mode = "fast"
[storage]
enabled = true

filetrace config validate /tmp/bad.toml

/tmp/bad.toml:2: [agent] mode: expected "minimal" or "standard"

Validate a file before you install it, so that the agent does not refuse to start: the agent also exits with 6 on an invalid file, and the systemd service does not retry a start that failed with that code.

​

path

config path prints the path of the file that would be read, whether or not it exists:

filetrace config path

​

Options

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

The configuration file to show, validate or locate. Accepted before config, as a global option, or after the action. A file argument of validate overrides the global option.

​

Examples

filetrace config show > /etc/filetrace/config.toml
filetrace config validate ./config.toml
filetrace --config ./config.toml config show

​

Exit codes

Code	Meaning
0	The configuration is usable
2	Invalid arguments, such as a missing or unknown action
6	The configuration is not usable: the file cannot be read or holds an error