Skip to content
This repository has been archived by the owner on Jun 29, 2022. It is now read-only.

Commit

Permalink
restructure document structure
Browse files Browse the repository at this point in the history
  • Loading branch information
@chambridge
chambridge committed Jun 22, 2017
1 parent 11e1f7f commit 618f46e
Show file tree
Hide file tree
Showing 6 changed files with 299 additions and 272 deletions.
1 change: 0 additions & 1 deletion AUTHORS
View file

This file was deleted.

8 changes: 8 additions & 0 deletions AUTHORS.rst
View file
@@ -0,0 +1,8 @@
rho was written by Adrian Likins <alikins@redhat.com>, Devan Goodwin
<dgoodwin@redhat.com>, and Jesus M. Rodriguez <jesusr@redhat.com>.

rho 2.0 was written by Karthik Harihar Reddy Battula <karthikhhr@gmail.com>,
Chris Hambridge <chambrid@redhat.com>, and Noah Lavine <nlavine@redhat.com>.

rho is maintained by Chris Hambridge <chambrid@redhat.com>
and Noah Lavine <nlavine@redhat.com>
16 changes: 16 additions & 0 deletions CHANGES.rst
View file
@@ -0,0 +1,16 @@
----------------
Changes
----------------
version 2.0
* Made rho rely on Ansible for all of it's scanning needs.

version 0.2
* Added ability to detect and correctly categorize virtual hosts and guests.

version 0.1 (Initial release)
* Runs scans for RHEL systems, upstream (Fedora) systems, downstream (CentOS) systems, and other flavors of Linux and Unix.
* Introduces auth and profile configuration for setting up rho.
* Scans user-defined IP address ranges and hostnames for an entire network or subnet.
* Allows existing JSON configuration files to be loaded for configuration.
* Outputs results to CSV file reports.
* Allows the report format to be customized.
289 changes: 18 additions & 271 deletions README.rst
View file
@@ -1,5 +1,5 @@
====================================================================
rho - FLOSS tool for discovering RHEL, Linux, and Unix Servers
rho - Tool for discovering RHEL, Linux, and Unix Servers
====================================================================

rho is a tool for scanning a network, logging into systems using SSH, and
Expand All @@ -11,7 +11,7 @@ command and command options with rho, see the manpage.


-------------
INTRO TO RHO
Intro to rho
-------------
rho is an Ansible-based network inventory tool. rho scans a user-defined range
of machines and then reports basic information about the operating system and
Expand Down Expand Up @@ -54,7 +54,7 @@ roles are used by 'rho_playbook.yml' to perform the fact collection.
Running the scan is simple. Just point the rho tool to the profile
to use, the facts to collect and print the results to a CSV output file.
Optional parameters are the number of forks Ansible should use and whether
or not to process the profile using '--reset'. A newly created or
or not to process the profile using ``--reset``. A newly created or
freshly edited profile has to be processed using reset so that it creates
an Ansible inventory called '<profile name>_hosts' that includes the working
hosts matched with an auth each (the auths are chosen in the order passed in
Expand All @@ -81,7 +81,7 @@ returns that information with every scan, by default.


--------------------------
REQUIREMENTS & ASSUMPTIONS
Requirements & Assumptions
--------------------------
Before installing rho, there are some guidelines about which machine it should be installed on:
* rho is written to run on RHEL or Fedora servers.
Expand All @@ -99,7 +99,7 @@ These python packages are required for the rho install machine to run rho:
* ansible.module_utils.basic
* babel

The following python packages are required to build rho from source:
The following python packages are required to build & test rho from source:
* python-devel
* python-setuptools
* pytest
Expand All @@ -110,7 +110,7 @@ The following python packages are required to build rho from source:
* Coverage

-------------
INSTALLATION
Installation
-------------
rho is available for `download <http://download.fedora.redhat.com/pub/epel/>`_ with the other Fedora EPEL packages.

Expand All @@ -123,7 +123,7 @@ rho is available for `download <http://download.fedora.redhat.com/pub/epel/>`_ w
``yum install rho``

-----------------------
COMMAND SYNTAX & USAGE
Command Syntax & Usage
-----------------------
The basic syntax is:

Expand All @@ -144,281 +144,28 @@ The complete list of options for each command and subcommand are listed in the
rho manpage with other usage examples. The common options are listed with the
examples in this README.

^^^^^^^^^^^^^
AUTH ENTRIES
^^^^^^^^^^^^^
The first step to configuring rho is adding auth credentials to use to connect
over SSH. Each authentication identity requires its own auth entry.

``rho auth add --name server1creds --username rho-user --sshkeyfile /etc/ssh/ssh_host_rsa_key``

*Note:* --password not being passed or passed as empty are considered the same thing.

^^^^^^^^^
PROFILES
^^^^^^^^^
Then, create the profile to use for the scan. This should include a list of IP
addresses or ranges, and the auth identity to use.

``rho profile edit --name profile1 --hosts "1.2.3.0 - 1.2.3.255" --auth server1creds server2creds``

The hosts can be passed in as a file with all the ranges listed in newlines.

^^^^^^^^^
SCANNING
^^^^^^^^^
The arguments required for a scan are the profile to use, the file path for the report
and the facts to be collected. Optionally we can pass the number of Ansible forks.
Finally an important argument is 'reset'. This tells rho that the profile you are
passing in is either new or has been updated with changes in either the hosts or
auths or both and that rho has to process it afresh.

``rho scan --reset --profile profile1 --facts default --reportfile report.csv``

Since rho collects the successful host auth mappings from a full scan with reset
the user doesn't have to worry about iterating through multiple auths and hosts
again and again in the same profile as long as the profile hasn't changed.
For purposes of record keeping the host mapping files are always written to whenever
a scan is done using a profile. When profiles are deleted the host auth mappings
corresponding to the profile are renamed with prefix *(DELETED PROFILE)* so that
they are recognizable. Every scan has a timestamp in the mappings.

As far as the auths used by the inventory of a particular scan is concerned, it
is important to note that the order of the auths passed into a profile matters.
A profile by definition takes in one ordering of auths and all the hosts in
the profile are tested in that order with the auths before the first auths to
work are picked to run the fact collection. Therefore, it's up to the user
to pass in auths as per the priority they deem fit for a profile. If a non root
auth is better tried first and then the root auth then the user has to pass in the
auths in the order as ``--auth <nonroot_1> <nonroot_2> <root_1> <root_2>`` etc.

^^^^^^^
OUTPUT
^^^^^^^
The important part about a scan is, obviously, the results report. By default,
this contains a large amount of information about the operating system, hardware, and platform.

- ``cpu.count`` - number of processors
- ``cpu.cpu_family`` - cpu family
- ``cpu.model_name`` - cpu model name
- ``cpu.vendor_id`` - cpu vendor name
- ``dmi.bios-vendor`` - bios vendor name
- ``error`` - any errors that are found
- ``etc-release.etc-release`` - contents of /etc/release (or equivalent)
- ``instnum.instnum`` installation number
- ``redhat-release.name`` - name of package that provides 'redhat-release'
- ``redhat-release.release`` - release of package that provides 'redhat-release'
- ``redhat-release.version`` - version of package that provides 'redhat-release'
- ``systemid.system_id`` - Red Hat Network System ID
- ``systemid.username`` - Red Hat Network username
- ``virt.virt`` - host, guest, or baremetal
- ``virt.type`` - type of virtual system
- ``uname.all`` - ``uname -a`` (all)
- ``uname.hardware_platform`` - ``uname -i`` (hardware_platform)
- ``uname.hostname`` - ``uname -n`` (hostname)
- ``uname.kernel`` - ``uname -r`` (kernel)
- ``uname.os`` - ``uname -s`` (os)
- ``uname.processor`` - ``uname -p`` (processor)

The output can then be configured to contain any combination of these fields by using the
``--facts`` argument. The following is the format rho understands for all the facts. Some or all
of these facts can be requested by either as a CLI list i.e. ``--facts <fact_1> <fact_2>`` etc
or by passing in a file with a new fact on every line in the format as follows. A value
of 'default' will get all the information listed above.

- **Username_uname.x** - for facts of the form ``uname.x``
- **VirtWhat_virt.x** - for facts of the form ``virt.x``
- **SysId_systemid.x** - for facts of the form ``systemid.x``
- **RedhatRelease_redhat-release.x** - for facts of the form ``redhat-release.x``
- **Instnum_instnum.x** - for facts of the form ``instnum.x``
- **EtcRelease_etc-release.x** - for facts of the form ``etc-release.x``
- **Dmi_dmi.x** - for facts of the form ``dmi.x``
- **Cpu_cpu.x** - for facts of the form ``cpu.x``

As hinted at previously, the auths that have been used in a particular scan are
the first valid auths in the list passed in order to the profile. All the valid
auths are of course listed in the host auth mapping file for the profile for that
scan identified by the time stamp.

^^^^^^^^^^^^^^^^^
Example rho Scan
^^^^^^^^^^^^^^^^^

Following is the results of an example rho scan. This is the example of the
profile called 'big_test' and it's host auth mapping
after the original reset. This is for the scan performed on Wed Aug 10 23:33:17
2016. Below you will find the example contents for:

- Host Auth Mapping
- Inventory
- Scan Profile
- Scan Auths
- Output

Example Host Auth Mapping
""""""""""""""""""""""""""

::

Wed Aug 10 23:33:17 2016
-------------------------------
192.168.124.153
----------------------
seven, root, ********, empty
eight, t_4, ********, empty


192.168.124.162
----------------------
two, t_2, ********, empty


192.168.124.174
----------------------
one, root, ********, empty
five, root, ********, empty
seven, root, ********, empty


192.168.124.15
----------------------
five, root, ********, empty
seven, root, ********, empty


192.168.121.007
----------------------
six, vagrant, ********, empty



Example Inventory
""""""""""""""""""

::

[alpha]
192.168.124.153 ansible_ssh_host=192.168.124.153
192.168.124.162 ansible_ssh_host=192.168.124.162
192.168.124.174 ansible_ssh_host=192.168.124.174
192.168.124.15 ansible_ssh_host=192.168.124.15
192.168.121.007 ansible_ssh_host=192.168.121.007

[five]
192.168.124.15 ansible_ssh_host=192.168.124.15 ansible_ssh_user=root ansible_ssh_pass=thirdpass ansible_ssh_private_key_file=empty


[six]
192.168.121.007 ansible_ssh_host=192.168.121.007 ansible_ssh_user=vagrant ansible_ssh_private_key_file=empty


[one]
192.168.124.174 ansible_ssh_host=192.168.124.174 ansible_ssh_user=root ansible_ssh_pass=firstpass ansible_ssh_private_key_file=empty


[two]
192.168.124.162 ansible_ssh_host=192.168.124.162 ansible_ssh_user=t_2 ansible_ssh_pass=secondpass1 ansible_ssh_private_key_file=empty


[seven]
192.168.124.153 ansible_ssh_host=192.168.124.153 ansible_ssh_user=root ansible_ssh_pass=fourthpass ansible_ssh_private_key_file=empty


Example Scan Profile
"""""""""""""""""""""

``big_test, 192.168.124.[1:40],192.168.121.007,192.168.121.140,192.168.124.153,192.168.124.[150:200], test_first,test_second,test_third,one,two,three,four,five,six,seven,eight``

Example Scan Auths
"""""""""""""""""""""

::

c54de740-6e03-436f-ab46-901a3a07c271, test_first, root, ********, /home/kbattula/.ssh/id_rsa
ecdda349-f7f3-432f-ac45-84aff1182f98, test_second, root, ********, /home/kbattula/.ssh/id_rsa
e2b70d19-6c96-426b-962a-c773c0eb9125, test_third, root, ********, /home/kbattula/.ssh/id_rsa
d2aa29b5-4f90-4da6-adfc-1163d7007568, one, root, ********, empty
de7ae67b-8880-4b3a-ab3d-365d58da0d69, two, t_2, ********, empty
55bc67f3-fc64-427c-8b2f-7aa7ceccf59b, three, blippy, ********, empty
af05cdce-08f7-4e7f-b375-981ad1935c2e, four, foobar, ********, empty
dc759edd-e43f-4a62-9459-eda6bc0efff8, five, root, ********, empty
dc72b6e1-f486-4b15-8e25-8c3b2ab395b8, six, vagrant, ********, empty
f37ce000-dc2a-4a3d-9988-e21caa8cec2b, seven, root, ********, empty
b11e014b-da64-4c0d-a45d-c81d12419882, eight, t_4, ********, empty

*Note: The first column is the unique id that rho assigns to every auth.*

Auths Association
""""""""""""""""""
This is the order in which the profile was associated to auths:

``
test_first test_second test_third one two three four five six seven eight
``

Facts
"""""""
The facts collected were:

- Username_uname.hostname
- Username_uname.os
- Date_date.date
- Cpu_cpu.bogomips
- Cpu_cpu.vendor_id
- RedhatRelease_redhat-release.name
- RedhatPackages_redhat-packages.num_installed_packages

Example Output
""""""""""""""""

::

cpu.bogomips,cpu.vendor_id,date.date,redhat-packages.num_installed_packages,redhat-release.name,uname.hostname,uname.os
5587.07,GenuineIntel,Thu Aug 11 14:55:46 EDT 2016,324,redhat-release-server,localhost.localdomain,Linux
5587.07,GenuineIntel,Thu Aug 11 14:55:46 EDT 2016,328,redhat-release-server,localhost.localdomain,Linux
5587.07,GenuineIntel,Thu Aug 11 14:55:46 EDT 2016,324,redhat-release-server,localhost.localdomain,Linux
5587.07,GenuineIntel,Thu Aug 11 14:55:46 EDT 2016,324,redhat-release-server,localhost.localdomain,Linux
5587.07,GenuineIntel,Thu Aug 11 14:55:46 EDT 2016,379,centos-release,rho-dev.example.com,Linux

For expanded information on Auth entries, profiles, scanning, and output read
the `syntax and usage document <doc/command_syntax_usage.rst>`_.

-------------
KNOWN ISSUES
Known Issues
-------------
To report bugs for rho, select the Fedora product and rho component in the Red
Hat bug tracking system, http://bugzilla.redhat.com.

version 2.0
To report bugs for rho `open issues <https://github.com/quipucords/rho/issues>`_
against this repository in Github.

----------------
VERSION HISTORY
Changes
----------------
version 2.0
* Made rho rely on Ansible for all of it's scanning needs.

version 0.2
* Added ability to detect and correctly categorize virtual hosts and guests.

version 0.1 (Initial release)
* Runs scans for RHEL systems, upstream (Fedora) systems, downstream (CentOS) systems, and other flavors of Linux and Unix.
* Introduces auth and profile configuration for setting up rho.
* Scans user-defined IP address ranges and hostnames for an entire network or subnet.
* Allows existing JSON configuration files to be loaded for configuration.
* Outputs results to CSV file reports.
* Allows the report format to be customized.
Track & find changes to the tool in `CHANGES <CHANGES.rst>`_.

--------
CONTACT
Authors
--------
rho was written by Adrian Likins <alikins@redhat.com>, Devan Goodwin
<dgoodwin@redhat.com>, and Jesus M. Rodriguez <jesusr@redhat.com>.

rho 2.0 was written by Karthik Harihar Reddy Battula <karthikhhr@gmail.com>
Authorship and current maintainer information can be found in `AUTHORS <AUTHORS.rst>`_.

--------------------
COPYRIGHT & LICENSE
Copyright & License
--------------------
Copyright 2009-2017, Red Hat, Inc.

rho is released under the GNU Public License version 2.

(README v2.0, last updated June 21, 2017.)
rho is released under the `GNU Public License version 2 <LICENSE>`_.

0 comments on commit 618f46e

Please sign in to comment.