Skip to content

Install the collector

The collector runs on a unit and reports which packages are installed. Affectra matches those packages against vulnerabilities, so you can see which units are affected.

Each unit reports in one of two ways:

  • Online. The collector pushes its report to the Affectra API (--push). Use this when the unit can reach the API.
  • Outbox. The collector writes a bundle file to a directory (--out). Someone carries the file out and imports it. See Air-gapped units and bundles.

Before you start, you need:

  • the tenant name of your organization;
  • for online units, an API key. Create it under API keys in the app. See API keys. Collectors need a key that can propose changes.

Packages for Linux amd64, arm64 and arm7 (32-bit ARMv7) are attached to each agents/collector/v* release on GitHub. Each release also has a file called SHA256SUMS.

Download the package for your unit’s architecture and SHA256SUMS into one empty directory:

Terminal window
curl --fail --location --remote-name \
"https://github.com/affectra/affectra/releases/download/agents%2Fcollector%2Fv1.2.3/affectra-collector_1.2.3_arm64.deb"
curl --fail --location --remote-name \
"https://github.com/affectra/affectra/releases/download/agents%2Fcollector%2Fv1.2.3/SHA256SUMS"

Replace 1.2.3, the architecture and the file type with your own. The .rpm files are named affectra-collector-<version>.<arch>.rpm, and the tarballs affectra-collector_<version>_linux_<arch>.tar.gz.

Check the download before you install it. SHA256SUMS lists every file of the release, so tell sha256sum to skip the ones you did not download:

Terminal window
sha256sum --check --ignore-missing SHA256SUMS

The line for your file must say OK. If it says FAILED, delete the file and download it again. Do not install it.

Debian and Ubuntu:

Terminal window
sudo apt install ./affectra-collector_1.2.3_arm64.deb

RHEL, Fedora and SUSE:

Terminal window
sudo rpm -i affectra-collector-1.2.3.aarch64.rpm

The package does not start anything. It needs your settings first.

Open /etc/affectra/collector.env. The package installs it so that only root can read it (mode 0600), because it holds the API key. An upgrade keeps your edits.

For an online unit:

Terminal window
AFFECTRA_TENANT=acme
AFFECTRA_TOKEN=exk_example_not_a_real_key
AFFECTRA_COLLECTOR_ARGS=--push https://api.example.com

For an air-gapped unit, leave the key empty and write bundles to the outbox:

Terminal window
AFFECTRA_TENANT=acme
AFFECTRA_COLLECTOR_ARGS=--out /var/lib/affectra/outbox

Put the key in this file and nowhere else. A key on a command line shows up in the process list and in shell history. All settings are in the collector reference.

If you edit the file in a way that replaces it, check that it is still mode 0600:

Terminal window
sudo chmod 0600 /etc/affectra/collector.env

Enable the timer, then run the collector once now:

Terminal window
sudo systemctl enable --now affectra-collector.timer
sudo systemctl start affectra-collector.service

The timer runs the collector 5 minutes after boot and then once an hour, plus a random delay of up to 10 minutes so that many units do not report at the same moment.

Read the log of the run:

Terminal window
journalctl -u affectra-collector.service

An online unit logs inventory collected and then report pushed. An outbox unit logs inventory collected and then bundle written with the path of the file.

Then open Units in the app. An online unit is listed there once its report has arrived. If it is not, the log shows the error. A 429 means you are over the rate limits; the report is left for the next run.

To link the unit to a release, see Find affected units.

Units without systemd or a package manager

Section titled “Units without systemd or a package manager”

Use the tarball. Verify it as above, unpack it, copy affectra-collector to the unit and run it from your own scheduler. Set the key in the environment of the job, not on the command line:

Terminal window
AFFECTRA_TENANT=acme affectra-collector --out /var/lib/affectra/outbox

Remove the package the usual way:

Terminal window
sudo apt remove affectra-collector # Debian, Ubuntu
sudo rpm -e affectra-collector # RHEL, Fedora, SUSE

Before it removes the files, the package stops the timer and disables it. An upgrade does not do this.

The package does not delete what you or the collector created:

  • /etc/affectra/collector.env stays after apt remove on Debian and Ubuntu. On RPM systems it stays, renamed to collector.env.rpmsave, when you changed it. It holds the API key.
  • Bundle files in /var/lib/affectra/outbox/ stay, so no report is lost before it is imported.

When you take a unit out of service or hand it on, make sure the API key does not go with it:

  1. Revoke the key under API keys in the app, if no other unit uses it. Collectors using a revoked key stop reporting immediately.
  2. Remove the package. On Debian and Ubuntu use sudo apt purge affectra-collector, which deletes the settings file as well.
  3. Delete /etc/affectra/collector.env and any collector.env.rpmsave if they are still there.
  4. Import the bundle files left in /var/lib/affectra/outbox/ first, or delete them. They list the packages of the unit.

Deleting a file does not wipe it from a flash disk. If the key might still be readable, the revoked key is what protects you.