Install Filetrace on Linux and macOS

Install Filetrace with the installer script, from the apt, dnf, yum, zypper or apk repositories, with Homebrew, or from release archives, and upgrade or remove it.

Filetrace is distributed as signed packages for the common Linux package managers, as a Homebrew formula, and as release archives. The package installs both programs, the configuration file /etc/filetrace/config.toml and the filetrace-agent service for systemd, OpenRC or SysV init. The programs are linked statically, so one build runs on any distribution.

​

Requirements

Platform	Collection	Notes
Linux 6.1 or later, x86-64 or arm64	eBPF through libbpf and CO-RE	Needs BTF (/sys/kernel/btf/vmlinux). Tested on Linux 6.1, 6.12 and 7.0 on arm64; continuous integration builds and tests x86-64 and arm64 on the kernel of GitHub’s Ubuntu 24.04 runners. Other kernels are expected to work through CO-RE but are untested.
macOS 15 or later	None	The command-line interface builds and reports diagnostics. Collection would need an Endpoint Security system extension.
FreeBSD	None	Collection would need a DTrace backend.

SELinux in enforcing mode is untested. Run filetrace doctor after installing to see what the kernel accepts.

​

Install with the installer script

On Linux, the installer detects the package manager (apt, dnf, yum, zypper or apk), adds the Filetrace repository with its signing key, and installs the filetrace package, so upgrades arrive with the system’s own. Where none of these package managers is present, it downloads the release archive, checks it against the release’s SHA256SUMS, unpacks it under /usr/local and installs the service for the init system it finds.

curl -fsSL https://filetrace.eorlov.org/install.sh | sudo sh

Pass options after -s --:

curl -fsSL https://filetrace.eorlov.org/install.sh | sudo sh -s -- --channel lts --no-start

Option	Effect
--version <version>	Install this version instead of the newest.
--channel <channel>	stable or lts. Default: stable. See Versions and release channels.
--method <method>	auto, package or tarball. Default: auto.
--prefix <dir>	Where the archive is unpacked. Default: /usr/local.
--no-start	Leave the service disabled and stopped.
--uninstall	Remove what this script installed.
--dry-run	Print what would be done and stop.
-h, --help	Show the help.

The environment variables FILETRACE_VERSION, FILETRACE_CHANNEL and FILETRACE_NO_START=1 stand for the options of the same name.

The installer starts the agent unless --no-start is given. With the agent running as root, the commands that query it need sudo.

​

Install from a package repository

The repositories live under https://filetrace.eorlov.org and carry the stable and lts channels. apt and yum metadata and the rpm packages are signed with the OpenPGP key at https://filetrace.eorlov.org/gpg.key; the apk repository and packages with the RSA key at https://filetrace.eorlov.org/apk/filetrace.rsa.pub. Security lists their fingerprints.

Debian and Ubuntu

curl -fsSL https://filetrace.eorlov.org/gpg.key | sudo tee /etc/apt/keyrings/filetrace.asc >/dev/null
printf 'Types: deb\nURIs: https://filetrace.eorlov.org/apt\nSuites: stable\nComponents: main\nSigned-By: /etc/apt/keyrings/filetrace.asc\n' |
    sudo tee /etc/apt/sources.list.d/filetrace.sources >/dev/null
sudo apt update && sudo apt install filetrace

The deb package enables and starts filetrace-agent when it is first installed.

Fedora and RHEL

printf '[filetrace]\nname=Filetrace\nbaseurl=https://filetrace.eorlov.org/rpm/stable/$basearch\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://filetrace.eorlov.org/gpg.key\n' |
    sudo tee /etc/yum.repos.d/filetrace.repo >/dev/null
sudo dnf install filetrace && sudo systemctl enable --now filetrace-agent

On systems with yum, replace dnf with yum. The rpm package leaves the service disabled and stopped.

openSUSE

sudo rpm --import https://filetrace.eorlov.org/gpg.key
sudo zypper addrepo --refresh 'https://filetrace.eorlov.org/rpm/stable/$basearch' filetrace
sudo zypper install --repo filetrace filetrace && sudo systemctl enable --now filetrace-agent

Alpine

wget -O /etc/apk/keys/filetrace.rsa.pub https://filetrace.eorlov.org/apk/filetrace.rsa.pub
echo https://filetrace.eorlov.org/apk/stable >>/etc/apk/repositories
apk add filetrace && rc-update add filetrace-agent default && rc-service filetrace-agent start

The apk package leaves the service disabled and stopped.

To follow the lts channel, replace stable with lts in the suite, baseurl or repository URL.

​

Install with Homebrew

Homebrew installs the two programs on macOS 15 or later and on Linux, without a service.

brew install orlovevgeny/filetrace/filetrace

filetrace follows the newest release. To stay on one release line, install its formula instead, for example orlovevgeny/filetrace/filetrace@26.11.

​

Install from a release archive

Every release carries archives for Linux and macOS, also available at https://filetrace.eorlov.org/dist/<tag>/. An archive holds bin/filetrace and bin/filetrace-agent, the default configuration and the service definitions. Check an archive against the release’s SHA256SUMS, or verify its build attestation:

gh attestation verify filetrace-26.11.1.80-linux-amd64.tar.gz --repo OrlovEvgeny/filetrace

To build Filetrace yourself, see Build from source.

​

Verify the installation

filetrace version
sudo filetrace doctor

filetrace version prints the version, build and platform, and whether the agent is running. filetrace doctor reports whether the kernel can be monitored; it exits with 0 when the status is READY.

​

Upgrade

Upgrades arrive through the package manager like any other package. The command and the agent speak one protocol version, so an upgrade restarts a running agent. If /etc/filetrace/config.toml is not valid for the new version, the agent is not restarted and the package manager prints what filetrace config validate reports. An upgrade never overwrites the configuration file.

With an archive installation, run the installer again. It replaces the programs and restarts a running agent under the same condition: the configuration must be valid for the new version.

​

Uninstall

curl -fsSL https://filetrace.eorlov.org/install.sh | sudo sh -s -- --uninstall

The installer removes the package and the repository definition and key it added, or, for an archive installation, stops and disables the service and removes the programs and service files. /etc/filetrace is left in place. To remove a package installed by hand, use the package manager: apt remove filetrace, dnf remove filetrace, zypper remove filetrace or apk del filetrace.