Documentation

The entries below are the failures that occur most often during installation, each given as symptom, cause and resolution.

Symptom: CBOM-Server or Collector-Services exits at once with no useful message, or the container restarts in a loop.
Most likely cause: a configuration file is missing. Both the root and the service configuration file must be present; the service exits deliberately rather than starting in an undefined state.
Resolution: confirm both files exist at their expected paths and are readable by the service account. In a container deployment, confirm the entrypoint generated them — a missing variable in the environment file can produce a file that exists but is incomplete.
Second cause: the logging section is absent from the root configuration. The service treats an absent logging configuration as fatal. An empty section is valid and sufficient.

Symptom: the platform is reachable and the portal loads, but the task template builder offers no sensors.
Cause: the sensor library component was not initialised before build, so no sensor schemas were copied into the image and none were registered at startup.
Resolution: initialise the sensor component recursively, rebuild, and restart. Verify that sensor schemas are present after startup.

Symptom: installation completed and the portal works, but saving a host or integration credential fails.
Cause: the credential encryption key is not a valid key for the encryption scheme. This does not fail at startup — it fails on first use.
Resolution: generate a valid key with the documented helper, set it in configuration, and restart. Note that credentials written under a different key cannot be read back after the key changes; a key change requires re-entering credentials.

Symptom: startup fails at the database step, or the portal loads but every data view is empty.
Checks: the connection string and credentials in the root configuration; network reachability from the service to the database port; whether database authentication is enabled and whether the application account exists with rights on the application database; and whether the database is still initialising on a first container start.
Note for evaluators: the platform opens its database client at startup and performs schema seeding and index creation at that point. A database that is unreachable at startup is fatal, not deferred.

Symptom: the login page loads, credentials are accepted, and the browser returns to the login page.
Most likely cause: an external FQDN mismatch. The frontend URL, the backend URL and the identity provider redirect URIs must all agree, and all must be the name the browser actually used.
Second cause: an incorrect identity provider client secret. This usually produces an explicit authentication error rather than a loop.
Third cause: the realm was not imported. The import runs on first start only. If the platform first started without the export in place, the realm must be imported manually or the identity provider state reset.

Symptom: browsers warn, or remote sensors fail to submit with a verification error.
Checks: whether the certificate names the address actually used — the most common failure is a certificate naming a hostname while sensors connect by IP; whether the full issuing chain is installed rather than the leaf alone; whether the certificate has expired; and whether the sensor host trusts the issuing CA.
For evaluation deployments using a self-signed certificate, the sensor host must be configured to trust that certificate explicitly. This is a deliberate step, not something to work around by disabling verification.

Linux targets: verify SSH and SFTP reachability, credential validity, write permission on the deployment directory, and that the execute permission is being set on the transferred binary.
Windows targets: verify WinRM is enabled and reachable, SMB is reachable, the firewall permits WinRM, and the account has enough privilege for the sensors in the task.
Both: check that a binary for the target platform and architecture exists in the distribution directory. A missing artefact for one platform is easy to overlook, because deployment to the other platform continues to work.