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.
Download
Section titled “Download”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:
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.
Verify
Section titled “Verify”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:
sha256sum --check --ignore-missing SHA256SUMSThe line for your file must say OK. If it says FAILED, delete the file and download it again. Do not install it.
Install
Section titled “Install”Debian and Ubuntu:
sudo apt install ./affectra-collector_1.2.3_arm64.debRHEL, Fedora and SUSE:
sudo rpm -i affectra-collector-1.2.3.aarch64.rpmThe package does not start anything. It needs your settings first.
Configure
Section titled “Configure”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:
AFFECTRA_TENANT=acmeAFFECTRA_TOKEN=exk_example_not_a_real_keyAFFECTRA_COLLECTOR_ARGS=--push https://api.example.comFor an air-gapped unit, leave the key empty and write bundles to the outbox:
AFFECTRA_TENANT=acmeAFFECTRA_COLLECTOR_ARGS=--out /var/lib/affectra/outboxPut 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:
sudo chmod 0600 /etc/affectra/collector.envEnable the timer, then run the collector once now:
sudo systemctl enable --now affectra-collector.timersudo systemctl start affectra-collector.serviceThe 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.
Check that it reported
Section titled “Check that it reported”Read the log of the run:
journalctl -u affectra-collector.serviceAn 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:
AFFECTRA_TENANT=acme affectra-collector --out /var/lib/affectra/outboxUninstall
Section titled “Uninstall”Remove the package the usual way:
sudo apt remove affectra-collector # Debian, Ubuntusudo rpm -e affectra-collector # RHEL, Fedora, SUSEBefore 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.envstays afterapt removeon Debian and Ubuntu. On RPM systems it stays, renamed tocollector.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.
Remove a unit securely
Section titled “Remove a unit securely”When you take a unit out of service or hand it on, make sure the API key does not go with it:
- Revoke the key under API keys in the app, if no other unit uses it. Collectors using a revoked key stop reporting immediately.
- Remove the package. On Debian and Ubuntu use
sudo apt purge affectra-collector, which deletes the settings file as well. - Delete
/etc/affectra/collector.envand anycollector.env.rpmsaveif they are still there. - 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.