~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~
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"
]
}
],
"version": 1
}
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 three rho commands:
* auth, for managing auth entries
* profile, for managing profile entries
* scan, for running scans
auth and profile 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_PASSPHRASE 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
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
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. 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.
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.)