> ## 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. # 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 > [tab] systemd > > ```bash theme={null} > sudo systemctl enable --now filetrace-agent > sudo systemctl status filetrace-agent > sudo systemctl restart filetrace-agent > sudo systemctl disable --now filetrace-agent > ``` > [tab] OpenRC > > ```bash theme={null} > 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 > ``` > [tab] SysV init > > ```bash theme={null} > 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: ```bash theme={null} sudo filetrace agent status ``` ```text theme={null} 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: ```bash theme={null} 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](https://filetrace.mintlify.site/reference/configuration.md). 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: ```ini theme={null} [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](https://filetrace.mintlify.site/reference/security.md). ## 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//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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.