Chapter 4. Running and managing scans
Chapter 4. Running and managing scans After you add sources and credentials for the parts of your IT infrastructure that you want to scan, you can create and run scans. When you create a scan, you can choose to scan a single source or combine multiple sources from different source types. You can also choose whether to run a standard scan for products that are installed with default installation processes and locations or to run a deep scan if products might be installed with nonstandard processes or locations. Note Currently you cannot combine an OpenShift, Ansible, or RHACS scan with any other type of source in a scan. However, a single OpenShift, Ansible, or RHACS scan can contain multiple sources of the same type, each of which is associated with a single cluster only. After a scan is created, you can run that scan multiple times. Each instance of that scan is saved as a scan job. Learn more To learn more about running a standard scan that does not use deep scanning for products, see the following information: Running and managing standard scans To learn more about running a deep scan, a scan that can find products that might have been installed with a nonstandard process or in a nonstandard location, see the following information: Running and managing deep scans 4.1. Running and managing 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. Learn more Run a standard scan to find products in standard locations. To learn more, see the following information: Running standard scans When you begin running scans, there are several tasks that you can do to manage your scans. These tasks include updating the data for a scan by running a new scan job and managing active scans by pausing, resuming, and canceling. When you are finished with a scan, you can delete it. To learn more, see the following information: Running a new scan job Pausing, resuming, and canceling scans Deleting scans To learn more about how scans and scan jobs work, including how a scan job is processed by Discovery and the states a scan job moves through during its life cycle, see the following information: About scans and scan jobs Scan job processing Scan job life cycle 4.1.1. Running standard scans You can run a new scan from the Sources view. You can run a scan for a single source or select multiple sources to combine into a single scan. Each time that you use the Sources view to run a scan, you are prompted to save it as a new scan. Note Currently you cannot combine an OpenShift, Ansible, or RHACS scan with any other type of source in a scan. However, a single OpenShift, Ansible, or RHACS scan can contain multiple sources of the same type, each of which is associated with a single cluster only. After you run a scan for the first time, the scan is saved to the Scans view. From that view, you can run that scan again to update its data. Each time that you run a scan from the Scans view, it is saved as a new scan job for that scan. Prerequisites To run a scan, you must first add 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 steps 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. 4.1.2. Running 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. Note In the scan details, if the most recent scan job did not complete successfully, this icon is labeled Retry Scan . Verification steps 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 to view all scan jobs. 4.1.3. Pausing, resuming, and canceling scans As you begin running scans, you might need to stop a scan job that is currently running. There might be various business reasons that require you to do this, for example, the need to do an emergency fix due to an alert from your IT health monitoring system or the need to run a higher priority scan that consumes more CPU resources than a lower priority scan that is currently running. You can stop a scan job by either pausing it or canceling it. You can resume a paused scan job, but you cannot resume a canceled scan job. Procedure To pause a scan job that is running: From the Scans view, find the scan that contains the scan job that you want to pause. Click Pause Scan . Note If you have multiple scans running at the same time, it might take several moments after starting a scan for the Pause Scan icon to appear. To resume a scan job that is paused: From the Scans view, find the scan that contains the scan job that you want to resume. Click Resume Scan . To cancel a scan job that is running: From the Scans view, find the scan that contains the scan job that you want to cancel. Click Cancel Scan . 4.1.4. Deleting 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 To delete a scan, a scan needs to be run first for it to display 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. Result Your scan is deleted. 4.1.5. About scans and scan jobs After you create sources and credentials, you can create scans. A scan is an object that groups sources into a unit that can be inspected, or scanned, in a reproducible way. Each time that you run a saved scan, that instance is saved as a scan job . The output of a scan job is a report , the collection of facts gathered for all IT resources that are contained in that source. 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 and then it 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. Note 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. 4.1.6. Scan job processing A scan job moves through two phases, or tasks, while it is being processed. These two tasks are the connection task and the inspection task. 4.1.6.1. Scan job connection and inspection tasks The first task that runs during a scan job is a connection task. The connection task determines the ability to connect to the source and finds the number of systems that can be inspected for the defined source. The second task that runs is an inspection task. The inspection task is the task that gathers data from each of the reachable systems in the defined source to output the scan results into a report. If the scan is configured so that it contains several sources, then when the scan job runs, these two tasks are created for each source. First, all of the connection tasks for all of the sources run to establish connections to the sources and find the systems that can be inspected. Then all of the inspection tasks for all of the sources run to inspect the contents of the reachable systems that are contained in the sources. 4.1.6.2. How these tasks are processed When the scan job runs the connection task for a source, it attempts to connect to the network, the server, the cluster, or the instance used. If the connection fails, then the connection task fails. For a network scan, if the network is not reachable or the credentials are invalid, the connection task reports zero (0) successful systems. If only some of the systems for a network scan are reachable, the connection task reports success on the systems that are reachable, and the connection task does not fail. You can view information about the status of the connection task in the Scans view. The row for a scan displays the connection task results as the number of successful system connections for the most recent scan job. You can also expand the scan jobs to see the connection task results for a scan job. When the scan job runs the inspection task for a source, it checks the state of the connection task. If the connection task shows a failed state or if there are zero (0) successful connections, the scan job transitions to the failed state. However, if the connection task reports at least one successful connection, the inspection task continues. The results for the scan job then show success and failure data for each individual system. If the inspection task is not able to gather results from the successful systems, or if another unexpected error occurs during the inspection task, then the scan job transitions to the failed state. If a scan contains multiple sources, each source has its own connection and inspection tasks. These tasks are processed independently from the tasks for the other sources. If any task for any of the sources fails, the scan job transitions to the failed state. The scan job transitions to the completed state only if all scan job tasks for all sources complete successfully. If a scan job completes successfully, the data for that scan job is generated as a report. In the Scans view, you can download the report for each successful scan job. 4.1.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. 4.2. Running and managing 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. Learn more Run a deep scan to find products in nonstandard locations. To learn more, see the following information: Running scans with deep scanning When you begin running scans, there are several tasks that you can do to manage your scans. These tasks include updating the data for a scan by running a new scan job and managing active scans by pausing, resuming, and canceling. When you are finished with a scan, you can delete it. To learn more, see the following information: Running a new scan job Pausing, resuming, and canceling scans Deleting scans To learn more about how scans and scan jobs work, including how a scan job is processed by Discovery and the states a scan job moves through during its life cycle, see the following information: About scans and scan jobs Scan job processing Scan job life cycle 4.2.1. Running scans with deep scanning You can run a new scan from the Sources view. You can run a scan for a single source or select multiple sources to combine into a single scan. As part of the scan configuration, you might choose to use the deep scanning process to search for products in nonstandard locations. Note Currently you cannot combine a OpenShift, Ansible or RHACS scan with any other type of source in a scan. However, a single OpenShift, Ansible or RHACS scan can contain multiple OpenShift, Ansible or RHACS sources, each of which is associated with a single cluster only. The deep scanning process uses the find command, so the search process could be CPU resource intensive for the systems that are being scanned. Therefore, you should use discretion when selecting a deep scan for systems that require continuous availability, such as 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 To run a scan, you must first add 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. Optionally, 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 /usr directories. To begin the scan process, click Scan . Verification steps 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. 4.2.2. Running 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. Note In the scan details, if the most recent scan job did not complete successfully, this icon is labeled Retry Scan . Verification steps 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 to view all scan jobs. 4.2.3. Pausing, resuming, and canceling scans As you begin running scans, you might need to stop a scan job that is currently running. There might be various business reasons that require you to do this, for example, the need to do an emergency fix due to an alert from your IT health monitoring system or the need to run a higher priority scan that consumes more CPU resources than a lower priority scan that is currently running. You can stop a scan job by either pausing it or canceling it. You can resume a paused scan job, but you cannot resume a canceled scan job. Procedure To pause a scan job that is running: From the Scans view, find the scan that contains the scan job that you want to pause. Click Pause Scan . Note If you have multiple scans running at the same time, it might take several moments after starting a scan for the Pause Scan icon to appear. To resume a scan job that is paused: From the Scans view, find the scan that contains the scan job that you want to resume. Click Resume Scan . To cancel a scan job that is running: From the Scans view, find the scan that contains the scan job that you want to cancel. Click Cancel Scan . 4.2.4. Deleting 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 To delete a scan, a scan needs to be run first for it to display 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. Result Your scan is deleted. 4.2.5. About scans and scan jobs After you create sources and credentials, you can create scans. A scan is an object that groups sources into a unit that can be inspected, or scanned, in a reproducible way. Each time that you run a saved scan, that instance is saved as a scan job . The output of a scan job is a report , the collection of facts gathered for all IT resources that are contained in that source. 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 and then it 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. Note 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. 4.2.6. Scan job processing A scan job moves through two phases, or tasks, while it is being processed. These two tasks are the connection task and the inspection task. 4.2.6.1. Scan job connection and inspection tasks The first task that runs during a scan job is a connection task. The connection task determines the ability to connect to the source and finds the number of systems that can be inspected for the defined source. The second task that runs is an inspection task. The inspection task is the task that gathers data from each of the reachable systems in the defined source to output the scan results into a report. If the scan is configured so that it contains several sources, then when the scan job runs, these two tasks are created for each source. First, all of the connection tasks for all of the sources run to establish connections to the sources and find the systems that can be inspected. Then all of the inspection tasks for all of the sources run to inspect the contents of the reachable systems that are contained in the sources. 4.2.6.2. How these tasks are processed When the scan job runs the connection task for a source, it attempts to connect to the network, the server, the cluster, or the instance used. If the connection fails, then the connection task fails. For a network scan, if the network is not reachable or the credentials are invalid, the connection task reports zero (0) successful systems. If only some of the systems for a network scan are reachable, the connection task reports success on the systems that are reachable, and the connection task does not fail. You can view information about the status of the connection task in the Scans view. The row for a scan displays the connection task results as the number of successful system connections for the most recent scan job. You can also expand the scan jobs to see the connection task results for a scan job. When the scan job runs the inspection task for a source, it checks the state of the connection task. If the connection task shows a failed state or if there are zero (0) successful connections, the scan job transitions to the failed state. However, if the connection task reports at least one successful connection, the inspection task continues. The results for the scan job then show success and failure data for each individual system. If the inspection task is not able to gather results from the successful systems, or if another unexpected error occurs during the inspection task, then the scan job transitions to the failed state. If a scan contains multiple sources, each source has its own connection and inspection tasks. These tasks are processed independently from the tasks for the other sources. If any task for any of the sources fails, the scan job transitions to the failed state. The scan job transitions to the completed state only if all scan job tasks for all sources complete successfully. If a scan job completes successfully, the data for that scan job is generated as a report. In the Scans view, you can download the report for each successful scan job. 4.2.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.