Using Red Hat Discovery
Preface
Use this guide to add sources, manage credentials, run scans, and download reports with Red Hat Discovery.
Chapter 1. Track your product data with Red Hat Discovery
Red Hat Discovery is designed to help users collect data about their usage of specific Red Hat software. By using Discovery, users can reduce the amount of time and effort that is required to calculate and report usage of those Red Hat products.
1.1. What is Red Hat Discovery
Red Hat Discovery is an agentless inspection and reporting tool that identifies physical and virtual systems on a network, their operating systems, configuration data, and installed Red Hat products. Use these findings to understand and manage your subscription usage and IT inventory.
The ability to inspect the software and systems that are running on your network improves your ability to understand and report on your subscription usage. Ultimately, this inspection and reporting process is part of the larger system administration task of managing your inventories.
Red Hat Discovery requires the configuration of two basic structures to access IT resources and run the inspection process. A credential contains user access data, such as the username and password or Secure Shell (SSH) key. It provides sufficient authority to run the inspection process on a particular source. A source contains data about a single asset or multiple assets that are to be inspected.
These assets can be physical machines, virtual machines, or containers, identified as hostnames, IP addresses, IP ranges, or subnets. These assets can also be a systems management solution such as vCenter Server or Red Hat Satellite Server, or can be clusters deployed on Red Hat OpenShift Container Platform.
Currently, the only virtualized deployment that Discovery can scan with a specialized source for virtualization infrastructure is VMware vCenter. No other virtualization infrastructure that is supported by Red Hat can be scanned with a specialized scan. General scans of your network might still find these assets, without the precise metadata returned by a specialized scan.
You can save multiple credentials and sources to use with Discovery in various combinations as you run inspection processes, or scans. When you have completed a scan, you can access these facts in the output as a collection of formatted data, or report, to review the results.
By default, the credentials and sources that are created during the use of Red Hat Discovery are encrypted in a database. The values are encrypted with AES-256 encryption. They are decrypted when the Red Hat Discovery server runs a scan with the use of a vault password to access the encrypted values that are stored in the database.
Red Hat Discovery is an agentless inspection tool, so there is no need to install the tool on every source that is to be inspected. However, the system that Discovery is installed on must have access to the systems to be discovered and inspected.
1.2. Products that Red Hat Discovery finds
Red Hat Discovery detects specific Red Hat products. For each version or release, the earliest supported version is listed, with later releases indicated as applicable.
If a product has changed names recently so that you might be more familiar with the current name for that product, that name is provided as additional information. No later version is implied by the inclusion of a newer product name unless specific versions of that product are also listed.
Red Hat Enterprise Linux
- Red Hat Enterprise Linux version 6 and later
- Red Hat Enterprise Linux version 7 and later
- Red Hat Enterprise Linux version 8 and later
- Red Hat Enterprise Linux version 9 and later
- Red Hat Enterprise Linux version 10 and later
Red Hat Application Services products (formerly Red Hat Middleware)
- JBoss Enterprise Web Server version 1 and later; Red Hat JBoss Web Server 3.0.1 and later
- Red Hat JBoss Enterprise Application Platform version 4.2 and later, version 4.3 and later, version 5 and later, version 6 and later, version 7 and later
- Red Hat Fuse version 6.0 and later
Red Hat Ansible Automation Platform
- Ansible Automation Platform version 2 and later
Red Hat OpenShift Container Platform
- Red Hat OpenShift Container Platform version 4 and later
Red Hat Advanced Cluster Security for Kubernetes
- Red Hat Advanced Cluster Security for Kubernetes version 4 and later
Red Hat Advanced Cluster Management for Kubernetes
- Red Hat Advanced Cluster Management for Kubernetes version 2 and later
1.3. Red Hat Discovery suitability and support
Red Hat Discovery helps you discover your Red Hat product inventory across complex networks. Work with a Red Hat Solution Architect (SA) or Technical Account Manager (TAM) to interpret the generated reports.
You can also work with the Subscription Education and Awareness Program (SEAP) for analysis and assistance.
Although you can install and use Discovery independently and then generate and view report data, the Discovery documentation does not provide any information to help you interpret report results. Red Hat Support can provide some basic assistance related to installation and usage of Discovery. However, the support team does not provide any assistance to help you understand the reports.
The Discovery tool does not automatically share data directly with Red Hat. Instead, you choose whether to prepare and send report data to Red Hat for ingestion by Red Hat tools and services. You can use the Discovery tool locally to scan your network for the Red Hat products that Discovery currently supports and then use the generated reports for your own internal purposes.
Chapter 2. Access the Red Hat Discovery user interface
You access the Red Hat Discovery graphical user interface through a browser. You access the Discovery command line interface by running a terminal session command to connect to the server.
2.1. Log in to the Red Hat Discovery user interface
Log in to the Discovery user interface by using the server IP address, port number, and administrator credentials. Contact your Discovery administrator if you do not have this information.
Prerequisites
- The system on which you want to run the user interface can communicate with the system on which the Discovery server is installed.
Procedure
In a browser, enter the URL for the Discovery server in the format
https://IPaddress:server_port, whereIPaddressis the IP address andserver_portis the exposed server port.-
If you log in from the system where the server is installed and the default port
9443is used, you can use the loopback address as the IP address. The loopback address is also known as localhost, as shown in the following example:
https://127.0.0.1:9443
-
If you log in from the system where the server is installed and the default port
- After you enter the URL for the server, the Discovery login page displays.
- On the login page, enter the username and password for the Discovery server administrator account and then click Log in to log in to the server.
Verification
If this is the first time that you have logged in to Discovery, the Credentials view displays. You can begin by adding credentials and sources that can be used in scans. If you have previously logged in to Discovery, you can interact with your previously created credentials, sources, and scans.
2.2. Log out of the Red Hat Discovery user interface
Log out of the Discovery user interface to end your session and secure access to the server.
Procedure
- In the application toolbar, click the person icon or your username.
- Click Logout.
Verification
- Verify that the Discovery login page is displayed in your browser.
2.3. Log in to the Red Hat Discovery command line interface
To log in to the Discovery command line interface, you need the username and password for the Discovery server administrator. If you do not have this information, contact the administrator who installed the Discovery server.
The login command retrieves a token that is used for authentication with subsequent command line interface commands. That token is removed when you log out of the server, and expires daily.
Prerequisites
- The Discovery command line interface is installed on the same system where the server container is installed.
- You are accessing the command line interface on the same system where the server container is installed.
Procedure
To log in to the command line interface, enter the following command. In this command,
server_usernameis the username for the Discovery server administrator andserver_passwordis the password for the server administrator:dsc server login --username __server_administrator_username__ --password __server_administrator_password__
- After you log in to the command line interface, you can begin entering commands to create sources, credentials, and scans.
2.4. Log out of the Red Hat Discovery command line interface
The command to log out of the server removes the token that was created when you logged in to the server. This token also expires daily.
Procedure
To log out of the command line interface, enter the following command:
dsc server logout
Verification
- Verify that a logout confirmation message is displayed in the command line output.
Chapter 3. Establish authentication credentials to enable network scans
To run a scan on your network, you must first add a source that identifies the physical machines, virtual machines, or containers to scan. Then you must add credentials that contain the authentication data to access each asset.
3.1. Add network sources
Define network sources to identify the hosts, Internet Protocol (IP) addresses, and IP ranges that Discovery scans across your network.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click Add Source.
- From the Sources view, click Add.
- On the Type page, select Network Range as the source type and click Next.
On the Credentials page, enter the following information.
- In the Name field, enter a descriptive name.
In the Search Addresses field, enter one or more network identifiers separated by commas. You can enter hostnames, IP addresses, and IP ranges.
-
Enter hostnames as Domain Name System (DNS) hostnames, for example,
server1.example.com. -
Enter IP ranges in Classless Inter-Domain Routing (CIDR) or Red Hat Ansible Automation Platform notation, for example,
192.168.1.0/24for CIDR notation or192.168.1.[1:254]for Red Hat Ansible Automation Platform notation.
-
Enter hostnames as Domain Name System (DNS) hostnames, for example,
- Optional: In the Port field, enter a different port if you do not want a scan for this source to run on the default port 22.
- In the Credentials list, select the credentials that are required to access the network resources for this source. If a required credential does not exist, click the Add a credential icon to open the Add Credential view.
- If your network resources require the Python SSH implementation (Paramiko) instead of the default OpenSSH implementation, select the Connect using Paramiko instead of OpenSSH check box.
- Click Save to save the source and then click Close to close the view.
Verification
- In the Sources view, verify that the new source appears in the sources list with the correct name and type.
3.2. Add network credentials
Create network credentials to authenticate Discovery scans against remote systems in your network by using Secure Shell (SSH)-based authentication.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click → .
- From the Add Source wizard, click the Add a credential icon for the Credentials field.
The Add Credential wizard opens.
- In the Credential Name field, enter a descriptive name.
- In the Authentication Type field, select the type of authentication that you want to use. You can select either Username and Password or SSH Key.
Enter the authentication data in the appropriate fields, based on the authentication type.
- For username and password authentication, enter a username and password for a user. This user must have root-level access to your network or to the subset of your network that you want to scan. Alternatively, this user must be able to obtain root-level access with the selected become method.
- For SSH key authentication, enter a username and paste the contents of the ssh keyfile. Entering a passphrase is optional.
- Enter the become method for privilege elevation. Privilege elevation is required to run some commands during a network scan. Entering a username and password for the become method is optional.
- Click Save to save the credential and close the Add Credential wizard.
Verification
- In the Credentials view, verify that the new credential appears in the credentials list with the correct name and type.
3.3. Red Hat Discovery sources and credentials
To run a scan, you must configure data for two basic structures: sources and credentials. The type of source that you are going to inspect during the scan determines the type of data that is required for both source and credential configuration.
A source contains a single asset or a set of multiple assets that are to be inspected during the scan. You can configure any of the following types of sources:
- Network source
- One or more physical machines, virtual machines, or containers. These assets can be expressed as hostnames, IP addresses, IP ranges, or subnets.
- vCenter source
- A vCenter Server systems management solution that is managing all or part of your IT infrastructure.
- Satellite source
- A Satellite systems management solution that is managing all or part of your IT infrastructure.
- Red Hat OpenShift source
- A Red Hat OpenShift Container Platform cluster that is managing all or part of your Red Hat OpenShift Container Platform nodes and workloads.
- Ansible source
- An Red Hat Ansible Automation Platform management solution that is managing your Red Hat Ansible Automation Platform nodes and workloads.
- Red Hat Advanced Cluster Security for Kubernetes source
- A RHACS security platform solution that secures your Kubernetes environments.
When you are working with network sources, you determine how many individual assets you should group within a single source. Currently, you can add multiple assets to a source only for network sources. The following list contains some of the other factors that you should consider when you are adding sources:
- Whether assets are part of a development, testing, or production environment, and if demands on computing power and similar concerns are a consideration for those assets.
- Whether you want to scan a particular entity or group of entities more often because of internal business practices such as frequent changes to the installed software.
A credential contains data such as the username and password or SSH key of a user with sufficient authority to run the scan on all or part of the assets in that source. As with sources, credentials are configured as the network, vCenter, satellite, OpenShift, Red Hat Ansible Automation Platform, or RHACS type. A network source might require multiple network credentials to access all assets in a broad IP range. Conversely, a vCenter or satellite source typically uses a single credential to access a particular system management solution server. An OpenShift, Red Hat Ansible Automation Platform, or RHACS source uses a single credential to access a single cluster.
You can add new sources from the Sources view and you can add new credentials from the Credentials view. You can also add new or select previously existing credentials during source creation. It is during source creation that you associate a credential directly with a source.
Because sources and credentials must have matching types, any credential that you add during source creation shares the same type as the source. If you want to use an existing credential during source creation, the list of available credentials contains only credentials of the same type. For example, during network source creation, only network credentials are available for selection.
3.4. Network authentication for Red Hat Discovery
Network scans use Secure Shell (SSH) through Red Hat Ansible Automation Platform to inspect remote systems. Configure network credentials with either a username and password or a username and SSH keyfile pair, optionally including a passphrase.
Also during network credential configuration, you can enable a become method. The become method is used during a scan to elevate privileges. These elevated privileges are needed to run commands and obtain data on the systems that you are scanning.
Additional resources
3.5. Commands that are used in scans of remote network assets
During network scans, Discovery runs commands on remote systems using the credentials you provide. Some commands require elevated privileges through sudo to gather complete facts for your report.
Although it is possible to run a scan for a network source without elevated privileges, the results of that scan are incomplete. The incomplete results from the network scan affect the quality of the generated report for the scan.
The following information lists the commands that Discovery runs on remote hosts during a network scan. It includes the basic commands that can run without elevated privileges. It also lists the commands that must run with elevated privileges to gather the most accurate and complete information for the report.
In addition to the following commands, Discovery also depends on standard shell facilities, such as those provided by the bash shell.
3.5.1. Basic commands that do not need elevated privileges
The following commands do not require elevated privileges to gather facts during a scan:
- cat
- egrep
- sort
- uname
- ctime
- grep
- rpm
- virsh
- date
- id
- test
- whereis
- echo
- sed
- tune2fs
- xargs
3.5.2. Commands that need elevated privileges
The following commands require elevated privileges to gather facts during a scan. Each command includes a list of individual facts or categories of facts that Discovery attempts to find during a scan. These facts cannot be included in reports if elevated privileges are not available for that command.
- awk
- cat
- chkconfig
- command
- df
- dirname
- dmidecode
- echo
- egrep
- fgrep
- find
- ifconfig
- ip
- java
- locate
- ls
- ps
- readlink
- sed
- sort
- stat
- subscription-manager
- systemctl
- tail
- test
- tr
- unzip
- virt-what
- xargs
- yum
Chapter 4. Add Red Hat Satellite sources and credentials
To run a scan on a Red Hat Satellite Server deployment, you must add a source that identifies the Satellite Server server to scan. Then you must add a credential that contains the authentication data to access that server.
4.1. Add satellite sources
Define satellite sources to identify Satellite Server instances and their managed hosts for Discovery scanning.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click Add Source.
- From the Sources view, click Add.
- On the Type page, select Satellite as the source type and click Next.
On the Credentials page, enter the following information.
- In the Name field, enter a descriptive name.
-
In the IP Address or Hostname field, enter the IP address or hostname of the Satellite server for this source. Enter a different port if you do not want a scan for this source to run on the default port 443. For example, if the IP address of the Satellite server is 192.0.2.15 and you want to change the port to 80, you would enter
192.0.2.15:80. -
Optional: In the Proxy URL field enter the proxy server needed to reach the Satellite host. This value is passed directly to the HTTP client and must match the format expected by your proxy setup, for example,
Content from proxy.example.com is not included.http://proxy.example.com:3128orContent from proxy.example.com is not included.https://proxy.example.com:443. - In the Credentials list, select the credential that is required to access the Satellite server for this source. If a required credential does not exist, click the Add a credential icon to open the Add Credential view.
In the Connection list, select the SSL protocol to be used for a secure connection during a scan of this source.
NoteSatellite Server does not support the disabling of SSL. If you select the Disable SSL option, this option is ignored.
- If you need to upgrade the SSL validation for the Satellite server to check for a verified SSL certificate from a certificate authority, select the Verify SSL Certificate check box.
- Click Save to save the source and then click Close to close the view.
Verification
- In the Sources view, verify that the new source appears in the sources list with the correct name and type.
4.2. Add Red Hat Satellite credentials
Create satellite credentials to authenticate Discovery scans against Satellite Server instances.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click → .
- From the Add Source wizard, click the Add a credential icon for the Credentials field.
The Add Credential wizard opens.
- In the Credential Name field, enter a descriptive name.
- Enter the username and password for a Satellite Server administrator.
- Click Save to save the credential and close the Add Credential wizard.
Verification
- In the Credentials view, verify that the new credential appears in the credentials list with the correct name and type.
4.3. Red Hat Discovery sources and credentials
To run a scan, you must configure data for two basic structures: sources and credentials. The type of source that you are going to inspect during the scan determines the type of data that is required for both source and credential configuration.
A source contains a single asset or a set of multiple assets that are to be inspected during the scan. You can configure any of the following types of sources:
- Network source
- One or more physical machines, virtual machines, or containers. These assets can be expressed as hostnames, IP addresses, IP ranges, or subnets.
- vCenter source
- A vCenter Server systems management solution that is managing all or part of your IT infrastructure.
- Satellite source
- A Satellite systems management solution that is managing all or part of your IT infrastructure.
- Red Hat OpenShift source
- A Red Hat OpenShift Container Platform cluster that is managing all or part of your Red Hat OpenShift Container Platform nodes and workloads.
- Ansible source
- An Red Hat Ansible Automation Platform management solution that is managing your Red Hat Ansible Automation Platform nodes and workloads.
- Red Hat Advanced Cluster Security for Kubernetes source
- A RHACS security platform solution that secures your Kubernetes environments.
When you are working with network sources, you determine how many individual assets you should group within a single source. Currently, you can add multiple assets to a source only for network sources. The following list contains some of the other factors that you should consider when you are adding sources:
- Whether assets are part of a development, testing, or production environment, and if demands on computing power and similar concerns are a consideration for those assets.
- Whether you want to scan a particular entity or group of entities more often because of internal business practices such as frequent changes to the installed software.
A credential contains data such as the username and password or SSH key of a user with sufficient authority to run the scan on all or part of the assets in that source. As with sources, credentials are configured as the network, vCenter, satellite, OpenShift, Red Hat Ansible Automation Platform, or RHACS type. A network source might require multiple network credentials to access all assets in a broad IP range. Conversely, a vCenter or satellite source typically uses a single credential to access a particular system management solution server. An OpenShift, Red Hat Ansible Automation Platform, or RHACS source uses a single credential to access a single cluster.
You can add new sources from the Sources view and you can add new credentials from the Credentials view. You can also add new or select previously existing credentials during source creation. It is during source creation that you associate a credential directly with a source.
Because sources and credentials must have matching types, any credential that you add during source creation shares the same type as the source. If you want to use an existing credential during source creation, the list of available credentials contains only credentials of the same type. For example, during network source creation, only network credentials are available for selection.
4.4. Satellite Server authentication
Satellite scans authenticate to Satellite Server by using a username and password encrypted over HTTPS. By default, scans run with certificate validation and secure communication through SSL or TLS protocols, which you can configure during source creation.
The Satellite Server credentials that you use for a satellite scan must be a user with a role that contains the view permissions for hosts, subscriptions, and organizations.
You might need to adjust the level of certificate validation to connect properly to the Satellite Server during a scan. For example, your Satellite Server might use a verified SSL certificate from a certificate authority. During source creation, you can upgrade SSL certificate validation to check for that certificate during a scan of that source.
Conversely, your Satellite Server might use self-signed certificates. During source creation, you can leave the SSL validation at the default so that a scan of that source does not check for a certificate. This choice, to leave the option at the default for a self-signed certificate, could possibly avoid scan errors.
Although the option to disable SSL is currently available in the interface, Satellite Server does not support the disabling of SSL. If you select the Disable SSL option when you create a satellite source, this option is ignored.
Chapter 5. Add vCenter sources and credentials
To run a scan on a vCenter Server deployment, you must add a source that identifies the vCenter Server server to scan. Then you must add a credential that contains the authentication data to access that server.
5.1. Add vCenter sources
Define vCenter sources to identify vCenter Server instances and their managed virtual machines for Discovery scanning.
A vCenter source is only compatible with a vCenter deployment. You cannot use this source to scan other virtualization infrastructures, even those that are supported by Red Hat.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click Add Source.
- From the Sources view, click Add.
- On the Type page, select vCenter Server as the source type and click Next.
On the Credentials page, enter the following information:
- In the Name field, enter a descriptive name.
-
In the IP Address or Hostname field, enter the IP address or hostname of the vCenter Server for this source. Enter a different port if you do not want a scan for this source to run on the default port 443. For example, if the IP address of the vCenter Server is 192.0.2.15 and you want to change the port to 80, you would enter
192.0.2.15:80. -
Optional: In the Proxy URL field enter the proxy server needed to reach the vCenter host. This value is passed directly to the HTTP client and must match the format expected by your proxy setup, for example,
Content from proxy.example.com is not included.http://proxy.example.com:3128orContent from proxy.example.com is not included.https://proxy.example.com:443. - In the Credentials list, select the credential that is required to access the vCenter Server for this source. If a required credential does not exist, click the Add a credential icon to open the Add Credential view.
- In the Connection list, select the SSL protocol to be used for a secure connection during a scan of this source. Select Disable SSL to disable secure communication during a scan of this source.
- If you need to upgrade the SSL validation for the vCenter Server to check for a verified SSL certificate from a certificate authority, select the Verify SSL Certificate check box.
- Click Save to save the source and then click Close to close the Add Source view.
Verification
- In the Sources view, verify that the new source appears in the sources list with the correct name and type.
5.2. Add vCenter credentials
Create vCenter credentials to authenticate Discovery scans against vCenter Server instances.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click → .
- From the Add Source wizard, click the Add a credential icon for the Credentials field.
The Add Credential wizard opens.
- In the Credential Name field, enter a descriptive name.
- Enter the username and password for a vCenter Server administrator.
- Click Save to save the credential and close the Add Credential wizard.
Verification
- In the Credentials view, verify that the new credential appears in the credentials list with the correct name and type.
5.3. Red Hat Discovery sources and credentials
To run a scan, you must configure data for two basic structures: sources and credentials. The type of source that you are going to inspect during the scan determines the type of data that is required for both source and credential configuration.
A source contains a single asset or a set of multiple assets that are to be inspected during the scan. You can configure any of the following types of sources:
- Network source
- One or more physical machines, virtual machines, or containers. These assets can be expressed as hostnames, IP addresses, IP ranges, or subnets.
- vCenter source
- A vCenter Server systems management solution that is managing all or part of your IT infrastructure.
- Satellite source
- A Satellite systems management solution that is managing all or part of your IT infrastructure.
- Red Hat OpenShift source
- A Red Hat OpenShift Container Platform cluster that is managing all or part of your Red Hat OpenShift Container Platform nodes and workloads.
- Ansible source
- An Red Hat Ansible Automation Platform management solution that is managing your Red Hat Ansible Automation Platform nodes and workloads.
- Red Hat Advanced Cluster Security for Kubernetes source
- A RHACS security platform solution that secures your Kubernetes environments.
When you are working with network sources, you determine how many individual assets you should group within a single source. Currently, you can add multiple assets to a source only for network sources. The following list contains some of the other factors that you should consider when you are adding sources:
- Whether assets are part of a development, testing, or production environment, and if demands on computing power and similar concerns are a consideration for those assets.
- Whether you want to scan a particular entity or group of entities more often because of internal business practices such as frequent changes to the installed software.
A credential contains data such as the username and password or SSH key of a user with sufficient authority to run the scan on all or part of the assets in that source. As with sources, credentials are configured as the network, vCenter, satellite, OpenShift, Red Hat Ansible Automation Platform, or RHACS type. A network source might require multiple network credentials to access all assets in a broad IP range. Conversely, a vCenter or satellite source typically uses a single credential to access a particular system management solution server. An OpenShift, Red Hat Ansible Automation Platform, or RHACS source uses a single credential to access a single cluster.
You can add new sources from the Sources view and you can add new credentials from the Credentials view. You can also add new or select previously existing credentials during source creation. It is during source creation that you associate a credential directly with a source.
Because sources and credentials must have matching types, any credential that you add during source creation shares the same type as the source. If you want to use an existing credential during source creation, the list of available credentials contains only credentials of the same type. For example, during network source creation, only network credentials are available for selection.
5.4. vCenter Server authentication
vCenter scans authenticate to vCenter Server by using a username and password encrypted over HTTPS. By default, scans run with certificate validation and secure communication through SSL or TLS protocols, which you can configure during source creation.
You might need to adjust the level of certificate validation to connect properly to the vCenter server during a scan. For example, your vCenter server might use a verified SSL certificate from a certificate authority. During source creation, you can upgrade SSL certificate validation to check for that certificate during a scan of that source.
Conversely, your vCenter server might use self-signed certificates. During source creation, you can leave the SSL validation at the default so that scan of that source does not check for a certificate. This choice, to leave the option at the default for a self-signed certificate, could possibly avoid scan errors.
You might also need to disable SSL as the method of secure communication during the scan if the vCenter server is not configured to use SSL communication for web applications. For example, your vCenter server might be configured to communicate with web applications by using HTTP with port 80. If so, then during source creation you can disable SSL communication for scans of that source.
Chapter 6. Add Red Hat OpenShift sources and credentials
To run a scan on a Red Hat OpenShift Container Platform deployment, you must add a source that identifies the Red Hat OpenShift Container Platform cluster to scan. Then you must add a credential that contains the authentication data to access that cluster.
6.1. Add Red Hat OpenShift Container Platform sources
Define Red Hat OpenShift Container Platform sources to identify OpenShift clusters for Discovery scanning.
Prerequisites
- You have access to the Red Hat OpenShift Container Platform web console administrator perspective to get the API address and token values.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click Add Source.
- From the Sources view, click Add.
- On the Type page, select OpenShift as the source type and click Next.
On the Credentials page, enter the following information:
- In the Name field, enter a descriptive name.
- In the IP Address or Hostname field, enter the Red Hat OpenShift Container Platform cluster API address for this source. You can find the cluster API address by viewing the overview details for the cluster in the web console
-
Optional: In the Proxy URL field enter the proxy server needed to reach the OpenShift host. This value is passed directly to the HTTP client and must match the format expected by your proxy setup, for example,
Content from proxy.example.com is not included.http://proxy.example.com:3128orContent from proxy.example.com is not included.https://proxy.example.com:443. - In the Credentials list, select the credential that is required to access the cluster for this source. If a required credential does not exist, click the Add a credential icon to open the Add Credential view.
- In the Connection list, select the SSL protocol to be used for a secure connection during a scan of this source. Select Disable SSL to disable secure communication during a scan of this source.
- If you need to upgrade the SSL validation for the cluster to check for a verified SSL certificate from a certificate authority, select the Verify SSL Certificate check box.
- Click Save to save the source and then click Close to close the Add Source view.
Verification
- In the Sources view, verify that the new source appears in the sources list with the correct name and type.
6.2. Add Red Hat OpenShift Container Platform credentials
Create Red Hat OpenShift Container Platform credentials to authenticate Discovery scans against OpenShift clusters by using an application programming interface (API) token.
Prerequisites
- You have access to the Red Hat OpenShift Container Platform web console administrator perspective to get the API address and token values.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click → .
- From the Add Source wizard, click the Add a credential icon for the Credentials field.
The Add Credential wizard opens.
- In the Credential Name field, enter a descriptive name.
- Enter the API token for the Red Hat OpenShift Container Platform cluster from your Administrator console. You can find the API token by clicking your username in the console, clicking the Display Token option and copying the value displayed for Your API token is.
- Click Save to save the credential and close the Add Credential wizard.
Verification
- In the Credentials view, verify that the new credential appears in the credentials list with the correct name and type.
6.3. Red Hat Discovery sources and credentials
To run a scan, you must configure data for two basic structures: sources and credentials. The type of source that you are going to inspect during the scan determines the type of data that is required for both source and credential configuration.
A source contains a single asset or a set of multiple assets that are to be inspected during the scan. You can configure any of the following types of sources:
- Network source
- One or more physical machines, virtual machines, or containers. These assets can be expressed as hostnames, IP addresses, IP ranges, or subnets.
- vCenter source
- A vCenter Server systems management solution that is managing all or part of your IT infrastructure.
- Satellite source
- A Satellite systems management solution that is managing all or part of your IT infrastructure.
- Red Hat OpenShift source
- A Red Hat OpenShift Container Platform cluster that is managing all or part of your Red Hat OpenShift Container Platform nodes and workloads.
- Ansible source
- An Red Hat Ansible Automation Platform management solution that is managing your Red Hat Ansible Automation Platform nodes and workloads.
- Red Hat Advanced Cluster Security for Kubernetes source
- A RHACS security platform solution that secures your Kubernetes environments.
When you are working with network sources, you determine how many individual assets you should group within a single source. Currently, you can add multiple assets to a source only for network sources. The following list contains some of the other factors that you should consider when you are adding sources:
- Whether assets are part of a development, testing, or production environment, and if demands on computing power and similar concerns are a consideration for those assets.
- Whether you want to scan a particular entity or group of entities more often because of internal business practices such as frequent changes to the installed software.
A credential contains data such as the username and password or SSH key of a user with sufficient authority to run the scan on all or part of the assets in that source. As with sources, credentials are configured as the network, vCenter, satellite, OpenShift, Red Hat Ansible Automation Platform, or RHACS type. A network source might require multiple network credentials to access all assets in a broad IP range. Conversely, a vCenter or satellite source typically uses a single credential to access a particular system management solution server. An OpenShift, Red Hat Ansible Automation Platform, or RHACS source uses a single credential to access a single cluster.
You can add new sources from the Sources view and you can add new credentials from the Credentials view. You can also add new or select previously existing credentials during source creation. It is during source creation that you associate a credential directly with a source.
Because sources and credentials must have matching types, any credential that you add during source creation shares the same type as the source. If you want to use an existing credential during source creation, the list of available credentials contains only credentials of the same type. For example, during network source creation, only network credentials are available for selection.
6.4. Red Hat OpenShift Container Platform authentication
Red Hat OpenShift scans authenticate to the cluster application programming interface (API) address by using an API token encrypted over HTTPS. By default, scans run with certificate validation and secure communication through SSL or TLS protocols, which you can configure during source creation.
You might need to adjust the level of certificate validation to connect properly to the Red Hat OpenShift Container Platform cluster API address during a scan. For example, your Red Hat OpenShift cluster API address might use a verified SSL certificate from a certificate authority. During source creation, you can upgrade SSL certificate validation to check for that certificate during a scan of that source. Conversely, your cluster API address might use self-signed certificates. During source creation, you can leave the SSL validation at the default so that scan of that source does not check for a certificate. This choice, to leave the option at the default for a self-signed certificate, could possibly avoid scan errors.
You might also need to disable SSL as the method of secure communication during the scan. This applies if the Red Hat OpenShift cluster API address is not configured to use SSL communication for web applications. For example, your Red Hat OpenShift server might be configured to communicate with web applications by using HTTP with port 80. If so, then during source creation you can disable SSL communication for scans of that source.
Chapter 7. Add Red Hat Ansible Automation Platform sources and credentials
To run a scan on a Red Hat Ansible Automation Platform deployment, you must add a source that identifies the Ansible Automation Platform to scan. Then, you must add a credential that contains the authentication data to access that cluster.
7.1. Add Red Hat Ansible Automation Platform sources
Define Red Hat Ansible Automation Platform sources to identify Ansible Controller instances for Discovery scanning.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click Add Source.
- From the Sources view, click Add Source.
- On the Type page, select Ansible Controller as the source type and click Next.
On the Credentials page, enter the following information:
- In the Name field, enter a descriptive name.
- In the IP Address or Hostname field, enter the Red Hat Ansible Automation Platform host IP address for this source. You can find the host IP address by viewing the overview details for the controller in the portal.
-
Optional: In the Proxy URL field enter the proxy server needed to reach the Red Hat Ansible Automation Platform host. This value is passed directly to the HTTP client and must match the format expected by your proxy setup, for example,
Content from proxy.example.com is not included.http://proxy.example.com:3128orContent from proxy.example.com is not included.https://proxy.example.com:443. - In the Credentials list, select the credential that is required to access the cluster for this source. If a required credential does not exist, click the Add a credential icon to open the Add Credential view.
- In the Connection list, select the SSL protocol to be used for a secure connection during a scan of this source. Select Disable SSL to disable secure communication during a scan of this source.
- If you need to upgrade the SSL validation for the cluster to check for a verified SSL certificate from a certificate authority, select the Verify SSL Certificate check box.
- Click Save to save the source and then click Close to close the Add Source view.
Verification
- In the Sources view, verify that the new source appears in the sources list with the correct name and type.
7.2. Add Red Hat Ansible Automation Platform credentials
Create Red Hat Ansible Automation Platform credentials to authenticate Discovery scans against Ansible Controller instances.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click → .
- From the Add Source view, click the Add a credential icon for the Credentials field.
- In the Credential Name field, enter a descriptive name.
- In the User Name field, enter the username for your Ansible Controller instance.
- In the Password field, enter the password for your Ansible Controller instance.
- Click Save to save the credential.
Verification
- In the Credentials view, verify that the new credential appears in the credentials list with the correct name and type.
7.3. Red Hat Discovery sources and credentials
To run a scan, you must configure data for two basic structures: sources and credentials. The type of source that you are going to inspect during the scan determines the type of data that is required for both source and credential configuration.
A source contains a single asset or a set of multiple assets that are to be inspected during the scan. You can configure any of the following types of sources:
- Network source
- One or more physical machines, virtual machines, or containers. These assets can be expressed as hostnames, IP addresses, IP ranges, or subnets.
- vCenter source
- A vCenter Server systems management solution that is managing all or part of your IT infrastructure.
- Satellite source
- A Satellite systems management solution that is managing all or part of your IT infrastructure.
- Red Hat OpenShift source
- A Red Hat OpenShift Container Platform cluster that is managing all or part of your Red Hat OpenShift Container Platform nodes and workloads.
- Ansible source
- An Red Hat Ansible Automation Platform management solution that is managing your Red Hat Ansible Automation Platform nodes and workloads.
- Red Hat Advanced Cluster Security for Kubernetes source
- A RHACS security platform solution that secures your Kubernetes environments.
When you are working with network sources, you determine how many individual assets you should group within a single source. Currently, you can add multiple assets to a source only for network sources. The following list contains some of the other factors that you should consider when you are adding sources:
- Whether assets are part of a development, testing, or production environment, and if demands on computing power and similar concerns are a consideration for those assets.
- Whether you want to scan a particular entity or group of entities more often because of internal business practices such as frequent changes to the installed software.
A credential contains data such as the username and password or SSH key of a user with sufficient authority to run the scan on all or part of the assets in that source. As with sources, credentials are configured as the network, vCenter, satellite, OpenShift, Red Hat Ansible Automation Platform, or RHACS type. A network source might require multiple network credentials to access all assets in a broad IP range. Conversely, a vCenter or satellite source typically uses a single credential to access a particular system management solution server. An OpenShift, Red Hat Ansible Automation Platform, or RHACS source uses a single credential to access a single cluster.
You can add new sources from the Sources view and you can add new credentials from the Credentials view. You can also add new or select previously existing credentials during source creation. It is during source creation that you associate a credential directly with a source.
Because sources and credentials must have matching types, any credential that you add during source creation shares the same type as the source. If you want to use an existing credential during source creation, the list of available credentials contains only credentials of the same type. For example, during network source creation, only network credentials are available for selection.
7.4. Ansible authentication
Red Hat Ansible Automation Platform scans authenticate to the host Internet Protocol (IP) address by using a username and password over HTTPS. By default, scans use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) certificate validation, which you can configure during source creation.
You might need to adjust the level of certificate validation to connect properly to the Red Hat Ansible Automation Platform host IP address during a scan. For example, your Red Hat Ansible Automation Platform host IP address might use a verified SSL certificate from a certificate authority. During source creation, you can upgrade SSL certificate validation to check for that certificate during a scan of that source. Conversely, your host IP address might use self-signed certificates. During source creation, you can leave the SSL validation at the default so that scan of that source does not check for a certificate. This choice, to leave the option at the default for a self-signed certificate, could possibly avoid scan errors.
You might also need to disable SSL as the method of secure communication during the scan. This applies if the Red Hat Ansible Automation Platform host IP address is not configured to use SSL communication for web applications. For example, your Red Hat Ansible Automation Platform host IP address might be configured to communicate with web applications by using HTTP with port 80. If so, then during source creation you can disable SSL communication for scans of that source.
Chapter 8. Add Red Hat Advanced Cluster Security for Kubernetes sources and credentials
To run a scan on a Red Hat Advanced Cluster Security for Kubernetes (RHACS) deployment, you must add a source that identifies the RHACS instance to scan. Then you must add a credential that contains the authentication data to access that instance.
8.1. Add Red Hat Advanced Cluster Security for Kubernetes sources
Define Red Hat Advanced Cluster Security for Kubernetes sources to identify RHACS deployments for Discovery scanning.
Prerequisites
- You have access to the Red Hat Advanced Cluster Security for Kubernetes (RHACS) portal to generate admin application programming interface (API) token values.
- You have either access to the RHACS portal to find the RHACS Central endpoint or access to the RHACS Configuration Management Cloud Service instance details.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click Add Source.
- From the Sources view, click Add.
- On the Type page, select RHACS as the source type and click Next.
On the Credentials page, enter the following information:
- In the Name field, enter a descriptive name.
In the IP Address or Hostname field, enter the Red Hat Advanced Cluster Security for Kubernetes Central address for this source.
- You can find the address by viewing the network routes for the cluster if RHACS was deployed on OpenShift.
- If RHACS was deployed on the cloud, you can find this information in the instance details.
-
Optional: In the Proxy URL field enter the proxy server needed to reach the RHACS host. This value is passed directly to the HTTP client and must match the format expected by your proxy setup, for example,
Content from proxy.example.com is not included.http://proxy.example.com:3128orContent from proxy.example.com is not included.https://proxy.example.com:443. - In the Credentials list, select the credential that is required to access the cluster for this source. If a required credential does not exist, click the Add a credential icon to open the Add Credential view.
- In the Connection list, select the SSL protocol to be used for a secure connection during a scan of this source. Select Disable SSL to disable secure communication during a scan of this source.
- If you need to upgrade the SSL validation for the cluster to check for a verified SSL certificate from a certificate authority, select the Verify SSL Certificate check box.
- Click Save to save the source and then click Close to close the Add Source view.
Verification
- In the Sources view, verify that the new source appears in the sources list with the correct name and type.
8.2. Add Red Hat Advanced Cluster Security for Kubernetes credentials
Create RHACS credentials to authenticate Discovery scans against Red Hat Advanced Cluster Security for Kubernetes instances by using an API token.
Prerequisites
- You have access to the Red Hat Advanced Cluster Security for Kubernetes (RHACS) portal to generate admin API token values.
- You have either access to the RHACS portal to find the RHACS Central endpoint or access to the RHACS Configuration Management Cloud Service instance details.
Procedure
Click the option to add a new credential based on your location:
- From the Credentials view, click → .
- From the Add Source wizard, click the Add a credential icon for the Credentials field.
The Add Credential wizard opens.
- In the Credential Name field, enter a descriptive name.
- Enter the API token for RHACS from your RHACS portal. If you do not already have a token, you can generate a token on the RHACS Configuration Management Cloud Service portal.
- Click Save to save the credential and close the Add Credential wizard.
Verification
- In the Credentials view, verify that the new credential appears in the credentials list with the correct name and type.
8.3. Red Hat Discovery sources and credentials
To run a scan, you must configure data for two basic structures: sources and credentials. The type of source that you are going to inspect during the scan determines the type of data that is required for both source and credential configuration.
A source contains a single asset or a set of multiple assets that are to be inspected during the scan. You can configure any of the following types of sources:
- Network source
- One or more physical machines, virtual machines, or containers. These assets can be expressed as hostnames, IP addresses, IP ranges, or subnets.
- vCenter source
- A vCenter Server systems management solution that is managing all or part of your IT infrastructure.
- Satellite source
- A Satellite systems management solution that is managing all or part of your IT infrastructure.
- Red Hat OpenShift source
- A Red Hat OpenShift Container Platform cluster that is managing all or part of your Red Hat OpenShift Container Platform nodes and workloads.
- Ansible source
- An Red Hat Ansible Automation Platform management solution that is managing your Red Hat Ansible Automation Platform nodes and workloads.
- Red Hat Advanced Cluster Security for Kubernetes source
- A RHACS security platform solution that secures your Kubernetes environments.
When you are working with network sources, you determine how many individual assets you should group within a single source. Currently, you can add multiple assets to a source only for network sources. The following list contains some of the other factors that you should consider when you are adding sources:
- Whether assets are part of a development, testing, or production environment, and if demands on computing power and similar concerns are a consideration for those assets.
- Whether you want to scan a particular entity or group of entities more often because of internal business practices such as frequent changes to the installed software.
A credential contains data such as the username and password or SSH key of a user with sufficient authority to run the scan on all or part of the assets in that source. As with sources, credentials are configured as the network, vCenter, satellite, OpenShift, Red Hat Ansible Automation Platform, or RHACS type. A network source might require multiple network credentials to access all assets in a broad IP range. Conversely, a vCenter or satellite source typically uses a single credential to access a particular system management solution server. An OpenShift, Red Hat Ansible Automation Platform, or RHACS source uses a single credential to access a single cluster.
You can add new sources from the Sources view and you can add new credentials from the Credentials view. You can also add new or select previously existing credentials during source creation. It is during source creation that you associate a credential directly with a source.
Because sources and credentials must have matching types, any credential that you add during source creation shares the same type as the source. If you want to use an existing credential during source creation, the list of available credentials contains only credentials of the same type. For example, during network source creation, only network credentials are available for selection.
8.4. Red Hat Advanced Cluster Security for Kubernetes authentication
RHACS scans authenticate to the application programming interface (API) by using a bearer token encrypted over TLS. By default, scans run with certificate validation and secure communication through TLS protocols, which you can configure during source creation.
You might need to adjust the level of certificate validation to connect to the RHACS portal during a scan. For example, your RHACS instance might use a verified TLS certificate from a certificate authority. During source creation, you can upgrade TLS certificate validation to check for that certificate during a scan of that source.
Conversely, your RHACS instance might use self-signed certificates. During source creation, you can leave the TLS validation at the default so that scan of that source does not check for a certificate. This choice, to leave the option at the default for a self-signed certificate, could possibly avoid scan errors.
You might also need to disable TLS as the method of secure communication during the scan if the RHACS instance is not configured to use TLS communication for web applications. For example, your RHACS instance might be configured to communicate with web applications by using HTTP with port 80. If so, then during source creation you can disable TLS communication for scans of that source.
Chapter 9. Run and manage standard scans
After you add sources and credentials for the parts of your IT infrastructure that you want to scan, you can begin running scans. In most situations, you can run a standard scan to find the environment and product data that is required to report on your Red Hat products.
Currently you cannot combine an OpenShift, Red Hat Ansible Automation Platform, or RHACS scan with any other type of source in a scan. However, a single OpenShift, Red Hat Ansible Automation Platform, or RHACS scan can contain multiple sources of the same type, each of which is associated with a single cluster only.
9.1. Run standard scans
Run a standard scan to inspect your sources and detect Red Hat products installed in default locations. Select one or more sources from the Sources view to combine into a single scan.
Prerequisites
- You have added the sources that you want to scan and the credentials to access those sources.
Procedure
- From the Sources view, select one or more sources. You can select sources of different types to combine them into a single scan.
Click the Scan button that is appropriate for the selected sources:
- For a single source, click Scan on the row for that source. Selecting the check box for the source is optional.
- If you selected multiple sources, click Scan in the toolbar.
The Scan wizard opens.
- In the Name field, enter a descriptive name for the scan.
- If you want to change the default number of maximum concurrent scans, set a new value in the Maximum concurrent scans field. This value is the maximum number of physical machines or virtual machines that are scanned in parallel during a scan.
- To use the default scanning process, allow the Deep scan for these products check boxes to remain in the default, cleared state.
- To begin the scan process, click Scan.
Verification
When the scan process begins, a notification displays in the Sources view. The running scan also displays in the Scans view, with a message about the progress of the scan.
9.2. Run a new scan job
After you name a scan and run it for the first time, it is added to the Scans view. You can then run a new instance of that scan, known as a scan job, to update the data that is gathered for that scan.
Procedure
From the Scans view, click the Run Scan icon in the scan details.
NoteIn the scan details, if the most recent scan job did not complete successfully, this icon is labeled Retry Scan.
Verification
When the scan process begins, a notification displays with a message about the progress of the scan. If you want to view a completed scan, you can view the scan details and expand Previous to view all previous scan jobs.
9.3. Cancel scans
Cancel a running scan job to free system resources or address higher-priority operational needs.
Procedure
- From the Scans view, find the scan that contains the scan job that you want to cancel.
- Click Cancel Scan.
Verification
- In the Scans view, verify that the scan job status shows as canceled.
9.4. Delete scans
Deleting a scan is a nonreversible action that deletes the scan and all scan jobs for that scan. Deleted scans cannot be retrieved.
Prerequisites
- A scan has been run and is displayed in the Scans navigation.
Procedure
- From the navigation, click Scans.
- Find the row that contains the scan that you would like to delete.
- Click the Delete icon for that row.
Verification
- In the Scans view, verify that the deleted scan no longer appears in the scans list.
9.5. Scans and scan jobs
After you create sources and credentials, you can create scans. A scan groups sources into a reproducible inspection unit. Each time a saved scan runs, that instance is stored as a scan job. The output of a scan job is a report containing the facts gathered for all IT resources in the scanned sources.
A scan includes at least one source and the credentials that were associated with that source at source creation time. When the scan job runs, it uses the provided credentials to contact the assets contained in the source. It then inspects the assets to gather facts about those assets for the report. You can add multiple sources to a single scan, including a combination of different types of sources into a single scan.
Currently, you cannot combine a OpenShift source with any other type of source in a scan. However, a single OpenShift scan can contain multiple OpenShift sources, each of which is associated with a single cluster only.
9.6. Scan job inspection tasks
A scan job manages one or more inspection tasks that gather data from systems defined in the scan’s sources. These tasks handle all aspects of connecting to systems and collecting information needed to generate the scan’s reports.
When a scan job runs, Discovery creates an inspection task for each source assigned to the scan. Each inspection task connects to systems defined by its source and collects facts that Discovery uses to produce the scan’s reports.
If a source includes multiple systems, the inspection task attempts to connect to and inspect each one. If some systems are unreachable, the task records partial results based on the systems it was able to inspect.
In scans with multiple sources, each source’s inspection task runs independently of the inspection tasks for other sources. A scan job is marked as completed only if all inspection tasks across all sources finish successfully. If any inspection task fails or cannot connect to any systems in its source, the scan job is marked as failed.
9.7. Scan job life cycle
A scan job, or individual instance of a scan, moves through several states during its life cycle.
When you start a scan, a scan job is created and the scan job is in the created state. The scan job is then queued for processing and the scan job transitions to the pending state. Scan jobs run serially, in the order that they are started.
As the Discovery server reaches a specific scan job in the queue, that scan job transitions from the pending state to the running state as the processing of that scan job begins. If the scan process completes successfully, the scan job transitions to the completed state and the scan job produces results that can be viewed in a report. If the scan process results in an error that prevents successful completion of the scan, the scan job halts and the scan job transitions to the failed state. An additional status message for the failed scan contains information to help determine the cause of the failure.
Other states for a scan job result from user action that is taken on the scan job. You can pause or cancel a scan job while it is pending or running. A scan job in the paused state can be resumed. A scan job in the canceled state cannot be resumed.
Chapter 10. Run and manage deep scans
After you add sources and credentials for the parts of your IT infrastructure that you want to scan, you can begin running scans. In a few situations, running standard scans is not sufficient to find the environment and product data that is required to report on your Red Hat products.
By default, Red Hat Discovery searches for and fingerprints products by using known metadata that relates to those products. However, it is possible that you have installed these products with a process or in an installation location that makes the search and fingerprinting algorithms less effective. In that case, you need to use deep scanning to find those products.
10.1. Run scans with deep scanning
Run a deep scan to detect products installed in nonstandard locations. Deep scans use the find command and can be CPU-intensive, so use discretion on production systems. After you run a scan for the first time, the scan is saved to the Scans view. From that view, you can run the scan again to update its data.
Prerequisites
- You have added the sources that you want to scan and the credentials to access those sources.
Procedure
- From the Sources view, select one or more sources. You can select sources of different types to combine them into a single scan.
Click the Scan button that is appropriate for the selected sources:
- For a single source, click Scan on the row for that source. Selecting the check box for the source is optional.
- If you selected multiple sources, click Scan in the toolbar.
The Scan wizard opens.
- In the Name field, enter a descriptive name for the scan.
- If you want to change the default number of maximum concurrent scans, set a new value in the Maximum concurrent scans field. This value is the maximum number of physical machines or virtual machines that are scanned in parallel during a scan.
To use the deep scanning process on one or more products, supply the following information:
- Select the applicable Deep scan for these products check boxes.
-
Optional: Enter the directories that you want Discovery to scan. The default directories that are used in a deep scan are the
/,/opt,/app,/home, and/usrdirectories.
- To begin the scan process, click Scan.
Verification
When the scan process begins, a notification displays in the Sources view. The running scan also displays in the Scans view, with a message about the progress of the scan.
10.2. Run a new scan job
After you name a scan and run it for the first time, it is added to the Scans view. You can then run a new instance of that scan, known as a scan job, to update the data that is gathered for that scan.
Procedure
From the Scans view, click the Run Scan icon in the scan details.
NoteIn the scan details, if the most recent scan job did not complete successfully, this icon is labeled Retry Scan.
Verification
When the scan process begins, a notification displays with a message about the progress of the scan. If you want to view a completed scan, you can view the scan details and expand Previous to view all previous scan jobs.
10.3. Cancel scans
Cancel a running scan job to free system resources or address higher-priority operational needs.
Procedure
- From the Scans view, find the scan that contains the scan job that you want to cancel.
- Click Cancel Scan.
Verification
- In the Scans view, verify that the scan job status shows as canceled.
10.4. Delete scans
Deleting a scan is a nonreversible action that deletes the scan and all scan jobs for that scan. Deleted scans cannot be retrieved.
Prerequisites
- A scan has been run and is displayed in the Scans navigation.
Procedure
- From the navigation, click Scans.
- Find the row that contains the scan that you would like to delete.
- Click the Delete icon for that row.
Verification
- In the Scans view, verify that the deleted scan no longer appears in the scans list.
10.5. Scans and scan jobs
After you create sources and credentials, you can create scans. A scan groups sources into a reproducible inspection unit. Each time a saved scan runs, that instance is stored as a scan job. The output of a scan job is a report containing the facts gathered for all IT resources in the scanned sources.
A scan includes at least one source and the credentials that were associated with that source at source creation time. When the scan job runs, it uses the provided credentials to contact the assets contained in the source. It then inspects the assets to gather facts about those assets for the report. You can add multiple sources to a single scan, including a combination of different types of sources into a single scan.
Currently, you cannot combine a OpenShift source with any other type of source in a scan. However, a single OpenShift scan can contain multiple OpenShift sources, each of which is associated with a single cluster only.
10.6. Scan job inspection tasks
A scan job manages one or more inspection tasks that gather data from systems defined in the scan’s sources. These tasks handle all aspects of connecting to systems and collecting information needed to generate the scan’s reports.
When a scan job runs, Discovery creates an inspection task for each source assigned to the scan. Each inspection task connects to systems defined by its source and collects facts that Discovery uses to produce the scan’s reports.
If a source includes multiple systems, the inspection task attempts to connect to and inspect each one. If some systems are unreachable, the task records partial results based on the systems it was able to inspect.
In scans with multiple sources, each source’s inspection task runs independently of the inspection tasks for other sources. A scan job is marked as completed only if all inspection tasks across all sources finish successfully. If any inspection task fails or cannot connect to any systems in its source, the scan job is marked as failed.
10.7. Scan job life cycle
A scan job, or individual instance of a scan, moves through several states during its life cycle.
When you start a scan, a scan job is created and the scan job is in the created state. The scan job is then queued for processing and the scan job transitions to the pending state. Scan jobs run serially, in the order that they are started.
As the Discovery server reaches a specific scan job in the queue, that scan job transitions from the pending state to the running state as the processing of that scan job begins. If the scan process completes successfully, the scan job transitions to the completed state and the scan job produces results that can be viewed in a report. If the scan process results in an error that prevents successful completion of the scan, the scan job halts and the scan job transitions to the failed state. An additional status message for the failed scan contains information to help determine the cause of the failure.
Other states for a scan job result from user action that is taken on the scan job. You can pause or cancel a scan job while it is pending or running. A scan job in the paused state can be resumed. A scan job in the canceled state cannot be resumed.
Chapter 11. Download and review the results of completed scan reports
Maintain a unified inventory and create a complete picture of your subscription usage in connected or disconnected networks by downloading and sending scan reports to the Red Hat Hybrid Cloud Console.
11.1. Scan report types
Reports for a scan are available in two formats, a comma-separated variable (CSV) format and a JavaScript Object Notation (JSON) format. They are also available in two content types, raw output from the scan as a details report and processed content as a deployments report.
A third type of report is available, the insights report, but this report can be generated only through the Discovery command line interface. Downloading the insights report provides a .tar.gz file that you can transfer to the Red Hat Hybrid Cloud Console at cloud.redhat.com. Transferring this file allows the report data to be used in the Red Hat Lightspeed Subscriptions Inventory and in Subscription Services.
11.2. Download reports locally
From the Scans view, you can select one or more reports and download them to view the report data.
Prerequisites
- The most recent scan job for the scan that you want to download has completed successfully.
Procedure
- From the Scans view, navigate to the row of the scan for which you want to download the report.
- Click Download for that scan.
Verification
The downloaded report is saved to the downloads location for your browser as a .tar.gz file, for example, report_id_224_20190702_173309.tar.gz. The filename format is report_id_ID_DATE_TIME.tar.gz. In this format, ID is the unique report ID assigned by the server, DATE is the date in yyyymmdd format, and TIME is the time in hhmmss format based on the 24-hour system. The date and time data is determined by the interaction of the browser running the client with the server APIs.
To view the report, uncompress the .tar.gz file into a report_id_ID directory. The uncompressed report bundle includes five report files: two details reports in CSV and JSON formats, two deployments reports in CSV format, and one summary report in JSON format.
While you can view and use the output of these reports for your own internal processes, the Discovery documentation does not provide any information to help you interpret report results. Red Hat Support can provide some basic assistance related to the installation and use of Discovery. However, the support team does not provide assistance to help you understand the reports. The reports and their format are designed for use by the Red Hat Subscription Education and Awareness Program (SEAP) team during customer engagements. They are also used for other Red Hat internal processes, such as providing data to various Red Hat Hybrid Cloud Console services.
11.3. View scan summary reports in the graphical user interface
After a scan job completes, you can view a summary of the scan results directly in the Discovery graphical user interface. This eliminates the need to download and extract report files manually, offering a more efficient way to assess key results.
Prerequisites
- The most recent scan job for the scan that you want to view has completed successfully.
Procedure
- In the Scans view, locate the row for a completed scan.
- Click More Options.
- Click Scan summary.
Verification
A window opens with summary data extracted from the summary report. The summary displays a subset of the full summary report, with selected fields organized into two columns:
- Results: Results include status counts and totals, such as success rate, failure rate, or instance type.
Diagnostics: Issues or missing data identified during inspection.
Each entry includes a human-readable label and the associated count. Fields are sorted alphabetically within each column.
A scan summary might include such information as:
- Managed Ansible nodes
- Failed or unreachable inspections
- Virtual or physical instances
- Missing system metadata
Additional resources
11.4. Report creation process
The scan process discovers the systems in your IT infrastructure and inspects them to gather information about their nature and contents. It then creates a report from the information gathered during the inspection of each system.
A system is any entity that can be interrogated by the inspection tasks through an SSH connection, vCenter Server data, the Satellite Server API, or the Red Hat OpenShift cluster API. A system can be a physical or virtual machine, or it can be a different type of entity, such as a container or a cluster.
11.4.1. Facts and fingerprints
During a scan, a collection of facts is gathered for each system in each source. A fact is a single piece of data about a system. Examples include the operating system version, the number of CPU cores, or a consumed entitlement for a Red Hat product.
Facts are processed to create a summarized set of data for each system, known as a fingerprint. A fingerprint is the set of facts that identifies a unique system and its characteristics. This includes the architecture, operating system, installed products and their versions, entitlements in use, and other attributes.
Fingerprinting data is generated when you run a scan job, but the data is used to create only one type of report. When you request a details report, you receive the raw facts for that scan without any fingerprinting. When you request a deployments report, you receive the fingerprinting data that includes the results from the deduplication, merging, and post-processing processes. These processes identify installed products and versions from the raw facts, find consumed entitlements, find and merge duplicate product instances from different sources, and locate products in nondefault locations.
11.4.2. System deduplication and system merging
A single system can be found in multiple sources during a scan. For example, a virtual machine on vCenter Server could be running a Red Hat Enterprise Linux operating system installation that is also managed by Satellite. If you construct a scan that contains each type of source, vCenter, satellite, and network, that single system is reported by all three sources during the scan.
Currently, you cannot combine an OpenShift or Red Hat Ansible Automation Platform source with any other type of source in a scan. As a result, deduplication and merging processes do not apply for an OpenShift or Red Hat Ansible Automation Platform scan.
To resolve this issue and build an accurate fingerprint, Discovery feeds unprocessed system facts from the scan into a fingerprint engine. The fingerprint engine matches and merges data for systems that are found in more than one source by using the deduplication and merge processes.
The system deduplication process uses specific facts about a system to identify duplicate systems. The process moves through several phases, using these facts to combine duplicate systems in successively broader sets of data:
-
All systems from network sources are combined into a single network system set. Systems are considered to be duplicates if they have the same value for the
subscription_manager_idorbios_uuidfacts. -
All systems from vCenter sources are combined into a single vCenter system set. Systems are considered to be duplicates if they have the same value for the
vm_uuidfact. -
All systems from satellite sources are combined into a single satellite system set. Systems are considered to be duplicates if they have the same value for the
subscription_manager_idfact. -
The network system set is merged with the satellite system set to form a single network-satellite system set. Systems are considered to be duplicates if they have the same value for the
subscription_managerfact or matching MAC address values in themac_addressesfact. -
The network-satellite system set is merged with the vCenter system set to form the complete system set. Systems are considered duplicates if they have matching MAC addresses in the
mac_addressesfact. They are also duplicates if the vCentervm_uuidvalue matches the networkbios_uuidvalue.
11.4.3. System merging
After the deduplication process determines that two systems are duplicates, the next step is to perform a merge of those two systems. The merged system has a union of system facts from each source. When a fact that appears in two systems is merged, the merge process uses the following order of precedence to merge that fact, from highest to lowest:
- network source fact
- satellite source fact
- vCenter source fact
A system fingerprint contains a metadata dictionary that captures the original source of each fact for that system.
11.4.4. System post-processing
After deduplication and merging are complete, there is a post-processing phase that creates derived system facts. A derived system fact is a fact that is generated from the evaluation of more than one system fact. The majority of derived system facts are related to product identification data, such as the presence of a specific product and its version.
The following example shows how the derived system fact system_creation_date is created.
The system_creation_date fact is a derived system fact that contains the real system creation time. The value for this fact is determined by the evaluation of the following facts. The value for each fact is examined in the following order of precedence, based on accuracy of the match to the real system creation time. The highest non-empty value determines the system_creation_date fact value.
-
date_machine_id -
registration_time -
date_anaconda_log -
date_filesystem_create -
date_yum_history
11.4.5. Report creation
After report data processing is complete, the report creation process builds two reports in two formats: JavaScript Object Notation (JSON) and comma-separated variable (CSV). The details report for each format contains the raw facts with no processing. The deployments report for each format contains the output after the raw facts have passed through the fingerprinting, deduplication, merge, and post-processing processes.
The report format is designed to be used by the Red Hat Subscription Education and Awareness Program (SEAP) team during customer engagements and for other Red Hat internal processes.
You can view and use the output of these reports for your own internal processes. However, the Discovery documentation does not provide information to help you interpret report results. Red Hat Support can provide basic assistance with the installation and use of Discovery, but does not provide assistance with understanding the reports. The reports and their format are designed for use by the Red Hat Subscription Education and Awareness Program (SEAP) team during customer engagements. They are also used for other Red Hat internal processes, such as providing data to various Red Hat Hybrid Cloud Console services.
11.4.6. A fingerprint example
A fingerprint is a set of facts about a single system, including data about products, entitlements, sources, and metadata. The following example shows a partial fingerprint.
Example
{
"os_release": "Red Hat Enterprise Linux Atomic Host 7.4",
"cpu_count": 4,
"products": [
{
"name": "JBoss EAP",
"version": null,
"presence": "absent",
"metadata": {
"source_id": 5,
"source_name": "S62Source",
"source_type": "satellite",
"raw_fact_key": null
}
}
],
"entitlements": [
{
"name": "Satellite Tools 6.3",
"entitlement_id": 54,
"metadata": {
"source_id": 5,
"source_name": "S62Source",
"source_type": "satellite",
"raw_fact_key": "entitlements"
}
}
],
"metadata": {
"os_release": {
"source_id": 5,
"source_name": "S62Source",
"source_type": "satellite",
"raw_fact_key": "os_release"
},
"cpu_count": {
"source_id": 4,
"source_name": "NetworkSource",
"source_type": "network",
"raw_fact_key": "os_release"
}
},
"sources": [
{
"id": 4,
"source_type": "network",
"name": "NetworkSource"
},
{
"id": 5,
"source_type": "satellite",
"name": "S62Source"
}
]
}
The first several lines of a fingerprint show facts about the system, including facts about the operating system and CPUs. In this example, the os_release fact describes the installed operating system and release as Red Hat Enterprise Linux Atomic Host 7.4.
Next, the fingerprint lists the installed products in the products section. A product has a name, version, presence, and metadata field. In the JBoss EAP section, the presence field shows absent as the value, so the system in this example does not have Red Hat JBoss Enterprise Application Platform installed.
The fingerprint also lists the consumed entitlements for that system in the entitlements section. Each entitlement in the list has a name, ID, and metadata that describes the original source of that fact. In the example fingerprint, the system has the Satellite Tools 6.3 entitlement.
In addition to the metadata fields that are in the products and entitlements sections, the fingerprint contains a metadata section that is used for system fact metadata. For each system fact, there is a corresponding entry in the metadata section of the fingerprint that identifies the original source of that system fact. In the example, the os_release fact was found in Satellite Server, during the scan of the satellite source.
Lastly, the fingerprint lists the sources that contain this system in the sources section. A system can be contained in more than one source. For example, for a scan that includes both a network source and a satellite source, a single system can be found in both parts of the scan.
Chapter 12. Send reports to the Red Hat Hybrid Cloud Console
After you run a scan, you can send an Red Hat Lightspeed report to the Red Hat Hybrid Cloud Console at cloud.redhat.com. This report is formatted for ingestion by Red Hat Hybrid Cloud Console services.
The Red Hat Lightspeed report is a third type of report, separate from the details report and the deployments report. When you send Red Hat Lightspeed reports to the Red Hat Hybrid Cloud Console, the report data can be used by services such as Subscriptions Inventory of Red Hat Lightspeed to display host-based inventory data. It can also be used by Subscription Services to display subscription usage data.
12.1. Download and send Red Hat Lightspeed reports to the Red Hat Hybrid Cloud Console
When you need to provide report data to the Red Hat Hybrid Cloud Console services such as the Red Hat Lightspeed Subscriptions Inventory and Subscription Services, you download and send an insights report.
This type of report is different from a details report or a deployments report. A Red Hat Lightspeed report is a Discovery report with data that is similar to the deployments report. However, its contents and format are designed especially to be ingested and used by the Red Hat Hybrid Cloud Console services.
Prerequisites
- The most recent scan job for that scan has completed successfully.
- You are logged in to Red Hat Lightspeed in the Discovery graphical user interface (GUI).
Procedure
- Log in to the Discovery graphical user interface.
Find the
IDvalue for the scan job that you want to use to create an Red Hat Lightspeed report.NoteDepending on how your reports were created, you may locate them using the
Scan IDorScan Namefields that relate to the scans that produced the reports. Merged and uploaded reports may not have values in theScan IDorScan Namefields.Select
Publishto send the Lightspeed report to the Red Hat Hybrid Cloud Console and the services that can consume the reports, such as Subscriptions Inventory and Subscription Services.NoteWhile you can view the output of insights reports, the Discovery documentation does not provide any information to help you interpret Lightspeed report results. Red Hat Support can provide some basic assistance related to the installation and use of Discovery. However, the support team does not provide any assistance to help you understand the Lightspeed reports. The Lightspeed reports and their format are designed for use by Red Hat internal processes, such as providing data to various Red Hat Hybrid Cloud Console services.
Verification
- Verify that a confirmation message displays in the Discovery graphical user interface, confirming that the report was sent to the Red Hat Hybrid Cloud Console.
Additional resources
12.2. Download and publish Lightspeed reports to the Red Hat Hybrid Cloud Console with the CLI
Download and publish a Lightspeed report with the Discovery command line interface (CLI) to provide data from Discovery to Red Hat Hybrid Cloud Console services such as Red Hat Lightspeed Subscriptions Inventory and Subscription Services.
This type of report is different from the details report or deployments report contained in the .tar.gz files you may normally download from Discovery. A Lightspeed report is a Discovery report with data that is similar to the deployments report, but its contents and format are restructured specifically for use by the Red Hat Hybrid Cloud Console services.
Prerequisites
- A scan job has completed successfully, or you have successfully merged reports from previous scan jobs.
- The deployments report from that scan job or merge contains at least one valid host.
- The Discovery command line interface is installed on the same system as the Discovery server.
Procedure
Log in to the command line interface, where
server_administrator_usernameis the username for the Discovery server administrator andserver_administrator_passwordis the password for the server administrator:dsc server login --username __server_administrator_username__ --password __server_administrator_password__
Find the
report_idvalue for the scan job that you want to use to create a Lightspeed report. The following command returns the summary details for all created scan objects:dsc scan list --table
NoteIf you know the scan name but not the
report_idvalue, you can use theqpc scan show --name scan_namecommand to show the scan jobs for that scan only.Using the
report_idvalue that you located, download the Lightspeed report for the scan job. In the following example command, the file name assigned to the downloaded report isreport.tar.gzbut you can change this filename as needed:dsc report insights --report __report_id__ --output-file report.tar.gz
Add the credentials that you use to log in to the Red Hat Hybrid Cloud Console, generally your Red Hat Customer Portal account, to the command line interface configuration. This step is needed so that these credentials can be used in the next step to publish the Lightspeed report to the Red Hat Hybrid Cloud Console.
dsc insights login
Use the
publishsubcommand to publish the Lightspeed report data to the Red Hat Hybrid Cloud Console and the services that can consume the reports, such as Subscriptions Inventory and Subscription Services.dsc insights publish --input-file report.tar.gz
NoteWhile you can view the output of Lightspeed reports, the Discovery documentation does not provide any information to help you interpret Lightspeed report results. Red Hat Support can provide some basic assistance related to the installation and use of Discovery. However, the support team does not provide any assistance to help you understand the Lightspeed reports. The Lightspeed reports and their format are designed for use by Red Hat internal processes, such as providing data to various Red Hat Hybrid Cloud Console services.
Verification
- Verify that the command output confirms the Lightspeed report was published successfully to the Red Hat Hybrid Cloud Console.
Additional resources
12.3. Red Hat Lightspeed report overview
An Red Hat Lightspeed report is a specialized report formatted for Red Hat Hybrid Cloud Console services. Send it to Subscriptions Inventory for host-based inventory data and Subscription Services for subscription usage data.
Although Discovery is useful for scanning and reporting on all parts of your IT infrastructure, sending a report to the Red Hat Hybrid Cloud Console services is particularly useful for disconnected or air-gapped environments. By using Discovery to gather data about those parts of your network, you can get a more complete and more curated view of your overall network.
Red Hat Hybrid Cloud Console provides a unified inventory and a more complete picture of subscription usage. This is possible when the data from Discovery’s Red Hat Lightspeed report combines with data from other tools that support Red Hat Hybrid Cloud Console.
12.3.1. Frequency of reporting
All disconnected or air-gapped systems must be periodically scanned and reported through an Red Hat Lightspeed report to ensure that accurate data is reaching the Red Hat Hybrid Cloud Console. A weekly cadence of sending a Red Hat Lightspeed report is the current recommendation. A weekly cadence provides sufficient milestones for effectively monitoring subscription usage in Subscription Services.