# Upgrade collectors

Upgrade Tracix Collectors to the stable release from the console, turn on automatic updates per policy, and recover from a failed upgrade.

Tracix promotes one collector release at a time as the stable release. The **Collectors** page compares every collector with it, so you can upgrade collectors one at a time, in bulk, or let each policy keep its collectors current on its own.

## How releases reach collectors

Every release is published for Linux, macOS and Windows on amd64 and arm64, and as a container image for Docker and Kubernetes. The console's install commands and every upgrade use an exact version, and containers an exact image digest, never a moving tag such as `latest`.

Upgrades are verified before anything changes:

* A host collector downloads the new build over HTTPS, checks its SHA-256 checksum, and has the new binary validate the configuration it is running before it replaces the old one.
* A container upgrade uses the image digest Tracix pinned for the release.
* Tracix never moves a collector to an older version.

## Check which collectors are out of date

Open **Collectors**. The **Version** column shows what each collector runs, and the **Release** column shows how it compares with the stable release:

| Release column | Meaning                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Upgrade**    | A newer stable release is available and Tracix can upgrade this collector.                                           |
| **Retry**      | The last upgrade failed. Select it to try again.                                                                     |
| **Updating**   | An upgrade is in progress.                                                                                           |
| **manual**     | A legacy or unmanaged installation. Reinstall it once with the current installer or command to get managed upgrades. |
| **current**    | The collector runs the stable release.                                                                               |
| **ahead**      | The collector runs a newer version than the stable release.                                                          |
| **unknown**    | Tracix can't compare the collector's version with the stable release.                                                |

## Upgrade from the console

**1. Pick the collectors**

To upgrade one collector, select **Upgrade** in its row, or open it and select **Upgrade to** with the version. To upgrade several, select them and choose **upgrade** above the list; collectors that are already current, already updating or managed by hand are skipped.

**2. Watch the progress**

The row shows **Updating** while the collector downloads, validates and applies the release. Host collectors restart onto the new binary; containers are replaced, as the table below explains.

**3. Check the result**

The **Version** column shows the new version and the **Release** column shows **current**. If the upgrade failed, the row offers **Retry**, which starts a new attempt.

Each upgrade request is attempted once, and a failure stays visible until you retry it. Policies that update their collectors automatically also retry failed upgrades on a schedule, described below.

## Update collectors automatically

Each policy has an **Automatically update managed collectors** setting. It is on by default for new policies. Find it on the policy's **Settings** tab under **Collector updates**.

When it is on, Tracix upgrades every managed collector on the policy to each new stable release. Plan for that: a new release can reach all of the policy's managed collectors within about a minute. If you want to try releases on a few hosts first, keep those hosts on a separate policy and turn the setting off on the rest.

If an automatic upgrade fails, Tracix tries again 15 minutes, 1 hour and 4 hours after each failed attempt. After the fourth failure the upgrade stays failed until you select **Retry**, which starts over. Without automatic updates, failed upgrades wait for you to retry them.

## What an upgrade does on each platform

| Platform   | Upgrade                                                                                                                                                         | If it fails                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Linux      | Swaps the binary in place and lets systemd restart the service. Keeps the old binary as `/opt/tracix-collector/bin/tracix-collector.previous`.                  | Restore the previous binary by hand. See below.                       |
| macOS      | Swaps the binary in place and lets launchd restart the daemon. Keeps the old binary as `/usr/local/bin/tracix-collector.previous`.                              | Restore the previous binary by hand. See below.                       |
| Windows    | Stops the service, replaces the binary and starts it again. Keeps the old binary as `tracix-collector.exe.previous`.                                            | Puts the previous binary back if the service fails to start.          |
| Kubernetes | Patches the collector's DaemonSet to the release's image digest. The rolling update replaces one node's pod at a time.                                          | The rest of the fleet keeps running if a new pod never becomes ready. |
| Docker     | Pulls the release's image by digest, checks the digest, then recreates the container with the same name, volumes and networks. Needs the Docker socket mounted. | The old container keeps running when the pull or the check fails.     |

> **Docker upgrades need the Docker socket**
>
> A Docker collector upgrades itself only when it was started with the Docker socket mounted, which the console's Docker command does while the policy updates collectors automatically. The socket gives root-equivalent access to the host. Without it, the collector shows **manual**: upgrade it by running the install command again, as described below.

On Kubernetes, Helm or your GitOps tool still owns the DaemonSet. If it is pinned to an older image digest, it can undo an upgrade the console started, so update the pinned values when you upgrade.

## Restore the previous binary

If a new binary on Linux or macOS can't start, put the previous one back and restart the service. Turn off **Automatically update managed collectors** on the policy first if you want to keep the collector on the older version for now; otherwise Tracix retries the upgrade.

#### Linux

```bash
sudo systemctl stop tracix-collector
sudo cp /opt/tracix-collector/bin/tracix-collector.previous /opt/tracix-collector/bin/tracix-collector
sudo systemctl start tracix-collector
```

#### macOS

```bash
sudo cp /usr/local/bin/tracix-collector.previous /usr/local/bin/tracix-collector
sudo launchctl kickstart -k system/com.tracix.collector
```

#### Windows

Nothing to do: the Windows upgrade puts the previous binary back itself when the service fails to start.

## Upgrade by hand

Use these when a collector shows **manual**, or when you install pinned versions yourself.

In the commands on this page, replace `<workspace>` with your workspace ID: the eight characters that end your workspace's address, before `.app.tracix.io`.

#### Linux

Run the installer again, with the version the console shows for the stable release. It upgrades the binary in place and keeps the collector's identity, and the previous configuration is kept as a timestamped backup.

```bash
curl -fsSL https://charts.tracix.io/install.sh | sudo bash -s -- \
  --endpoint https://agents-<workspace>.app.tracix.io \
  --version <version from the console> \
  --token-file /root/tracix-token
```

#### macOS

Run the installer again, with the version the console shows for the stable release.

```bash
curl -fsSL https://charts.tracix.io/install.sh | sudo bash -s -- \
  --endpoint https://agents-<workspace>.app.tracix.io \
  --version <version from the console> \
  --token-file /var/root/tracix-token
```

#### Windows

Run the console's PowerShell install command again from an elevated PowerShell. It carries the stable version as `-Version`.

#### Kubernetes

Upgrade the Helm release to the chart version and image digest of the stable release, which the console's Kubernetes install command shows.

```bash
helm repo update
helm upgrade tracix-collector tracix/tracix-collector \
  --namespace tracix \
  --reuse-values \
  --version <chart version from the console> \
  --set-string image.digest=<image digest from the console>
```

#### Docker

Remove the old container, then run the console's Docker command again. It pins the new image by digest, and the `tracix-agent-state` volume keeps the collector's identity.

```bash
docker rm -f tracix-agent
# then run the Docker command from Deploy collector on the Collectors page
```

## Next steps

- [Manage collectors with policies](https://tracix.io/docs/collect/collector/policies): Turn automatic updates on or off per policy

- [Troubleshoot the collector](https://tracix.io/docs/collect/collector/troubleshooting): Fix a collector that fails after an upgrade

- [Release notes](https://tracix.io/docs/reference/release-notes): What changed in each release