Linux Certif

Toute la documentation sur la certification Linux LPI

rho

NAME

rho - Easily discover and manage systems on your network.

SYNOPSIS

rho command subcommand [options]

DESCRIPTION

rho is a network discovery tool to identify the number of systems running on a network, their operating system, hardware, and release numbers for almost any Linux or Unix flavor. Being able to identify the systems running on the network is a vital component to managing licenses and renewals. Ultimately, discovery is part of the larger sysadmin task of managing inventories.

rho uses two configuration entries to manage the discovery process. Profiles define the network or subnet that is being monitored. Credentials contains the usernames, passwords or, alternatively, the SSH keys of the user as which discovery runs. There can be multiple network profiles and authentication credentials, used in any combination.

rho is an agentless discovery tool, so there is no need to install anything on multiple systems. OS discovery for the entire network is centralized to a single machine.

This man page covers the commands, subcommands and options for rho with basic usage information. For more detailed information and examples, including best practices, see the rho README.

USAGE

rho performs three major tasks:

1. Creating authentication profiles. This has the basic command:

rho auth add ...

2. Creating network profiles. This has the basic command:

rho profiles add --name X --range X --auth X

3. Running discovery, such as:

rho scan --profile X

The following sections cover these commands in more detail.

The primary purpose of rho is to scan a network. This can be done using simply 'rho scan' and passing all of the required network parameters and authentication credentials with every discovery pass. Using network and authentication profiles, however, simplifies discovery.

By default, the authentication credentials and profiles created using rho are stored in an encrypted file, $HOME/.rho.conf. The file is encrypted with AES-128 encryption and is decrypted when the 'rho' command is run, using a passphrase to access the file.

AUTHENTICATION

The first part to configuring rho is setting up authentication credentials. rho uses SSH to connect to the servers on the network, and the credentials is uses are configured in auth entries. Some kind of auth entry has to be passed when the scan is run, either by referencing the auth entry in a profile or by passing the credentials with the scan command.

There can be multiple auth credentials contained in a single profile.

Creating and Editing auth Entries

rho uses SSH credentials to access the servers to get their OS information during discovery. These credentials can be either a username-password or username-key pair. Each set of credentials is stored in a separate entry.

rho auth add --name name --username name [--file key_file ] [--password password ]

--name name

This required argument sets the name of the new authentication credentials entry. This should be descriptive, such as identifying the user or server it relates to. For example, "server1-rhouser". It should never contain the actual password, as this name may be logged or printed during rho execution.

--username name

This required argument contains the username of the SSH identity will use to bind to the server. This parameter prompts for the password for the user identity.

--file key_file

Optionally, this contains the path and file name of the file containing the SSH key issued for the --username identity.

The information given in an auth entry -- such as a password, SSH keys, or even the username -- may change. For example, network security may require passwords to be updated every few months. The auth entry can be edited to change the SSH credential information. The parameters for 'rho auth edit' are the same as those for 'rho auth add'.

rho auth edit --name name --username name [--file key_file ] [--password password ]

Listing and Showing auth Entries

The 'rho auth list' command returns the details for every auth entry configured for rho. This output includes the name, username, password, and auth type for each entry. Optionally, it can include the key fingerprint.

rho auth list [--showkeys]

--showkeys

This displays the key fingerprint of the SSH key given in the --file parameter when the authentication method was added. By default, key information is not returned with 'rho auth list'.

The 'rho auth show' command is the same as the 'rho auth list' command, except that it only returns details for a single specified auth entry.

rho auth show --name name [--showkeys]

--name name

This required argument gives the authentication credentials entry to display.

--showkeys

This displays the key fingerprint of the SSH key given in the --file parameter when the authentication method was added. By default, key information is not returned with 'rho auth show'.

Deleting auth Entries

It can be necessary to remove authentication credentials as the network infrastructure changes. This is done using the 'clear' subcommand.

IMPORTANT: Remove the auth setting from any profile which uses it before removing the auth entry. Otherwise, any attempt to use the profile attempts to use the non-existent auth entry, which causes the 'rho' command to fail.

rho auth clear --name name | --all

--name name

This argument gives the authentication credentials entry to delete.

--all

This deletes all stored authentication credentials.

PROFILES

Profiles define a collection of network information, including IP addresses, SSH ports, and SSH credentials. A discovery scan can reference a profile so that running the scan is automatic and repeatable, without having to re-enter network information every time.

Creating and Editing Profiles

A profile is essentially a concise collection of the information that rho needs to connect to a network or system. This means it contains 1) servers to connect to, 2) SSH ports to use, and 3) authentication credentials to use. Each of these parameters allowed multiple entries, so the same profile can access a patchwork of servers and subnets, as needed.

rho profile add --name name [--range ip_address ] [--ports ssh_ports ] [--auth auth_profile ]

--name name

This required argument sets the name of the new profile. This name is used to identify the profile in later operations. Use a descriptive name, such as "ColoSubnet".

--range ip_address

This sets the IP address, hostname, or IP address range to use when running discovery. There are several different formats that are allowed for the ip_address value.

1. A specific hostname:

--range server.example.com

2. A specific IP address, in both standard and CIDR format:

--range 1.2.3.4

--range 1.2.3.4/24

3. Wildcards in IP addresses:

--range 1.2.3.*

4. An IP address range, in the form "IP - IP":

--range "1.2.3.4 - 1.2.3.255"

The --range setting also allows multiple entries, so non-contiguous ranges can be specified in the same profile. For example:

--range "1.2.3.4 - 1.2.3.100" --range "1.2.3.211" --range "server.example.com"

These all show up in the profile entry as:

--ports ssh_ports

This gives a comma-separated list of allowed SSH ports to access on the hosts. For example:

--ports 22,300,500

The default port is 22. This parameter is optional.

--auth auth_profile

This contains the name of the authentication profile (created with 'rho auth add') to use to authentication to the servers being scanned. To add more than one auth profile to the network profile, run the --auth argument multiple times. For example:

--auth first_auth --auth second_auth

IMPORTANT: This auth profile must exist before attempting to add the authentication profile to the network profile.

The only required parameter when a profile is created is its name. Some parameters can be missing when it's first added and can be added later or they can be modified using the 'rho profile edit' command.

rho profile edit --name name [--range ip_address ] [--ports ssh_ports ] [--auth auth_profile ]

Although all three 'rho profile' parameters accept more than one setting, the 'rho profile edit' command is not additive. If a new argument is passed, it overwrites whatever was originally in the profile, it doesn't add a new attribute, even if the parameter is multi-valued. To add or keep multiple values with the edit command, list all parameters in the edit. For example, if a profile was created with an auth value of "server1creds" and the same profile will be used to scan with both server1creds and server2creds, edit as follows:

rho profile edit --name myprofile --auth server1creds --auth server2creds

You can use 'rho profile show --name myprofile' to make sure that the profile was properly edited.

Listing and Showing Profiles

The 'list' commands lists the details for all configured profiles. The output includes the IP ranges, auth credentials, and ports for the profile.

rho profile list

The 'rho profile show' command is the same as the 'rho profile list' command, except that it returns details for a single specific profile. This is a handy command to verify edits to a profile.

rho profile show --name profile

Deleting Profiles

Any or all profiles can be deleted using the 'clear' subcommand.

rho profile clear --name name | --all

SCANNING

The 'scan' command is the one that actually runs discovery on the network. This command scans all of the servers within the range, and then prints the information to a CSV file.

There are two ways to run a scan. The simplest way is to specify the profile to use:

rho scan [--profile profile_name ] [--output file ] [--allow-agent true|false] [--cache file ] [--show-fields true|false] [--report-format options ]

--profile profile_name

Gives the name of the profile to use to run the scan.

--output file

Prints the output to a comma-separated values (CSV) file instead of stdout.

--allow-agent true|false

Tells 'rho' to use the keys stored in the local ssh-agent. By default, this is false, so that the credentials are used from the profile.

--cache file

Loads the output file of a previous scan. This loads the successful connection information (SSH port, auth username, and auth credentials) used to access each IP address in the range. This allows the scan to progress more quickly because it doesn't have to iterate through all of the auth credentials for the profile for each server. If credentials for the server aren't available or the previous credentials fail, then the scan falls back to the auth settings in the profile.

--show-fields

Prints the available values that can be returned in the scan output.

 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)
 

--report-format options

Sets the values to include in the CSV output, in order. The possible values are displayed with 'rho scan --show-fields'. Three fields are required, 'ip,port,authname'.

Alternatively, the scan can be run without using any profile and just passing all of the profile (or profile and auth) parameters with the scan command:

rho scan [--range ip_address ] [--ports ssh_ports ] [--username name ] [--auth auth_credentials ] [--output file ] [--allow-agent true|false] [--cache file ] [--show-fields true|false] [--report-format options ]

VIEWING AND LOADING CONFIGURATION

The configuration for using 'rho' is stored in the .rho.conf file. This file is automatically created and AES-128 encrypted when the first auth entry or profile is created.

The .rho.conf file is basically a simple JSON file, so it is possible to create a .conf file and then load the configuration all at once, rather than using 'rho' to create the file. This file has to be a plaintext, raw JSON file; when it is loaded, 'rho' will properly read and encrypt it. This is done using the 'importconfig' command.

rho importconfig --from-file /path/to/file.conf

--from-file /path/to/file

Identifies the JSON configuration file to use. This argument is required.

The complete configuration of the .rho.conf file can be viewed using the 'rho dumpconfig' command. This displays both profiles and auths, printed to stdout.

rho dumpconfig

OPTIONS FOR ALL COMMANDS

A handful of options are allowed with every command for rho.

rho ... [--config file ] [--log file ] [--log-level debug|info|warning|error|critical] [--help]

--config file

By default, rho reads its configuration from $HOME/.rho.conf. rho.conf is an AES-128 encrypted JSON file created by the rho utility. This option points the tool to a different location. The file does not need to exist first; the rho tool automatically creates and encrypts the specified config file the first time it is referenced.

--log file

This writes the output from the command to a specific log file. Otherwise, the logging information is written to stout.

--log-level level

This sets the logging level for the command. This moves progressively from the logging only critical failures (critical) to logging everything about the command (debug). If this is not set, the default is critical.

--help

This prints the help for the rho command or subcommand.

ENVIRONMENT VARIABLES

There is currently two environment variables that can be set when using rho to avoid password prompts.

IMPORTANT: Storing passwords in environment variables is especially dangerous. Be very cautious about using these environment variables in a production environment.

RHO_PASSPHRASE

The AES-128 encrypted $HOME/.rho.conf file must be accessed every time rho is run. This file stores all of the profile information. A passphrase must be entered to access this file; the phrase is set the first time the file is created. Normally, the command prompts for this passphrase and it must be entered manually. The RHO_PASSPHRASE environment variable sets the password.

RHO_AUTH_PASSWORD

The SSH credentials prompt for the authentication password whenever the scan is run or the credentials are updated. This SSH password can be set using the RHO_AUTH_PASSWORD environment variable.

OUTPUT

When the scan runs successfully, it outputs a CSV file that can be used to inventory the servers on the network. The output file has the following format:

 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,host,xen,ssh,rho-user,server1auth,none
 

ip

The IP address of the server machine picked up in the scan.

port

The SSH port number used to access the server.

kernel

The kernel for the server.

processor

The processor type for the server.

platform

The hardware platform for the server.

release name

The type of release. For Red Hat Linux, this is redhat-release. For up- and downstream releases, this could be centos-release or fedora-release. The formats for other Unix and Linux distributions depends on the distribution.

release version

The major version of the release.

release number

The release number for the operating system release.

system ID

The identifier for the server, as in /etc/sysconfig/rhn/systemid. For Red Hat releases only.

username

The username used by the server to bind to Red Hat Network for updates, as in /etc/sysconfig/rhn/systemid. For Red Hat releases only.

instnum

The instance number for the server for entitlement management, as in /etc/sysconfig/rhn/systemid. For Red Hat releases only.

release

The full release name, as in the /etc/*release file. Mainly for operating systems other than Red Hat Linux.

CPU count

The number of CPUs on the machine.

CPU vendor

The name of the CPU manufacturer, from the /proc/cpuinfo file.

BIOS vendor

The name of the BIOS vendor, from running dmidecode -s bios-vendor.

virtual guest/host

The type of virtual machine. This can be baremetal (no virtual machines), host, or guest.

virtual type

The type of virtual service. This can be xen, qemu, kvm, or vmware.

auth type

The SSH authentication method used by rho. This can be ssh (simple password) or ssh_key.

auth username

The username used by rho to bind to the system.

auth name

The name of the auth profile used by rho for the scan.

error

Any errors returned by the SSH process. This is normally "login failed" or "unable to connect".

EXAMPLES

Adding new auth credentials

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

Creating a new profile

rho profile add --name new-profile

Editing a profile

rho profile edit --name new-profile --range "1.2.3.0 - 1.2.3.255" --auth new-creds --auth other-creds --ports 22,318,415

Running a scan without a profile

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

Running a scan with a profile

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

SECURITY CONSIDERATIONS

The credentials used to access servers are stored with the profile configuration in an AES-128 encrypted configuration file (rho.conf). A passphrase is used to access this file. The passphrase and decrypted file contents are in the system memory, and could theoretically be written to disk if they were to be swapped out.

While the password-related environment variables can be set to run 'rho' without prompts (such as scheduling a cron job), setting these variables is extremely risky. Be exceptionally cautious about using these variables.

AUTHORS

The rho tool was originally written by Adrian Likins <alikins-at-redhat.com>, Devan Goodwin <dgoodwin-at-redhat.com>, and Jesus M. Rodriguez <jesusr-at-redhat.com> of Red Hat, Inc.

COPYRIGHT

(c)2009 Red Hat, Inc. Licensed under the GNU Public License version 2.