Quipucords Documentation

Transcription

1 Quipucords Documentation Release Red Hat Sep 07, 2018

2

3 Contents: 1 About Quipucords Quipucords User Guide qpc i

4 ii

5 CHAPTER 1 About Quipucords Quipucords is a Python based information gathering tool that is accessed through the qpc command and its subcommands. It enables the reporting of IT resource data based on the inspection of network or system management solution resources. Quipucords identifies environment data, or facts, such as the number of physical and virtual systems on a network, their operating systems, and other configuration data. In addition, it is designed to identify and report more detailed facts for some versions of key Red Hat packages and products for the Linux based IT resources in that network. The ability to inspect the software and systems that are running on your network improves your ability to understand and report on your entitlement usage. Ultimately, this inspection and reporting process is part of the larger system administration task of managing your inventories. 1.1 Quipucords User Guide This version of the Quipucords User Guide is provided as a preview during the pilot phase of Project Sonar. This guide is under development and is subject to substantial change. Because one of the goals of the pilot phase is to gather feedback on the documentation and workflows, you are encouraged to provide feedback about potential improvements to this information. Submit your feedback to the Project Sonar support contact address, <sonarpilot@redhat.com> About Quipucords Quipucords, accessed through the qpc command, is an inspection and reporting tool. It is designed to identify and report environment data, or facts, such as the number of physical and virtual systems on a network, their operating systems, and other configuration data. In addition, it is designed to identify and report more detailed facts for some versions of key Red Hat packages and products for the Linux based IT resources in that network. The ability to inspect the software and systems that are running on your network improves your ability to understand and report on your entitlement usage. Ultimately, this inspection and reporting process is part of the larger system administration task of managing your inventories. 1

6 Quipucords requires two types of data to access IT resources and run the inspection process. A credential defines user information such as the user name and password or SSH key of the user that runs the inspection process. A source defines the entity to be inspected, such as a host, subnet, network, or systems management solution such as vcenter Server or Red Hat Satellite, plus includes one or more credentials to use to access that network or systems management solution during the inspection process. You can save multiple credentials and sources to use with Quipucords in various combinations as you run inspection processes, or scans. When you have completed a scan, you can access the output as a report to review the results Requirements Before installing Quipucords in your environment, review the following guidelines about installing and running Quipucords: You must install Quipucords on a system that is running Red Hat Enterprise Linux 6 or 7. The system that Quipucords is installed on must have access to the systems to be discovered and inspected. The systems that are targeted for the inspection process must be running SSH. The user account that Quipucords uses for the SSH connection into the target systems, otherwise known as the credential, must have adequate permissions to run commands and read certain files, such as privilege escalation required for the systemctl command. The credential user account requires an sh shell or a similar shell. /sbin/nologin or /bin/false shell. For example, the shell cannot be a Installing Quipucords Quipucords is delivered in two parts, a command line tool as an RPM package and a server as a container image. The following instructions describe how to install the parts of Quipucords. Installing the Quipucords Command Line Tool qpc, the command line tool that is installed by RPM, is available for download from the Fedora COPR build and repository system. 1. Enable the EPEL repo for the server. You can find the appropriate architecture and version on the EPEL wiki. For Red Hat Enterprise Linux 7, enter the following command: # rpm -Uvh For Red Hat Enterprise Linux 6, enter the following command: # rpm -Uvh 2. Add the COPR repo to your server. You can find the appropriate architecture and version on the COPR qpc page. For Red Hat Enterprise Linux 7, enter the following command: # wget -O /etc/yum.repos.d/chambridge-qpc-epel-7.repo coprs/chambridge/qpc/repo/epel-7/chambridge-qpc-epel-7.repo For Red Hat Enterprise Linux 6, enter the following command: 2 Chapter 1. About Quipucords

7 # wget -O /etc/yum.repos.d/chambridge-qpc-epel-6.repo fedorainfracloud.org/coprs/chambridge/qpc/repo/epel-6/chambridge-qpc- epel-6.repo 3. Install the qpc beta package: For Red Hat Enterprise Linux 7, enter the following command: # yum -y install qpc git b5e58.el7.centos`` For Red Hat Enterprise Linux 6, enter the following command: # yum -y install qpc git b5e58.el6 Installing the Quipucords Server Requirement and Container Image The Quipucords server is delivered as a container image that runs on your server. First you must install and start the necessary prerequisite, Docker, to run the container. Then you can obtain and install the Quipucords server container image. Installing the Docker Prerequisite The instructions for installing Docker vary according to your system configuration. Installing Docker on Red Hat Enterprise Linux 7 You can install Docker in different ways, depending on your needs: You can set up the Docker repositories and then install from them. This choice is the recommended approach because it simplifies the installation and upgrade tasks. You can download the RPM package, install it manually, and manage upgrades manually. This choice is useful when Docker is installed on systems with limited or no access to the internet. Installing from the repository 1. Make sure that you are logged in as a user with sudo or root privileges. 2. Install the required packages: # sudo yum install -y yum-utils device-mapper-persistent-data lvm2 3. Add the repository: # sudo yum-config-manager add-repo 4. Install Docker from the repository: # sudo yum install docker-ce 1.1. Quipucords User Guide 3

8 Installing from a package 1. Go to For the Docker version that you want to install, download the RPM package to the intended installation system. 2. Make sure that you are logged in as a user with sudo or root privileges. 3. Install Docker, changing the path in the following example to the path where you downloaded the Docker package: # sudo yum install /path/to/package.rpm Starting Docker on Red Hat Enterprise Linux 7 After you install Docker, you must start it and verify that it is running. 1. Start Docker: # sudo systemctl start docker 2. Verify that Docker is installed correctly. To do this step, run the hello-world image: # sudo docker run hello-world After you complete the steps to install Docker for Red Hat Enterprise Linux 7 or later, continue with the Quipucords server installation steps in Installing the Quipucords Server Container Image. Installing Docker on Red Hat Enterprise Linux 6.6 or later To install Docker on Red Hat Enterprise Linux 6.6 or later, you must have kernel or later installed. To check the current kernel release, open a terminal session and use the uname command to display the kernel release information, as shown in the following example: # uname -r The output of this command is similar to the following example: el6.x86_64 TIP: After you confirm that you have at least the minimum required kernel release, it is recommended that you fully update your system. Having a fully patched system can help you avoid kernel bugs that have already been fixed on the latest kernel packages. When your system meets the minimum required kernel release, you can use the following steps to install Docker: 1. Make sure that you are logged in as a user with sudo or root privileges. 2. Download the Docker RPM package to the current directory: # curl -k -O -ssl x86_64.rpm 3. Install the Docker package with yum: # sudo yum localinstall nogpgcheck docker-engine el6.x86_64.rpm 4 Chapter 1. About Quipucords

9 Starting Docker on Red Hat Enterprise Linux 6.6 or later After you install Docker, you must start it and verify that it is running. 1. Start the Docker daemon: # sudo service docker start 2. Verify that Docker is installed correctly. To do this step, run the hello-world image: # sudo docker run hello-world This command displays output similar to the following truncated example. The first section of the output contains a message about the installation status: Unable to find image 'hello-world:latest' locally latest: Pulling from hello-world a be10: Pull complete 91c95931e552: Already exists hello-world:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security. Digest: sha256:aa03e5d0d5553b4c3473e89c8619cf79df368babd18681cf5daeb82aab55838d Status: Downloaded newer image for hello-world:latest Hello from Docker. This message shows that your installation appears to be working correctly To ensure that Docker starts when you start your system, enter the following command: # sudo chkconfig docker on After you complete the steps to install Docker for Red Hat Enterprise Linux 6.6 or later, continue with the Quipucords server installation steps in Installing the Quipucords Server Container Image. Installing the Quipucords Server Container Image After Docker is installed, you can obtain and install the container image that enables the use of the Quipucords server. 1. Download the server container image by entering the following command: # curl -k -O -ssl 2. Load the container image into the local Docker registry by entering the following command: # sudo docker load -i quipucords.pilot.tar.gz The output appears similar to the following example: Loaded image: quipucords:pilot 3. Verify the image within the local Docker registry by entering the following command: # sudo docker images The output appears similar to the following example: 1.1. Quipucords User Guide 5

10 REPOSITORY TAG IMAGE ID CREATED SIZE quipucords pilot fdadcc4b326f 3 days ago 969MB Configuring and Starting Quipucords After you install the Quipucords server container image in the image registry, you must select configuration options to be used at the time that you start the server and the command line tool. When you are sure of the options that you want to use, you can start Quipucords by starting the server and the command line tool. Selecting the Quipucords Server Configuration Options When you run the command to start the Quipucords server, you supply values for several options that affect the configuration of that server. You must make the following decisions: Accepting or changing the default exposed server port Selecting a directory for SSH keys Selecting a directory for the SQLlite database Selecting a directory for log output The following steps guide you through those choices. 1. Accept or change the default exposed server port to use for HTTPS communication. By default, the server exposes port 443, which is the standard HTTPS port. You can choose to use that port or remap the port to be used on your server. If you select to expose port 443, you would use the following option when you run the Docker command to start the server: -p 443:443. If you want to remap the port on your system, you would supply a new value for the port when you run the Docker command to start the server. The syntax of this option is -p <host_port>:<container_port>. For example, to remap the port to 8443, you would enter the following option in the command: -p 8443:443. Additionally, Docker supplies an option to select a free port for all exposed ports by using the -P option; the port mapping is then available from the sudo docker ps command. 2. Select values for the directory for SSH keys, the directory for the SQLlite database, and the directory for the log output. The most efficient way to configure these options is to create a home directory for the Quipucords server and then use that home directory for each of these three options. a. Create the home directory. The following example command creates the home directory ~/quipucords: # mkdir -p ~/quipucords b. Change to that home directory. For example: # cd ~/quipucords c. Create subdirectories to house the SSH keys, (~/quipucords/sshkeys), database (~/quipucords/ data), and log output (~/quipucords/log). For example: 6 Chapter 1. About Quipucords

11 # mkdir sshkeys # mkdir data # mkdir log Starting the Quipucords Server After you make the decisions on the configuration options for the server, you can start the Quipucords server. The following commands assume that you used the default port and the recommended steps to create a home directory and subdirectories for the SSH keys, SQLlite database, and log output during the Quipucords server configuration. If your system does not have SELinux enabled, you can start the Quipucords server with the following Docker command: # sudo docker run --name quipucords -d -p 443:443 -v ~/quipucords/sshkeys:/sshkeys -v ~/quipucords/data:/var/data -v ~/quipucords/log:/var/log -i quipucords:pilot If your system does have SELinux enabled, you must append :z to each volume as follows: # sudo docker run --name quipucords -d -p 443:443 -v ~/quipucords/sshkeys:/sshkeys:z - v ~/quipucords/data:/var/data:z -v ~/quipucords/log:/var/log:z -i quipucords:pilot These commands start the server on port 443 and map the sshkeys, data, and log directories to the ~/ quipucords home directory for the server. To view the status of the server after it is running, enter the following command: # sudo docker ps Changing the Default Password for the Quipucords Server The Quipucords server has a default administrator user with a default user name of admin and a default password of pass. To ensure the security of your Quipucords server, it is recommended that you change the default password to a different password. To change the default password for the Quipucords server, use the following steps: 1. In a browser window, enter the URL to the Quipucords server. When you enter the URL to the Quipucords server, the browser loads a web page that shows an administrative login dialog box. If the browser window is running on the same system as the server and you used the default port of 443 for the server, the URL is If the browser window is running on a remote system, or if it is on the same system but you changed the default HTTPS port, enter the URL in the following format: For example, if the IP address for the server is and the port is remapped to 8443, you would enter in the browser window. 2. In the resulting web page that contains the Quipucords administrative login dialog box, enter the default user name admin and the default password pass to log in to the Quipucords server. 3. Click Change password to enter a new password for the Quipucords server. Record the new password in an enterprise password management solution or other password management tool, as determined by the best practices for your organization. TIP: You can also enter the local or remote URL (as applicable) for the Quipucords server in a browser window to verify that the Quipucords server is responding Quipucords User Guide 7

12 Configuring the qpc Command Line Tool Connection After the Quipucords server is running, you can configure the qpc command line tool to work with the server. The qpc server config command configures the connection between the qpc command line tool and the Quipucords server. The qpc server config command takes the following options: The --host option is required. If you are using the qpc command line tool on the same system where the server is running, you can supply the loopback address as the value. Otherwise, supply the IP address for your Quipucords server. The --port option is optional. The default value for this option is 443. If you decided to remap the Quipucords default exposed server port to another port, the port option is required. You must supply the port option and the remapped value in the command, for example, --port For example, if you are configuring the command line tool on the same system as the server and the server uses the default exposed server port, you would enter the following command to configure the qpc command line tool: # qpc server config --host However, if you are configuring the command line tool on a system that is remote from the server, the Quipucords server is running on the IP address , and the port is remapped to 8443, you would enter the following command to configure the qpc command line tool: # qpc server config --host port 8443 Logging in to the Quipucords Server After the connection between the qpc command line tool and the Quipucords server is configured on the system where you want to use the command line interface, you can log in to the server and begin using the command line interface to run qpc commands. 1. To log in to the server, enter the following command: # qpc server login 2. Enter the server user name and password at the prompts. The qpc server 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 Getting Started with Quipucords You use the capabilities of Quipucords to inspect and gather information on your IT infrastructure. The following information describes how you use the qpc command line interface to complete common Quipucords tasks. The complete list of options for each qpc command and subcommand are listed in the qpc man page. Quipucords requires the configuration of two basic structures to manage the inspection process. A credential contains the access credentials, such as the user name and password or SSH key of the user, with sufficient authority to run the inspection process on a particular source. For more information about this authority, see Requirements. A source defines the entity or entities to be inspected, such as a host, subnet, network, or systems management solution such as vcenter Server or Satellite. When you create a source, you also include one or more of the configured credentials to use to access the individual entities in the source during the inspection process. You can save multiple credentials and sources to use with Quipucords in various combinations as you run inspection processes, or scans. When you have completed a scan, you can access the collection of facts in the output as a report to review the results. 8 Chapter 1. About Quipucords

13 Before You Begin: Check the Connection to the Quipucords Server In some organizations, a single person might be responsible for scanning IT resources. However, in others, multiple people might hold this responsibility. Any additional Quipucords users who did not install the Quipucords server and command line tool must ensure that the command line tool instance is configured to connect to the server and that the user name can log in to the command line interface. For more information, see the following sections: Configuring the qpc Command Line Tool Connection Logging in to the Quipucords Server Creating Credentials and Sources for the Different Source Types The type of source that you are going to inspect determines the type of data that is required for credential and source configuration. Quipucords currently supports the following source types in the source creation command: network vcenter satellite A network source is composed of one or more host names, one or more IP addresses, IP ranges, or a combination of these network resources. A vcenter, for vcenter Server, or satellite, for Satellite, source is created with the IP address or host name of that system management solution server. In addition, the source creation command references one or more credentials. Typically, a network source might include multiple credentials because it is expected that many credentials would be needed to access a broad IP range. Conversely, a vcenter or satellite source would typically use a single credential to access a particular system management solution server. The following scenarios provide examples of how you would create a network, vcenter, or satellite source and create the credentials required for each. Creating a Network Source To create a network source, use the following steps: 1. Create at least one network credential with root-level access: # qpc cred add --type network --name cred_name --username root_name [--sshkeyfile key_file] [--password] If you did not use the sshkeyfile option to provide an SSH key for the user name value, enter the password of the user with root-level access at the connection password prompt. If you want to use SSH keyfiles in the credential, you must copy the keys into the directory that you mapped to /sshkeys during Quipucords server configuration. In the example information for that procedure, that directory is ~/quipucords/sshkeys. The server references these files locally, so refer to the keys as if they are in the /sshkeys directory from the qpc command. For example, for a network credential where the /sshkeys directory for the server is mapped to ~/ quipucords/sshkeys, the credential name is roothost1, the user with root-level access is root, and the SSH key for the user is in the ~/.ssh/id_rsa file, you would enter the following commands: 1.1. Quipucords User Guide 9

14 # cp ~/.ssh/id_rsa ~/quipucords/sshkeys # qpc cred add --type network --name roothost1 --username root --sshkeyfile / sshkeys/id_rsa Privilege escalation with the become-method, become-user, and become-password options is also supported to create a network credential for a user to obtain root-level access. You can use the become-* options with either the sshkeyfile or the password option. For example, for a network credential where the credential name is sudouser1, the user with root-level access is sysadmin, and the access is obtained through the password option, you would enter the following command: # qpc cred add --type network --name sudouser1 --username sysadmin --password -- become-password After you enter this command, you are prompted to enter two passwords. First, you would enter the connection password for the username user, and then you would enter the password for the become-method, which is the sudo command by default. 2. Create at least one network source that specifies one or more network identifiers, such as a host name or host names, an IP address, a list of IP addresses, or an IP range, and one or more network credentials to be used for the scan. TIP: You can provide IP range values in CIDR or Ansible notation. # qpc source add --type network --name source_name --hosts host_name_or_file -- cred cred_name For example, for a network source where the source name is mynetwork, the network to be scanned is the /24 subnet, and the network credentials that are used to run the scan are roothost1 and roothost2, you would enter the following command: # qpc source add --type network --name mynetwork --hosts [1:254] --cred roothost1 roothost2 You can also use a file to pass in the network identifiers. If you use a file to enter multiple network identifiers, such as multiple individual IP addresses, enter each on a single line. For example, for a network profile where the path to this file is /home/user1/hosts_file, you would enter the following command: # qpc source add --type network --name mynetwork --hosts /home/user1/hosts_file -- cred roothost1 roothost2 Creating a vcenter Source To create a vcenter source, use the following steps: 1. Create at least one vcenter credential: # qpc cred add --type vcenter --name cred_name --username vcenter_user --password Enter the password of the user with access to vcenter Server at the connection password prompt. For example, for a vcenter credential where the credential name is vcenter_admin and the user with access to the vcenter Server server is admin, you would enter the following command: # qpc cred add --type vcenter --name vcenter_admin --username admin --password 10 Chapter 1. About Quipucords

15 2. Create at least one vcenter source that specifies the host name or IP address of the server for vcenter Server and one vcenter credential to be used for the scan: # qpc source add --type vcenter --name source_name --hosts host_name --cred cred_ name For example, for a vcenter source where the source name is myvcenter, the server for the vcenter Server is located at the IP address, and the vcenter credential for that server is vcenter_admin, you would enter the following command: # qpc source add --type vcenter --name myvcenter --hosts cred vcenter_admin IMPORTANT: By default, sources are scanned with full SSL validation, but you might need to adjust the level of SSL validation to connect properly to the server for vcenter Server. The source add command supports options that are commonly used to downgrade the SSL validation. The --ssl-cert-verify option can take a value of False to disable SSL certificate validation; this option would be used for any server with a self-signed certificate. The --disable-ssl option can take a value of True to connect to the server over standard HTTP. Creating a Satellite Source To create a satellite source, use the following steps: 1. Create at least one satellite credential: # qpc cred add --type satellite --name cred_name --username satellite_user -- password Enter the password of the user with access to the Satellite server at the connection password prompt. For example, for a satellite credential where the credential name is satellite_admin and the user with access is to the Satellite server is admin, you would enter the following command: # qpc cred add --type satellite --name satellite_admin --username admin --password 2. Create at least one satellite source that specifies the host name or IP address of the Satellite server, one satellite credential to be used for the scan, and the version of the Satellite server (supported version values are 6.2, 6.3): # qpc source add --type satellite --name source_name --hosts host_name --cred cred_name --satellite-version sat_ver For example, for a satellite source where the source name is mysatellite6, the Satellite server is located at the IP address, the satellite credential for that server is satellite_admin, and the version of the Satellite server is 6.2, you would enter the following command: # qpc source add --type satellite --name mysatellite6 --hosts cred satellite_admin --satellite-version 6.2 IMPORTANT: By default, sources are scanned with full SSL validation, but you might need to adjust the level of SSL validation to connect properly to the Satellite server. The source add command supports options that are commonly used to downgrade the SSL validation. The --ssl-cert-verify option can take a value of False to disable SSL certificate validation; this option would be used for any server with a self-signed certificate. The Satellite server does not support disabling SSL, so the --disable-ssl option has no effect Quipucords User Guide 11

16 Running a Scan After you set up your credentials and sources, you can run a Quipucords scan to inspect your IT environment. You can run a scan on a single source or combine sources, even sources of different types. IMPORTANT: Scans run consecutively on the Quipucords server, in the order in which the qpc scan start command for each scan is entered. To run a scan, use the following steps: Run the scan by using the scan start command, specifying one or more sources for the sources option: # qpc scan start --sources source_name1 source_name2 For example, if you want to scan the network source mynetwork and the satellite source mysatellite6, you would enter the following command: # qpc scan start --sources mynetwork mysatellite6 Showing Scan Results for an Active Scan When you run the scan start command, the output provides an identifier for that scan. You can show the scan results to follow the status of the scan by using the scan show command and specifying the provided identifier. IMPORTANT: The scan show command can show results only after the scan starts running. You can also use this command on a scan that is completed. For example, you could run the following scan as the first scan in your environment: # qpc scan start --sources mynetwork mysatellite6 The output for the command shows the following information, with 1 listed as the scan identifier: Scan "1" started To show the scan results to follow the status of that scan, you would enter the following command: # qpc scan show --id 1 Listing Scan Results In addition to showing the status of a single scan, you can also show a list of all scans that are in progress or are completed on the Quipucords server. To show this list of scans, you use the scan list command. The output of this command includes the scan identifier, the source or sources for that scan, and the current state of the scan. To show the list of scans, enter the following command: # qpc scan list Viewing the Scan Report When the scan completes, you have the capability to produce a report for that scan. You can request a report with all the details, or facts, of the scan, or request a report with a summary. The summary report process runs steps to merge the facts found during the inspection of the various hosts that are contacted during the scan. When possible, the report 12 Chapter 1. About Quipucords

17 process also runs steps to deduplicate redundant systems. For both types of reports, you can produce the report in JavaScript Object Notation (JSON) format or comma-separated values (CSV) format. To generate a summary report, enter the report summary command and specify the identifier for the scan and the format for the output file. For example, if you want to create the report summary for a scan with the scan identifier of 1 and you want to generate that report in CSV format in the ~/scan_result.csv file, you would enter the following command: # qpc report summary --id 1 --csv --output-file=~/scan_result.csv However, if you want to create the detailed report, you would use the report detail command. This command takes the same options as the report summary command. The output is not deduplicated and merged, so it contains all facts from each source. For example, to create the detailed report for a scan with the scan identifier 1, with CSV output in the ~/scan_result.csv file, you would enter the following command: # qpc report detail --id 1 --csv --output-file=~/scan_result.csv Pausing and Restarting a Scan As you use Quipucords, you might need to stop a currently running scan. 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 if a lower priority scan is currently running. When you stop a scan by using the scan pause command, you can restart that same scan by using the scan restart command. To pause and restart a scan, use the following steps: 1. Make sure that you have the scan identifier for the currently running scan. To obtain the scan identifier, see the information in Showing Scan Results for an Active Scan. 2. Enter the command to pause the scan. For example, if the scan identifier is 1, you would enter the following command: # qpc scan pause --id 1 3. When you are ready to start the scan again, enter the command to restart the scan. For example, to restart scan 1, you would enter the following command: # qpc scan restart --id 1 Logging out of the Quipucords Server When you log in to the server, the command retrieves a token that is used for authentication with subsequent command line interface commands. That token expires daily. In addition, the token is removed when you log out of the server. To log out of the server, enter the following command: # qpc server logout Contacting Project Sonar Pilot Support The Project Sonar team relies on your feedback during this pilot to improve the quality and usability of Quipucords. For issues, questions, and suggestions for improvements that are related to the Project Sonar pilot, contact the pilot support team at <sonar-pilot@redhat.com> Quipucords User Guide 13

18 When you contact the pilot support team about an issue that you encounter while using Quipucords, you might then be asked to provide certain information that can help to resolve that issue. This information might include IT environment information such as the operating system and version for the machine or machines that are running the Quipucords server and command line interface, information about Quipucords usage such as the task that you are trying to perform and the detailed scan report of the scan that was running as you encountered the issue (if applicable), or Quipucords log information, among other requests. To provide the detailed report for a scan, follow the steps in Viewing the Scan Report to generate that report. To provide log information, access the log file locations for the Quipucords server and command line interface. If you followed the recommended Quipucords server configuration options in Selecting the Quipucords Server Configuration Options, the server log files are located in the path ~/quipucords/log. The command line interface log file is ~/.local/share/qpc/qpc.log. After you generate the information that is required to assist with problem resolution, submit the information to the pilot support team according to the instructions that they provide. 1.2 qpc Name qpc - Inspect and report on product entitlement metadata from various sources, including networks and systems management solutions Synopsis qpc command subcommand [options] Description Quipucords, accessed through the qpc command, is an inspection and reporting tool. It is designed to identify environment data, or facts, such as the number of physical and virtual systems on a network, their operating systems and other configuration data. In addition, it is designed to identify and report more detailed facts for some versions of key Red Hat packages and products for the Linux based IT resources in that network. The ability to inspect the software and systems that are running on your network improves your ability to understand and report on your entitlement usage. Ultimately, this inspection and reporting process is part of the larger system administration task of managing your inventories. Quipucords uses two types of configuration to manage the inspection process. A credential contains configuration such as the username and password or SSH key of the user that runs the inspection process. A source defines the entity to be inspected, such as a host, subnet, network, or systems management solution such as vcenter Server or Satellite, plus includes one or more credentials to use to access that network or systems management solution during the inspection process. You can save multiple credentials and sources to use with Quipucords in various combinations as you run inspection processes, or scans. When you have completed a scan, you can access the output as a report to review the results. By default, the credentials and sources that are created when using Quipucords are encrypted in a database. The values are encrypted with AES-256 encryption. They are decrypted when the Quipucords server runs a scan, by using a vault password to access the encrypted values that are stored in the database. Quipucords is an agentless inspection tool, so there is no need to install the tool on multiple systems. Inspection for the entire network is centralized on a single machine. 14 Chapter 1. About Quipucords

19 This man page describes the commands, subcommands, and options for the qpc command and includes usage information and example commands Usage The qpc command has several subcommands that encompass the inspection and reporting workflow. Within that workflow, qpc performs the following major tasks: Logging in to the server: qpc server login --username admin Creating credentials: qpc cred add --name=credname1 --type=type --username=user1 --password Creating sources: qpc source add --name=sourcename1 --type=type --hosts server1.example.com server2.example.com --cred credname1 credname2 Running a scan: qpc scan start --sources sourcename1 Working with scans: qpc scan show --id=1 Generating reports: qpc report summary --id 1 --csv --output-file=~/scan_result.csv The following sections describe these commands, their subcommands, and their options in more detail. They also describe additional tasks that are not highlighted in the previous list of major workflow tasks Server Authentication Use the qpc server command to configure connectivity with the server and to log in to and log out of the server. Configuring the server To configure the connection to the server, supply the host address. Supplying a port for the connection is optional. qpc server config host= host [ port= port ] --host=host Required. Sets the host address for the server. If you are running the qpc command on the same system as the server, the default host address for the server is port=port Optional. Sets the port to use to connect to the server. The default is qpc 15

20 Logging in to the server To log in to the server after the connection is configured, use the login subcommand. This command retrieves a token that is used for authentication with subsequent command line interface commands. qpc server login [ username= username ] --username=username Optional. Sets the username that is used to log in to the server. Logging out of the server To log out of the server, use the logout subcommand. This command removes the token that was created when the login command was used. qpc server logout Credentials Use the qpc cred command to create and manage credentials. A credential defines a set of user authentication information to be used during a scan. A credential includes a username and a password or SSH key. Quipucords uses SSH to connect to servers on the network and uses credentials to access those servers. When a scan runs, it uses a source that contains information such as the host names, IP addresses, a network, or a systems management solution to be accessed. The source also contains references to the credentials that are required to access those systems. A single source can contain a reference to multiple credentials as needed to connect to all systems in that network or systems management solution. Creating and Editing Credentials To create a credential, supply the type of credential and supply SSH credentials as either a username-password pair or a username-key pair. Quipucords stores each set of credentials in a separate credential entry. qpc cred add name= name type= (network vcenter satellite) username= username ( password sshkeyfile= key_file ) [ sshpassphrase] become-method= (sudo su pbrun pfexec doas dzdo ksu runas ) become-user= user [ become-password] --name=name Required. Sets the name of the new credential. For the value, use a descriptive name that is meaningful to your organization. For example, you could identify the user or server that the credential relates to, such as admin12 or server1_jdoe. Do not include the password as part of this value, because the value for the --name option might be logged or printed during qpc execution. --type=type Required. Sets the type of credential. The value must be network, vcenter, or satellite. The type cannot be edited after a credential is created. --username=username Required. Sets the username of the SSH identity that is used to bind to the server. --password 16 Chapter 1. About Quipucords

21 Prompts for the password for the --username identity. Mutually exclusive with the --sshkeyfile option. --sshkeyfile=key_file Sets the path of the file that contains the private SSH key for the --username identity. Mutually exclusive with the --password option. --sshpassphrase Prompts for the passphrase to be used when connecting with an SSH keyfile that requires a passphrase. Can only be used with the --sshkeyfile option. --become-method=become_method Sets the method to become for privilege escalation when running a network scan. The value must be sudo, su, pbrun, pfexec, doas, dzdo, ksu, or runas. The default is set to sudo when the credential type is network. --become-user=user Sets the user to become when running a privileged command during a network scan. --become-password Prompts for the privilege escalation password to be used when running a network scan. The information in a credential, such as a password, become password, SSH keys, the become_method, or even the username, might change. For example, network security might require passwords to be updated every few months. Use the qpc cred edit command to change credential information. The parameters for qpc cred edit are the same as those for qpc cred add. qpc cred edit name= name username= username ( password sshkeyfile= key_file ) [ sshpassphrase] become-method= (sudo su pbrun pfexec doas dzdo ksu runas ) become-user= user [ become-password] Listing and Showing Credentials The qpc cred list command returns the details for every credential that is configured for Quipucords. This output includes the name, username, password, SSH keyfile, and sudo password for each entry. Passwords are masked if provided, if not, they will appear as null. qpc cred list type= (network vcenter satellite) --type=type Optional. Filters the results by credential type. The value must be network, vcenter, or satellite. The qpc cred show command is the same as the qpc cred list command, except that it returns details for a single specified credential. qpc cred show name= name --name=name Required. Contains the name of the credential entry to display. Clearing Credentials As the network infrastructure changes, it might be necessary to delete some credentials. Use the clear subcommand to delete credentials qpc 17

22 IMPORTANT: Remove or change the credential from any source that uses it before clearing a credential. Otherwise, any attempt to use the source to run a scan runs the command with a nonexistent credential, an action that causes the qpc command to fail. qpc cred clear ( name name all) --name=name --all Contains the credential to clear. Mutually exclusive with the --all option. Clears all credentials. Mutually exclusive with the --name option Sources Use the qpc source command to create and manage sources. A source defines a collection of network information, including IP addresses or host names, or systems management solution information, in addition to SSH ports and SSH credentials. The SSH credentials are provided through reference to one or more credentials. A scan can reference a source so that the act of running the scan is repeatable, without a requirement to reenter network information for each scan attempt. Creating and Editing Sources To create a source, supply the type of source with the type option, one or more host names or IP addresses to connect to with the --hosts option, and the credentials needed to access those systems with the --cred option. The qpc source command allows multiple entries for the hosts and cred options. Therefore, a single source can access a collection of servers and subnets as needed to create an accurate and complete scan. qpc source add name= name type= (network vcenter satellite) hosts ip_address cred credential [ port= port ] [ satellite-version= version ] [ ssl-cert-verify= {True,False} ] [ ssl-protocol= protocol ] [ disable-ssl= {True,False} ] --name=name Required. Sets the name of the new source. For the value, use a descriptive name that is meaningful to your organization, such as APSubnet or Lab3. --type=type Required. Sets the type of source. The value must be network, vcenter, or satellite. The type cannot be edited after a source is created. --hosts ip_address Sets the host name, IP address, or IP address range to use when running a scan. You can also provide a path for a file that contains a list of host names or IP addresses or ranges, where each item is on a separate line. The following examples show several different formats that are allowed as values for the --hosts option: A specific host name: hosts server.example.com A specific IP address: hosts Chapter 1. About Quipucords

23 An IP address range, provided in CIDR or Ansible notation. network type: hosts [0:255] or hosts /24 A file: hosts /home/user1/hosts_file --cred credential This value is only valid for the Contains the name of the credential to use to authenticate to the systems that are being scanned. If the individual systems that are being scanned each require different authentication credentials, you can use more than one credential. To add multiple credentials to the source, separate each value with a space, for example: --cred first_auth second_auth IMPORTANT: A credential must exist before you attempt to use it in a source. A credential must be of the same type as the source. --port=port Optional. Sets a port to be used for the scan. This value supports connection and inspection on a nonstandard port. By default, a network scan runs on port 22 and a vcenter or satellite scan runs on port satellite-version=satellite_version Optional. Sets the version of the Satellite server to be used for the scan. The value must be 6.2 or ssl-cert-verify={true,false} Optional. Determines whether SSL certificate validation will be performed for the scan. --ssl-protocol=protocol Optional. Determines the SSL protocol to be used for a secure connection during the scan. The value must be SSLv23, TLSv1, LSv1_1, or TLSv1_2. --disable-ssl={true,false} Optional. Determines whether SSL communication will be disabled for the scan. The information in a source might change as the structure of the network changes. Use the qpc source edit command to edit a source to accommodate those changes. Although qpc source options can accept more than one value, the qpc source edit command is not additive. To edit a source and add a new value for an option, you must enter both the current and the new values for that option. Include only the options that you want to change in the qpc source edit command. Options that are not included are not changed. qpc source edit name name [ hosts ip_address ] [ cred credential ] [ port= port ] [ satellite_version= version ] [ ssl-cert-verify= {True,False} ] [ ssl-protocol= protocol ] [ disable-ssl= {True,False} ] For example, if a source contains a value of server1creds for the --cred option, and you want to change that source to use both the server1creds and server2creds credentials, you would edit the source as follows: qpc source edit --name=mysource --cred server1creds server2creds TIP: After editing a source, use the qpc source show command to review those edits qpc 19

24 Listing and Showing Sources The qpc source list command returns the details for all configured sources. The output of this command includes the host names, IP addresses, or IP ranges, the credentials, and the ports that are configured for each source. qpc source list [ type= (network vcenter satellite) ] --type=type Optional. Filters the results by source type. The value must be network, vcenter, or satellite. The qpc source show command is the same as the qpc source list command, except that it returns details for a single specified source. qpc source show name= source --name=source Required. Contains the source to display. Clearing Sources As the network infrastructure changes, it might be necessary to delete some sources. Use the qpc source clear command to delete sources. qpc source clear ( name= name all) --name=name --all Contains the name of the source to clear. Mutually exclusive with the --all option. Clears all stored sources. Mutually exclusive with the --name option Scans Use the qpc scan start command to run scans on one or more sources. This command scans all of the host names or IP addresses that are defined in the supplied sources. Each instance of a scan is assigned a unique identifier to identify the scan results, so that the results data can be viewed later. IMPORTANT: If any ssh-agent connection is set up for a target host, that connection will be used as a fallback connection. qpc scan start sources= source_list [ max-concurrency= concurrency ] disable-optional-products= products_list --sources=source_list Required. Contains the list of source names to use to run the scan. --max-concurrency=concurrency Contains the maximum number of parallel system scans. If this value is not provided, the default is disable-optional-products=products_list Contains the list of products to exclude from inspection. To add multiple values to the list, separate each value with a space. Valid values are jboss_eap, jboss_fuse, and jboss_brms. 20 Chapter 1. About Quipucords