~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~*~ 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.)