clair-troubleshooting-issues.adoc

Troubleshooting Clair issue

Use the following procedures to troubleshoot Clair.

Verifying image compatibility

If you are using Clair, ensure that the images you are trying to scan are supported by Clair. Clair has certain requirements and does not support all image formats or configurations.

For more information, see Clair vulnerability databases.

Allowlisting Clair updaters

If you are using Clair behind a proxy configuration, you must allowlist the updaters in your proxy or firewall configuration. For more information about updater URLs, see Clair updater URLs.

Updating Clair scanner and its dependencies

Ensure that you are using the latest version of Clair security scanner. Outdated versions might lack support for newer image formats, or might have known issues.

Use the following procedure to check your version of Clair.

Note	Checking Clair logs can also be used to check if there are any errors from the updaters microservice in your Clair logs. By default, Clair updates the vulnerability database every 30 minutes.

Procedure

1. Check your version of Clair.

   1. If you are running Clair on {productname-ocp}, enter the following command:

      $ oc logs clair-pod

   2. If you are running a standalone deployment of {productname} and using a Clair container, enter the following command:

      $ podman logs clair-container
      Example output

      "level":"info",
      "component":"main",
      "version":"v4.5.1",

Enabling debug mode for Clair

By default, debug mode for Clair is disabled. You can enable debug mode for Clair by updating your clair-config.yaml file.

Prerequisites

• For Clair on {productname-ocp} deployments, you must Running a custom Clair configuration with a managed Clair database.

Use the following procedure to enable debug mode for Clair.

Procedure

1. Update your clair-config.yaml file to include the debug option.

   1. On standalone {productname} deployments:

      1. Add the following configuration field to your clair-config.yaml file:

         log_level: debug

      2. Restart your Clair deployment by entering the following command:

         $ podman restart <clair_container_name>

   2. On {productname-ocp} deployments:

      1. On the {ocp} web console, click Operators → Installed Operators → Quay Registry.

      2. Click the name of your registry, for example, Example Registry. You are redirected to the Details page of your registry.

      3. Click the Config Bundle Secret, for example, example-registry-config-bundle-xncls.

      4. Confirm that you are running a custom Clair configuration by looking for the clair-config.yaml file under the Data section of the Details page of your secret.

      5. If you have a clair-config.yaml file, click Actions → Edit Secret. If you do not, see "Running a custom Clair configuration with a managed Clair database".

      6. Update your clair-config.yaml file to include the log_level: debug configuration variable. For example:

         log_level: debug

      7. Click Save.

      8. You can check the status of your Clair deployment by clicking Workloads → Pods. The clair-app pod should report 1/1 under the Ready category.

      9. You can confirm that Clair is returning debugging information by clicking the clair-app pod that is ready → Logs.

Checking Clair configuration

Check your Clair config.yaml file to ensure that there are no misconfigurations or inconsistencies that could lead to issues. For more information, see Clair configuration overview.

Inspect image metadata

In some cases, you might receive an Unsupported message. This might indicate that the scanner is unable to extract the necessary metadata from the image. Check if the image metadata is properly formatted and accessible.

Additional resources

For more information, see Troubleshooting Clair.