Skip to content

Collector

The collector is the program affectra-collector. It builds a list of the packages installed on a unit and either pushes it to the Affectra API or writes it to a file. To install it, see Install the collector.

Without --push or --out, the collector prints the report to standard output.

Flag Default Environment variable What it does
--unit-id the host name AFFECTRA_UNIT_ID The name of the unit in Affectra.
--tenant none AFFECTRA_TENANT The tenant that owns the unit. Required with --push and --out.
--token none AFFECTRA_TOKEN The API key. Required with --push. Use the environment variable: a flag is visible in the process list.
--root / none The file system root to inspect.
--push none none The base URL of the API to push the report to (online mode). Must be https://, unless you also set --insecure.
--insecure off none Allows --push to an http:// URL. The API key then travels unencrypted, so use it for tests only. Without it, the collector refuses a URL that is not https://.
--out none none The directory to write a bundle file to (outbox mode).
--help none none Prints the usage and exits.
--version none none Prints the version of the collector and exits.

A flag you set wins over its environment variable. --push and --out cannot be used together.

Older units may still pass flags with a single dash, such as -push. The collector accepts them, but write --push in new settings.

The service reads its settings from /etc/affectra/collector.env, a file of NAME=value lines.

Setting Default What it does
AFFECTRA_TENANT none The tenant that owns the unit. Required.
AFFECTRA_UNIT_ID the host name The name of the unit in Affectra.
AFFECTRA_TOKEN none The API key, for online units. Keep the file readable by root only (mode 0600).
AFFECTRA_COLLECTOR_ARGS none The flags the service passes to the collector, for example --push https://api.example.com or --out /var/lib/affectra/outbox.
AFFECTRA_LOG_LEVEL info How much the collector logs: debug, info, warn or error.
AFFECTRA_LOG_FORMAT auto The log format: json, text or auto. auto is text on a terminal and json otherwise.

Logs go to the journal: journalctl -u affectra-collector.service. A wrong log level or format does not stop the collector: it logs a warning and uses the defaults.

Each report holds the unit’s name, the tenant, the time, the version of the collector, the release the unit runs and its packages.

The release. The collector reads /etc/affectra-release (or /etc/affectra-firmware, the old name). The file holds one line with the version, or KEY=value lines with PRODUCT, VARIANT and VERSION. See Find affected units for the format and for how Affectra links the unit to a release.

The collector version. It is the version that --version prints, without the commit and cut to 100 characters. The Units page uses it to show which units run an old collector.

The packages. The collector reads every installed package from Alpine’s /lib/apk/db/installed or from dpkg’s /var/lib/dpkg/status. Packages that were removed but left their configuration are skipped. Each package has a name, a version and a package URL (purl) that Affectra matches against vulnerabilities:

  • dpkg: pkg:deb/<ID>/<package>@<version>?arch=…&distro=<ID>-<VERSION_ID>, with upstream naming the source package (and its version, if it has its own) and epoch for an epoch.
  • apk: pkg:apk/<ID>/<package>@<version>?arch=…&distro=<ID>-<VERSION_ID>, with upstream naming the origin package.

ID and VERSION_ID come from /etc/os-release, or /usr/lib/os-release.

Debian, Ubuntu and Alpine are matched. Other distributions are reported but not matched yet. That includes derivatives such as Raspberry Pi OS (raspbian), and Debian testing or sid, which have no VERSION_ID. Without an os-release file the collector sends no purls, and the unit is not matched.

The API limits how fast an organization can send reports. When a push gets 429 Too Many Requests, the collector waits for the time in Retry-After, which is seconds or an HTTP date, and 30 seconds if the header is missing or invalid. It adds up to 25% random delay and tries once more. If that is refused too, or if Retry-After is longer than 10 minutes, it exits with an error and leaves the report for the next run. It never loops. Reports are safe to send twice, so the retry does no harm. Error messages include the detail and code of the API’s answer.

Online collectors and imported bundles use the same budget. These are the defaults; the operator of your installation can change them:

  • Per organization: 50 reports a second, up to 1000 at once. Every key, user and online collector of the organization shares them.
  • Per unit: 12 reports an hour for one unit name. A unit over the limit is refused even when the organization has room. The count is kept per API replica, so it is approximate: do not rely on it to the request.

Over either limit the API answers 429 Too Many Requests with Retry-After in seconds and the problem code request.rateLimited. A 403 is not a rate limit: the bundle names another organization.

Path What it is
/usr/bin/affectra-collector The program.
/usr/lib/systemd/system/affectra-collector.service One inventory run. It runs as the user affectra-collector, not as root, with no capabilities and only network access. The service sees the file system read-only; only the outbox is writable.
/usr/lib/systemd/system/affectra-collector.timer Starts the service 5 minutes after boot and then every hour, with a random delay of up to 10 minutes. The package does not start it.
/etc/affectra/collector.env The settings and the API key. Mode 0600. An upgrade keeps your edits.
/var/lib/affectra/outbox/ Where bundle files go in outbox mode. Mode 0750, owned by affectra-collector. A bundle file is named after the unit name, with every character other than letters, digits, ., _ and - replaced by _.

The tarball holds the program, the service and timer files, a copy of collector.env and a short README.