bclarhk / quipucords Goto Github PK

quipucords is a tool for discovery, inspection, collection, deduplication, and reporting on an IT environment.

This README file contains information about the installation and development of quipucords, as well as instructions about where to find basic usage, known issue, and best practices information.

• Introduction to quipucords
• Requirements and Assumptions
• Installation
• Command Syntax and Usage
• Development
• Issues
• Changes
• Authors
• Contributing
• Copyright and License

quipucords is a Python based information gathering tool. quipucords provides a server base infrastructure for process tasks that discover and inspect remote systems by utilizing Ansible while additionally looking to integrate and extract data from systems management solutions. quipucords collects basic information about the operating system, hardware, and application data for each system. quipucords is intended to help simplify some of the basic system administrator tasks that are a part of the larger goal of managing licensing renewals and new deployments.

Before installing quipucords on a system, review the following guidelines about installing and running quipucords:

• quipucords is written to run on RHEL or Fedora servers.
• The system that quipucords is installed on must have access to the systems to be discovered and inspected.
• The target systems must be running SSH.
• The user account that quipucords uses for the SSH connection into the target systems must have adequate permissions to run commands and read certain files, such as privilege escalation required for the systemctl command.
• The user account that quipucords uses for a machine requires an sh shell or a similar shell. For example, the shell cannot be a /sbin/nologin or /bin/false shell.

The Python packages that are required for running quipucords on a system can be found in the requirements.txt file. The Python packages that are required to build and test quipucords from source can be found in the requirements.txt and dev-requirements.txt files.

quipucords is delivered with an RPM command line tool and a server container image. The following information contains instructions for installing each of these items.

qpc is available for download from the Fedora COPR.

1. Enable the EPEL repo for the server. You can find the appropriate architecture and version on the EPEL wiki:

   rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
   

2. Add the COPR repo to your server. You can find the appropriate architecture and version on the COPR qpc page:

   wget -O /etc/yum.repos.d/group_quipucords-qpc-epel-7.repo \
   https://copr.fedorainfracloud.org/coprs/g/quipucords/qpc/repo/epel-7/group_quipucords-qpc-epel-7.repo
   

3. Install the qpc package:

   yum -y install qpc
   

The quipucords container image can be created from source. This quipucords repository includes a Dockerfile that contains instructions for the image creation of the server. You must have Docker installed to create the image and run the container.

1. Clone the repository:

   git clone [email protected]:quipucords/quipucords.git
   

2. Build the Docker image:

   docker -D build . -t quipucords:latest
   

NOTE: The need to use sudo for this step is dependent upon on your system configuration.

3. Run the Docker image:

   docker run -d -p443:443 -i quipucords:latest
   

After you complete these steps and the server is running, you can launch the server login function. You can work with the APIs directly or you can use the command line interface. Use the following command to configure the command line interface:

qpc server config --host 127.0.0.1

The complete list of options for each qpc command and subcommand are listed in the qpc man page. The man page information also contains usage examples and some best practice recommendations.

For expanded information on credential entries, sources, scanning, and output, see the syntax and usage document.

To work with the quipucords code, begin by cloning the repository:

git clone [email protected]:quipucords/quipucords.git

quipucords currently supports Python 3.5 and 3.6. If you do not have Python on your system, follow these instructions. Based on the configuration of your system, you might be using either pip or pip3 to install modules. The following instructions show the steps for a system with pip.

You might want to isolate your development work by using a virtual environment. Run the following command to set up a virtual environment:

virtualenv -p python3 venv
source venv/bin/activate

Run the following commands from within the local clone root directory to install dependencies that are needed for development and testing purposes:

1. Collect some packages available through either yum (for RHEL) or dnf (for Fedora):

   sudo yum install python-tools
   

2. Install the rest of the packages locally in your virtual environment:

   pip install -r requirements.txt
   

To lint changes that are made to the source code, run the following command:

make lint

To set up the server, run the following command:

make server-init

This command creates a superuser with name admin and password of pass.

To run the development server, run the following command:

make serve

To log in to the server, you must connect to http://127.0.0.1:8000/admin/ and provide the superuser credentials.

After logging in, you can change the password and also go to some of the browsable APIs such as http://127.0.0.1:8000/api/v1/credentials/. To use the command line interface, you can configure access to the server by entering qpc server config. You can then log in by using qpc server login.

If you intend to run on Mac OS, there are several more steps that are required.

• Increase the maxfile limit as described here.
• Install sshpass as described here.
• Install coreutils to obtain the gtimeout command. To do this step, run the brew install coreutils command.
• If you are running macOS 10.13 or later and you encounter unexpected crashes when running scans, set the environment variable OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES before starting the server. See the explanation for this step here.

To run the unit tests with the interpreter available as python, use the following command:

make test

To report bugs for quipucords open issues against this repository in Github. Complete the issue template when opening a new bug to improve investigation and resolution time.

Track and find changes to the tool in CHANGES.

Authorship and current maintainer information can be found in AUTHORS.

See the CONTRIBUTING guide for information about contributing to the project.

Copyright 2017-2018, Red Hat, Inc.

quipucords is released under the GNU Public License version 3.