# Collector configuration reference

What a policy controls and what stays on the host, the collector's files, its bootstrap config.yaml and environment file, and its local health check.

A Tracix Collector takes almost all of its configuration from its policy. Only a few settings live on the host: where the control plane is, how to reach it, and what the host allows the collector to do. This page lists both, with the files the collector keeps on each platform.

## What the policy controls

You manage these in the console, on the policy, and every collector on the policy picks up the change:

| Setting                                                                                       | Where in the console                                       |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Integrations: what the collector collects, how often, and which ports it listens on           | The policy's **Integrations** tab                          |
| Output: where the collector writes, by default your workspace's data store (**Tracix store**) | The policy's **Settings** tab, under **Output**            |
| Automatic updates to the stable release                                                       | The policy's **Settings** tab, under **Collector updates** |

Tracix turns the policy into an OpenTelemetry Collector configuration and writes it to the collector's `config.yaml`. Every generated configuration also:

* adds `policy.id` and `policy.name` resource attributes to everything the collector sends;
* removes credentials from URLs in the application spans and OTLP logs the collector handles, such as `user:password@` in a URL, webhook paths and token query parameters, before it exports them;
* keeps the collector's management connection, its local health check and its own metrics.

The configuration on disk never contains the credential the collector writes with. It holds a reference, which the collector resolves in memory when it loads the configuration.

> **Change the policy, not config.yaml**
>
> The collector overwrites `config.yaml` whenever it applies a new revision of its policy, so edits you make on the host don't last. See [Enroll and manage collectors with policies](https://tracix.io/docs/collect/collector/policies).

## What stays on the host

The installer writes these, and they change only when you run the installer again:

* the control plane URL the collector enrolls with;
* an outbound proxy, if you passed `--proxy`;
* the collector's display name;
* what the host lets the collector do, such as the eBPF permissions `--enable-obi` grants.

### Installer flags

The installer for Linux and macOS takes these flags. The Windows installer takes the PowerShell equivalents shown in [Install the Tracix Collector](https://tracix.io/docs/collect/collector/install).

| Flag                                 | Platforms    | What it does                                                                                                                         |
| ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--endpoint URL`                     | Linux, macOS | The control plane to enroll with. Required.                                                                                          |
| `--token-file PATH`, `--token TOKEN` | Linux, macOS | The enrollment token. Without either, the installer prompts for it with the input hidden.                                            |
| `--version VERSION`                  | Linux, macOS | Installs a specific release.                                                                                                         |
| `--proxy URL`, `--no-proxy LIST`     | Linux, macOS | An outbound HTTP proxy, and the hosts that bypass it. See [Ports, proxies and firewalls](https://tracix.io/docs/collect/collector/ports-and-proxies). |
| `--name NAME`                        | Linux        | The collector's display name. Defaults to the host name.                                                                             |
| `--enable-obi`                       | Linux        | Grants the eBPF permissions for [zero-code tracing](https://tracix.io/docs/collect/instrument/ebpf).                                                  |
| `--enable-network-path`              | Linux        | Grants `CAP_NET_RAW`, so synthetic tests can trace the network path hop by hop.                                                      |
| `--enable-security`                  | Linux        | Grants what the Linux endpoint security integration needs to read process, network and file events.                                  |
| `--enable-software-inventory`        | Linux        | Grants what the software inventory integration needs to read every application on the host.                                          |
| `--enable-response`                  | Linux, macOS | Allows approved response actions on the host: ending a process, and quarantining or restoring a file.                                |

The console's install command adds the flags the selected policy needs. Running the installer again without a flag removes what that flag granted.

## Files on each platform

#### Linux

| Path                                           | Contents                                                               |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| `/opt/tracix-collector/bin/tracix-collector`   | The binary, with a link at `/usr/local/bin/tracix-collector`           |
| `/etc/tracix-collector/config.yaml`            | The bootstrap configuration, then the policy's                         |
| `/etc/tracix-collector/tracix-collector.env`   | The environment file, readable only by the collector's service account |
| `/etc/tracix-collector/backups/`               | Earlier environment files, kept when the installer runs again          |
| `/var/lib/tracix-collector/`                   | The state directory                                                    |
| `/etc/systemd/system/tracix-collector.service` | The systemd unit                                                       |

The service runs as the unprivileged `tracix-collector` user. Its logs go to the journal: `sudo journalctl -u tracix-collector -f`.

#### macOS

| Path                                                   | Contents                                       |
| ------------------------------------------------------ | ---------------------------------------------- |
| `/usr/local/bin/tracix-collector`                      | The binary                                     |
| `/usr/local/etc/tracix-collector/config.yaml`          | The bootstrap configuration, then the policy's |
| `/usr/local/etc/tracix-collector/tracix-collector.env` | The environment file, readable only by root    |
| `/usr/local/etc/tracix-collector/backups/`             | Earlier environment files                      |
| `/usr/local/var/lib/tracix-collector/`                 | The state directory                            |
| `/usr/local/var/log/tracix-collector/stderr.log`       | The log                                        |
| `/Library/LaunchDaemons/com.tracix.collector.plist`    | The launchd daemon                             |

#### Windows

| Path                                                    | Contents                                                        |
| ------------------------------------------------------- | --------------------------------------------------------------- |
| `C:\Program Files\TracixCollector\tracix-collector.exe` | The binary                                                      |
| `C:\ProgramData\TracixCollector\config.yaml`            | The bootstrap configuration, then the policy's                  |
| `C:\ProgramData\TracixCollector\data`                   | The state directory, readable only by SYSTEM and Administrators |
| `TracixCollector`                                       | The Windows service, running as LocalSystem                     |

Windows has no environment file: the installer stores the same settings in the service's `Environment` value under `HKLM:\SYSTEM\CurrentControlSet\Services\TracixCollector`. Logs go to the Application event log, source `TracixCollector`.

#### Kubernetes

The Helm chart runs the collector as a DaemonSet and reads its credentials from the secret named in `existingSecret`:

| Secret key          | Contents                            |
| ------------------- | ----------------------------------- |
| `control-plane-url` | The control plane URL               |
| `agent-token`       | The enrollment token                |
| `otlp-endpoint`     | Your workspace's OTLP/HTTP endpoint |
| `otlp-token`        | The enrollment token again          |

Chart values the console's command sets include `clusterName`, `controlPlane.enabled`, `image.repository` and `image.digest`, plus what the policy needs, such as `containerLogs.enabled` or `obi.enabled`. Each node's collector takes the node's name unless you set `agentDisplayName`. Add environment variables, such as a proxy, with `extraEnv`.

#### Docker

The console's Docker command passes the settings as environment variables and keeps the state directory in the `tracix-agent-state` volume, mounted at `/var/lib/tracix-collector`:

| Variable                    | Contents                                         |
| --------------------------- | ------------------------------------------------ |
| `CONTROL_PLANE_URL`         | The control plane URL                            |
| `AGENT_TOKEN`, `OTLP_TOKEN` | The enrollment token                             |
| `OTLP_ENDPOINT`             | Your workspace's OTLP/HTTP endpoint              |
| `TRACIX_INSTALL_MODE`       | `docker`                                         |
| `TRACIX_UPDATE_ENABLED`     | `1` when the container may upgrade itself        |
| `TRACIX_AGENT_NAME`         | The display name; the command uses the host name |

Inside the container, the configuration is `/var/lib/tracix-collector/config.yaml`, in the volume. Keep the volume: it holds the collector's identity, so a new container from the same command is the same collector.

### The state directory

| File                | Contents                                                                               |
| ------------------- | -------------------------------------------------------------------------------------- |
| `enrollment-token`  | The enrollment token, until the collector has enrolled. The collector then deletes it. |
| `agent-id`          | The collector's ID                                                                     |
| `agent-token`       | The collector's own credential, issued at enrollment                                   |
| `signing-pubkey`    | The key the collector checks configuration signatures with                             |
| `config-etag`       | The version of the configuration it last applied                                       |
| `update-state.json` | The state of its last upgrade                                                          |

The state directory is what makes a host the same collector across restarts, upgrades and reinstalls against the same workspace. Running the installer against a different workspace moves the old identity and configuration to `backups/` and enrolls the host as a new collector.

## The bootstrap config.yaml

On Linux, macOS and Windows, the installer writes a minimal configuration that does one thing: enroll. Once the collector has enrolled, it replaces the file with its policy's configuration. Each install keeps the previous file beside it as `config.yaml.bak.<timestamp>`. This is the Linux and macOS version; Windows reads the same values with `${env:…}`.

Expected output:

```text
# tracix-bootstrap
extensions:
health_check:
  endpoint: 127.0.0.1:13133
remoteconfig:
  endpoint: ${CONTROL_PLANE_URL}
  auth_token: ${AGENT_TOKEN}
  config_path: ${TRACIX_CONFIG_PATH}
  state_dir: ${TRACIX_STATE_DIR}
  poll_interval: 30s
  timeout: 10s

receivers:
nop: {}

exporters:
nop: {}

service:
extensions: [health_check, remoteconfig]
pipelines:
  metrics:
    receivers: [nop]
    exporters: [nop]
```

The `nop` pipeline sends nothing; it only makes the file a valid collector configuration. The values in `${…}` come from the environment file. Docker and Kubernetes collectors start from a similar configuration that also sends host metrics until the policy arrives.

## The environment file

On Linux the file is `/etc/tracix-collector/tracix-collector.env`; on macOS, `/usr/local/etc/tracix-collector/tracix-collector.env`. The enrollment token is never in it.

| Variable                                            | Contents                                                                                         |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `CONTROL_PLANE_URL`                                 | The control plane URL from `--endpoint`                                                          |
| `TRACIX_CONFIG_PATH`                                | Where the collector writes its policy's configuration                                            |
| `TRACIX_STATE_DIR`                                  | The state directory                                                                              |
| `TRACIX_REGION`                                     | The value of `--region`, which the console's command passes. The collector doesn't use it today. |
| `TRACIX_AGENT_NAME`                                 | The display name from `--name`. Linux only; empty means the host name.                           |
| `TRACIX_INSTALL_MODE`                               | `linux-systemd` or `macos-launchd`                                                               |
| `TRACIX_UPDATE_ENABLED`, `TRACIX_UNINSTALL_ENABLED` | `1`: the collector can upgrade and uninstall itself when asked                                   |
| `TRACIX_OBI_ENABLED`                                | `1` when installed with `--enable-obi`. Linux only.                                              |
| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`             | Present when installed with `--proxy`                                                            |
| `TRACIX_HOST_RESPONSE`                              | `1` when installed with `--enable-response`                                                      |

To change a value, run the installer again with the new flags rather than editing the file. The installer rewrites the file each time and keeps a copy of the old one in `backups/`.

## Local health check

Every collector answers a health check on port 13133. On Linux, macOS and Windows hosts it listens on `127.0.0.1` only, so it can't be reached from the network. In containers it listens on every interface, so Kubernetes probes and Docker port mappings can reach it.

#### Linux

```bash
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:13133
```

Expected output:

```text
200
```

#### macOS

```bash
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:13133
```

Expected output:

```text
200
```

#### Windows

```powershell
(Invoke-WebRequest http://127.0.0.1:13133 -UseBasicParsing).StatusCode
```

Expected output:

```text
200
```

#### Kubernetes

The chart's startup, liveness and readiness probes call the health check on each pod. Check the pods instead:

```bash
kubectl get pods -n tracix
```

#### Docker

The image's Docker health check calls it every 30 seconds:

```bash
docker inspect --format '{{.State.Health.Status}}' tracix-agent
```

Expected output:

```text
healthy
```

The collector also serves its own metrics in Prometheus format on port 18888, on the same interfaces as the health check. Tracix doesn't collect them; they are there for you to inspect.

## Next steps

- [Manage collectors with policies](https://tracix.io/docs/collect/collector/policies): Change what collectors collect

- [Ports, proxies and firewalls](https://tracix.io/docs/collect/collector/ports-and-proxies): What the collector connects to and listens on

- [Troubleshoot the collector](https://tracix.io/docs/collect/collector/troubleshooting): Logs, symptoms and fixes