~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 '.

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/.

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
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:

Write a small script like this:

!/bin/sh

RHO_PASSWORD=password /usr/bin/rho scan --profile=myprofile

Protect that script with the most secure Unix permissions that will work, like 700 (for a single user).
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.

rho is released under the GNU Public License version 2.

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

candlepin / rho

readme

!/bin/sh