Run the Filetrace agent as a system service

Manage filetrace-agent under systemd, OpenRC or SysV init: start and stop it, pass options, read its logs, control who may query it, and apply configuration changes.

The Filetrace packages install filetrace-agent as a service for the system’s init: a systemd unit, an OpenRC script or a SysV init script. The agent collects continuously from boot, so the commands always have history to answer from. This guide covers managing the service, configuring it, reading its logs, and controlling who may query it.

​

Start and stop

systemd

sudo systemctl enable --now filetrace-agent
sudo systemctl status filetrace-agent
sudo systemctl restart filetrace-agent
sudo systemctl disable --now filetrace-agent

OpenRC

sudo rc-update add filetrace-agent default
sudo rc-service filetrace-agent start
sudo rc-service filetrace-agent restart
sudo rc-update del filetrace-agent default && sudo rc-service filetrace-agent stop

SysV init

sudo service filetrace-agent start
sudo service filetrace-agent restart
sudo service filetrace-agent stop

Whether installing a package starts the service depends on the package format: the deb package enables and starts it, the rpm and apk packages leave both to you, and the installer script starts it unless given --no-start.

filetrace agent status reports the state of the agent behind the socket, whichever way it was started:

sudo filetrace agent status

Monitoring: RUNNING
Backend:    Linux eBPF (trampolines)
Mode:       standard
PID:        1008
Started:    2026-11-11 20:07:55
Uptime:     2h 14m
Health:     Healthy

It exits with 0 when the agent runs, 4 when it is stopped, and 9 when it is degraded, for example because it is losing events. filetrace agent stop asks the running agent to stop. Under a service manager, stop the service with the service manager instead.

​

Configure the agent

The agent reads /etc/filetrace/config.toml once, when it starts. Edit the file, check it, then restart the service:

sudoedit /etc/filetrace/config.toml
filetrace config validate
sudo systemctl restart filetrace-agent

filetrace config validate exits with 6 and says what is wrong when the file is not usable. An unknown setting or a value of the wrong kind is an error; a setting this build cannot honour is a warning. filetrace config show prints every setting with the value in effect. See the configuration reference.

Settings belong in the configuration file. Command-line options of filetrace-agent override it and can be passed through the service manager when needed:

Init	Where to put options
systemd	A drop-in: sudo systemctl edit filetrace-agent, then override ExecStart
OpenRC	FILETRACE_AGENT_OPTS in /etc/conf.d/filetrace-agent
SysV init	FILETRACE_AGENT_OPTS in /etc/default/filetrace-agent

For example, a systemd drop-in that forces the kprobe set:

[Service]
ExecStart=
ExecStart=/usr/bin/filetrace-agent --probes kprobe

Use the path of filetrace-agent that systemctl cat filetrace-agent shows.

​

Read the logs

The agent logs to standard error at the level set by [agent] log_level (error, warn, info or debug).

Init	Logs
systemd	journalctl -u filetrace-agent
OpenRC, SysV init	/var/log/filetrace-agent.log, rotated weekly by logrotate when it is installed

​

Restart behavior

The systemd unit restarts the agent on failure after 5 seconds, at most 5 times in 5 minutes. It does not restart on exit codes that a retry cannot fix: 2 (invalid arguments), 3 (permission denied), 5 (unsupported platform or kernel) and 6 (invalid configuration). The unit only starts when /sys/kernel/btf/vmlinux exists; the OpenRC script checks the same and validates the configuration before it starts the agent.

​

Control who may query the agent

The agent listens on /run/filetrace/agent.sock. It checks the credentials of every client and answers only root and the user the agent runs as. It closes the connection of any other client and logs rejected a client that is neither root nor the agent's user. Because the packaged service runs as root, use sudo for the commands that query it.

The gRPC API applies the same rule on a unix: socket. On a TCP address it admits anyone who can connect, and the agent says so when it starts. See Security.

​

Systemd hardening

The unit runs the agent with only the capabilities it needs and a restricted view of the system:

Setting	Value
CapabilityBoundingSet	CAP_BPF CAP_PERFMON CAP_SYS_ADMIN CAP_SYS_PTRACE. CAP_SYS_PTRACE reads /proc/<pid>/exe and the namespaces of other users’ processes.
NoNewPrivileges	yes
ProtectSystem	strict
ProtectHome, PrivateTmp, PrivateDevices	yes
ProtectKernelModules, ProtectKernelLogs, ProtectControlGroups, ProtectClock, ProtectHostname	yes
RestrictAddressFamilies	AF_UNIX AF_INET AF_INET6
RestrictNamespaces, RestrictRealtime, RestrictSUIDSGID, LockPersonality, MemoryDenyWriteExecute	yes
SystemCallArchitectures	native
RuntimeDirectory	filetrace, mode 0755, which holds the socket

​

Upgrades

The command and the agent speak one protocol version, so a package upgrade restarts a running agent, provided the configuration file is valid for the new version. Otherwise the agent keeps running the old version and the package manager prints what filetrace config validate reports; fix the file and restart the service. History starts again with every restart.