quipucords - Tool for discovery, inspection, collection, deduplication, and reporting on an IT environment. 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.
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.
Before installing quipucords on a system, review the following guidelines about installing and running quipucords:
- quipucords is written to run as a container image.
- 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
systemctlcommand. - 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 pyproject.toml file in the section
"tool.poetry.dependencies". Packages for development and testing are in the section "tool.poetry.group.dev.dependencies".
Finally, python packages for compiling quipucords from source can be found in requirements-build.txt.
quipucords server is delivered as a container image on quay.io. As so, the only requirement for
it is having podman, docker or any alternative to those.
podman run -d --name quipucords -e "QPC_DBMS=sqlite" -p 9443:443 -i quay.io/quipucords/quipucords:latest
Then open a browser and head to https://localhost:9443
For more info on how to install, configure, and/or even build from source refer to installation instructions
See qpc cli installation instructions for information.
To work with the quipucords code, begin by cloning the repository:
git clone git@github.com:quipucords/quipucords.git
quipucords currently supports Python 3.9. If you do not have Python on your system, follow these instructions.
This project uses poetry to manage it's python dependencies. To install them all, just run the following
poetry install
Quipucords environment variables for configuration. Our recommendation is to use the "poetry
dotenv" plugin to handle those (poetry self add poetry-dotenv-plugin), then add desired environment variables to the .env file. You can copy .env.example to get started.
Quipucords currently supports both SQLite and PostgreSQL. The default database is an internal postgres container.
All defaults point to this option. Just run the following (requires docker-compose)
make setup-postgres
These are the environment variables required to configure quipucords to use a custom postgresql instance.
QPC_DBMS=postgres
QPC_DBMS_DATABASE=<name of the database>
QPC_DBMS_HOST=<hostname or ip address of the database>
QPC_DBMS_PASSWORD=<db password>
QPC_DBMS_PORT=<db port>
QPC_DBMS_USER=<db user>
To use sqlite just set the following environment variable
QPC_DBMS=sqlite
make server-init
Both of the above commands create a superuser with name admin and password of qpcpassw0rd.
Currently, quipucords needs quipucords-ui to run. In order to get it's latest version, run
make fetch-ui
make server-static
If you prefer to build it from source, then make build-ui rule will be used instead.
See quipucords-ui installation instructions for further information.
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 and provide the superuser credentials stated above.
After logging in, you can change the password and also go to some 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.
- 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=YESbefore starting the server. See the explanation for this step here. - If installing dependencies fails involving openssl (
psycopg2-binarymay need this if using custom pyenv paths):brew install openssl export LDFLAGS="-I$(brew --prefix)/opt/openssl/include -L$(brew --prefix)/opt/openssl/lib" poetry install
To lint changes that are made to the source code, run the following command:
make lint
To run the unit tests, use the following command:
make test
To test quipucords against virtual machines running on a cloud provider, view the documentation found here.
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.
Authorship and current maintainer information can be found in AUTHORS.
See the CONTRIBUTING guide for information about contributing to the project.
Copyright 2017-2023, Red Hat, Inc.
quipucords is released under the GNU Public License version 3.