~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~
   rho - FLOSS tool for discovering RHEL, Linux, and Unix Servers  
~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~

This is README is for rho version 0.2, released November 20, 2009. rho is a tool 
for scanning a network, logging into systems using SSH, and retrieving 
information about available Unix and Linux servers. 

This README contains information about installing rho, basic usage, known 
issues, and best practices. For more details information about the available 
command and command options with rho, see the manpage.


*~*~*~*~*~*~
INTRO TO RHO
~*~*~*~*~*~*
rho is an SSH-based network inventory tool. rho scans a user-defined range of 
machines and then reports basic information about the operating system and 
hardware about each server. rho simplifies some basic sysadmin tasks, like 
managing licensing renewals and new deployments.

rho only has to be installed on a single central server to scan all of the 
servers on a network or subnet. rho uses SSH, which is commonly available for 
server, on both the scanning server and the target machines. rho is an 
agentless discovery tool, so there is no need to install anything on any server 
but the one which will run the scans. 

The rho tool itself is set up through two configuration items: 

 * auth entries, which contain the username and password or SSH key to access 
   each server

 * profile entries, which contain IP address ranges, auth credentials to use, and the 
   SSH ports to try

There can be multiple auth entries in each profile, and multiple profiles 
loaded for each scan.

The rho tool configuration is created using rho itself. There are subcommands 
to create and edit auth and profile items in the configuration. For example:

    rho auth add --name server1auth --username rho-user --file 
    /etc/ssh/ssh_host_rsa_key

This creates a new auth item named server1auth, which uses the SSH user 
rho-user with a key stored in the key file.

(The different rho commands are covered more in the "Syntax" section.)

The configuration entries are stored in an AES-128 encrypted configuration 
file, $HOME/.rho.conf by default. The .rho.conf file is created by the rho tool 
the first time rho is run. The .rho.conf file is in simple JSON format with two 
configuration items, for the auth entries and profiles. The attributes for each 
item correspond to the options for creating a profile or auth item. (E.g., a 
profile item has parameters for name, auth, ports, and range.) For example:
{
    "auths": [
        {
            "name": "server1auth", 
            "password": "secret", 
            "type": "ssh", 
            "username": "rho-user"
        }
    ], 
    "profiles": [
        {
            "auths": [
                "server1auth"
            ], 
            "name": "colo-net", 
            "ports": [
                22
            ], 
            "range": [
                "192.168.123.1 - 192.168.123.200"
            ]
        }
    ],
    "reports": [
        {
            "name": "basic",
            "output_filename": "basic.csv",
            "report_format": [
                "date.date",
                "uname.os"
            ]
        },
    ] 
    "version": 3
}

Running the scan is simple. Just point the rho tool to the profile (or 
profiles) to use and print the results to a CSV output file.

     rho scan --profile colo-net --output /tmp/myrho.csv

The output is simple CSV format. The exact data can be configured as part of 
the scan, but by default, it contains the following information in the output:
 
     ip,port,OS,kernel,processor,platform,release name,release version,release 
     number,system ID,username,instnum,release,CPU count,CPU vendor,CPU model,
     BIOS vendor,virtual guest/host,virtual type,auth type,auth username,auth 
     name,error

For example:

     192.168.123.116,22,Linux,i686,i386,redhat-release,5Client,5.3.0.3,ID-1000015943,
     jsmith,da3122afdb7edd23,Red Hat Enterprise Linux Client release 5.3 
     (Tikanga),2,GenuineIntel,Intel(R) Core(TM)2 Duo CPU,Award Software, Inc.,host,
     xen,ssh,rho-user,server1auth,none

The available output fields can be listed using 'rho scan --show-fields' and 
can be set using 'rho scan --report-format <fields>'.

As implied by the report output, rho differentiates between baremetal machines, 
virtual hosts, and virtual guests, and identifies several major virtual types 
(Xen, Qemu, KVM, and VMWare). It can be very important for inventorying machines 
and maintaining software licenses to separate virtual hosts from guests; rho 
returns that information with every scan, by default.


*~*~*~*~*~*~*~*~*~*~*~*~*~
REQUIREMENTS & ASSUMPTIONS
~*~*~*~*~*~*~*~*~*~*~*~*~*
Before installing rho, there are some guidelines about which machine it should 
be installed on:

 * rho is written to run on a RHEL or Fedora servers.

 * The machine that rho is installed on must be able to access the machines to 
   be scanned, so it must be on the network and the machines must be running.

 * The target machines must be running SSH.

 * The user account that rho uses to SSH into the machine must have adequate 
   permissions to run commands and read certain files. For example, it *cannot* 
   be a /sbin/nologin or /bin/false shell.

 * The user account rho uses for a machine should have a sh like shell

These python packages are required for the rho install machine to run rho:
 * python
 * python-paramiko
 * python-netaddr < 0.7
 * python-simplejson
 * python-crypto

The following python packages are required to build rho from source:
 * python-devel
 * python-setuptools


*~*~*~*~*~*~
INSTALLATION
~*~*~*~*~*~*
rho is available for download with the other Fedora EPEL packages at 
http://download.fedora.redhat.com/pub/epel/.

 1. First, make sure that the EPEL repo is enabled for the server:

     rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-2.noarch.rpm

 2. Then, install the rho packages:

     yum install rho


*~*~*~*~*~*~*~*~*~*~*~
COMMAND SYNTAX & USAGE
~*~*~*~*~*~*~*~*~*~*~*
The basic syntax is:

     rho command subcommand [options]

There are four rho commands:

 * auth, for managing auth entries

 * profile, for managing profile entries

 * report, for managing report entries

 * scan, for running scans

auth, profile, and report both have three subcommands:

 * add to create a new entry

 * edit to modify an existing entry

 * clear to remove any or all entries

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.


PASSWORDS
Every time the rho tool is run, the command prompts for the config file password. 
(The configuration file is encrypted and required a password to access it.) The 
first time rho is run, the prompt sets the password as it created the file. Every 
time after, it uses the password to decrypt the file.

     [me@example rho]$ bin/rho auth list
     Config Encryption Password:

When running a scan, the tool prompts for the config encryption password and 
for the SSH password, if required.

Although there is a significant security risk, it is possible to set environment 
variables for both of these passwords:

 * RHO_PASSWORD for the rho configuration file password

 * RHO_AUTH_PASSWORD for the SSH password


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 --file 
    /etc/ssh/ssh_host_rsa_key 


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

    rho profile edit --name profile1 --range "1.2.3.0 - 1.2.3.255" --auth 
    server1creds --auth server2creds --ports 22,318,415

REPORTS
Optionally, create a report to save report-formats for the scan. This should include a list of fields that constitute the report along with an optional output filename to always write this report to. The provided fields should be from the list reported by 'rho scan --show-fields'
   
    rho report add --name basic --fields date.date,uname.os

With no output filename specified the output file name defaults to NAME.csv where NAME is the provided name of the report.


SCANNING
The only argument required for a scan is a profile to use. In that case, 
the output is printed to stdout. 

    rho scan --profile myprofile

There is another option to use to specify an output file (which is in CSV format):

    rho scan --profile myprofile --output /home/jsmith/Desktop/output.csv 

It's also possible to run a scan without a profile, by passing the required 
information with the scan command.

    rho scan --range "1.2.3.0 - 1.2.3.255" --username rho-user --port 122 
    --output /home/jsmith/Desktop/output.csv 

One nifty alternative is using the output from an older scan to pass 
information for a new scan. There can be multiple SSH ports and auth 
credentials for each profile, which means that the scan has to iterate through 
multiple attempts to connect to a server. The output contains the SSH ports and 
IDs used to connect successfully to each server, by its IP address. Using the 
output of a previous scan makes the new scan run much faster, and if the old 
connection information fails, the tool can simply fall back on the options in 
the profile.

     rho scan --cache /home/me/cache.csv --profile profile1 --output 
     /home/me/newoutput.csv

It's also possible to run a scan for a saved report, by passing in the report
name created by 'rho report add'. 

     rho scan --profile myprofile --report basic

In the above example, rho will scan the machines specified in the myprofile
profile and output the values into basic.csv.

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. The 'rho scan --show-fields' command lists all of the 
available report fields (which may change with every version).

     auth.name:name of authentication class
     auth.type:type of ssh authentication used
     auth.username:username ssh
     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
     ip:ip address
     port:ssh port
     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 in 
the --report-format option or by defining a report using the report command. The only three required fields are 
ip,port,authname. For example:

     rho scan --profile myprofile --output /home/me/custom.csv --report-format 
     ip,port,authname,etc-release,cpucount,error


*~*~*~*~*~*~*~
BEST PRACTICES
~*~*~*~*~*~*~*

SSH USER IDENTITY
*****************
The rho tool does not need to connect to a target machine or be run as root. In 
fact, it's better if you run the tool as a regular user account.

If your organization already has tools for distributing SSH keys to users, then 
create a rho-specific user account and assign it its own SSH keys. This limits 
any potential damage or security problems. 

The rho user should have read permissions to things like install-num and the 
RHN systemid files, which are normally only readable by root.

INITIALIZING CONFIG
*******************
The rho tool can generate a config with a few default items to help get started (at this time this includes only pre-defined reports). 
To do this run:
    rho initconfig

Note: if a new config file is not specified with --config this will overwrite the default config: ~/.rho.conf

SCHEDULING SCANS
****************
It is possible to schedule rho scans as cron jobs, to run routinely. BE VERY 
CAREFUL about using cron to run scans. There are inherent security risks. The 
SSH passwords are stored on disk, so there are lots of ways a hacker could 
access the passwords and abuse the system.

If you want to schedule a rho scan, then the best practice is:  

 1. Write a small script like this:

#!/bin/sh
RHO_PASSWORD=password /usr/bin/rho scan --profile=myprofile

 2. Protect that script with the most secure Unix permissions that will work, 
    like 700 (for a single user).

 3. Run that script using cron.

USING MULTIPLE SSH CREDENTIALS
******************************
Do not associate too many authorizations or SSH ports with a single profile. 
Iterating through all the credentials and ports, with numerous expected 
failures, slows down the scanner substantially.

SSH LOGIN FAILURES
******************
Some networks may be configured to lock systems with a certain number of SSH 
login failures. Check the security measures in the organization and do some 
test runs to make sure that the current profile configuration won't lock any 
systems.


*~*~*~*~*~*~
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 0.1
 * Adding or editing a profile to use a non-existent auth entry returns an 
exception error and breaks the rho configuration.
 * Editing a non-existent profile returns an exception error.
 * Adding a malformed range to a profile causes a python trace.
 * 'rho scan --range' prompts for a decryption password, when it shouldn't be 
necessary


*~*~*~*~*~*~*~*
VERSION HISTORY
~*~*~*~*~*~*~*~
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.

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

COPYRIGHT & LICENSE
Copyright 2009, Red Hat, Inc.

rho is released under the GNU Public License version 2.

(README v1.0, last updated November 13, 2009.)