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

# 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 reports diagnostics; collection needs Linux. A macOS backend would need an Endpoint Security system extension. |
| FreeBSD | None | Collection would need a DTrace backend. |

SELinux in enforcing mode is untested. Run [`filetrace doctor`](https://filetrace.mintlify.site/cli/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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://filetrace.eorlov.org/install.sh | sudo sh
```

Pass options after `-s --`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://filetrace.eorlov.org/install.sh | sudo sh -s -- --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](https://filetrace.mintlify.site/reference/versioning.md). |
| `--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.

> [!NOTE]
>
> 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](https://filetrace.mintlify.site/reference/security.md) lists their fingerprints.

> [tab] Debian and Ubuntu
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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.

> [tab] Fedora and RHEL
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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.

> [tab] openSUSE
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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
> ```

> [tab] Alpine
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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.

> [!NOTE]
>
> No lts line has been cut yet. The `lts` channel, its apt suite and its rpm and apk repositories appear with the first release of an lts line; until then nothing is published under them. The installer of 26.11.1.160 does not check for this: on Debian and Ubuntu, `--channel lts` stops with apt's "does not have a Release file" and leaves `/etc/apt/sources.list.d/filetrace.sources` pointing at the missing suite, so `apt update` fails. Run the installer again without `--channel lts` to point the file back at `stable`, or with `--uninstall` to remove it. The installer of the next release refuses a channel that has no release before it changes anything, and names the address it could not read.

## Install with Homebrew

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://github.com/OrlovEvgeny/filetrace/releases) 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
gh attestation verify filetrace-26.11.1.80-linux-amd64.tar.gz --repo OrlovEvgeny/filetrace
```

To build Filetrace yourself, see [Build from source](https://filetrace.mintlify.site/build-from-source.md).

## Verify the installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.


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