1rho(1) rho User Commands rho(1)
2
6 rho - Easily discover and manage systems on your network.
7
10 rho command subcommand [options]
11
14 rho is a network discovery tool to identify the number of systems run‐
15 ning on a network, their operating system, hardware, and release num‐
16 bers for almost any Linux or Unix flavor. Being able to identify the
17 systems running on the network is a vital component to managing
18 licenses and renewals. Ultimately, discovery is part of the larger
19 sysadmin task of managing inventories.
20 rho uses two configuration entries to manage the discovery process.
22 Profiles define the network or subnet that is being monitored. Creden‐
23 tials contains the usernames, passwords or, alternatively, the SSH keys
24 of the user as which discovery runs. There can be multiple network pro‐
25 files and authentication credentials, used in any combination.
26 rho is an agentless discovery tool, so there is no need to install any‐
28 thing on multiple systems. OS discovery for the entire network is cen‐
29 tralized to a single machine.
30 This man page covers the commands, subcommands and options for rho with
32 basic usage information. For more detailed information and examples,
33 including best practices, see the rho README.
34
37 rho performs three major tasks:
38 1. Creating authentication profiles. This has the basic command:
40 rho auth add ...
42 2. Creating network profiles. This has the basic command:
44 rho profiles add --name X --range X --auth X
46 3. Running discovery, such as:
48 rho scan --profile X
50 The following sections cover these commands in more detail.
52 The primary purpose of rho is to scan a network. This can be done using
54 simply 'rho scan' and passing all of the required network parameters
55 and authentication credentials with every discovery pass. Using network
56 and authentication profiles, however, simplifies discovery.
57 By default, the authentication credentials and profiles created using
59 rho are stored in an encrypted file, $HOME/.rho.conf. The file is
60 encrypted with AES-128 encryption and is decrypted when the 'rho' com‐
61 mand is run, using a passphrase to access the file.
62 AUTHENTICATION
66 The first part to configuring rho is setting up authentication creden‐
67 tials. rho uses SSH to connect to the servers on the network, and the
68 credentials is uses are configured in auth entries. Some kind of auth
69 entry has to be passed when the scan is run, either by referencing the
70 auth entry in a profile or by passing the credentials with the scan
71 command.
72 There can be multiple auth credentials contained in a single profile.
74 Creating and Editing auth Entries
76 rho uses SSH credentials to access the servers to get their OS informa‐
78 tion during discovery. These credentials can be either a username-pass‐
79 word or username-key pair. Each set of credentials is stored in a sepa‐
80 rate entry.
81 rho auth add --name name --username name [--file key_file ] [--password
83 password ]
84 --name name
86 This required argument sets the name of the new authentication
87 credentials entry. This should be descriptive, such as identify‐
88 ing the user or server it relates to. For example,
89 "server1-rhouser". It should never contain the actual password,
90 as this name may be logged or printed during rho execution.
91 --username name
93 This required argument contains the username of the SSH identity
94 will use to bind to the server. This parameter prompts for the
95 password for the user identity.
96 --file key_file
98 Optionally, this contains the path and file name of the file
99 containing the SSH key issued for the --username identity.
100 The information given in an auth entry -- such as a password, SSH keys,
103 or even the username -- may change. For example, network security may
104 require passwords to be updated every few months. The auth entry can be
105 edited to change the SSH credential information. The parameters for
106 'rho auth edit' are the same as those for 'rho auth add'.
107 rho auth edit --name name --username name [--file key_file ] [--pass‐
109 word password ]
110 Listing and Showing auth Entries
113 The 'rho auth list' command returns the details for every auth entry
115 configured for rho. This output includes the name, username, password,
116 and auth type for each entry. Optionally, it can include the key fin‐
117 gerprint.
118 rho auth list [--showkeys]
120 --showkeys
122 This displays the key fingerprint of the SSH key given in the
123 --file parameter when the authentication method was added. By
124 default, key information is not returned with 'rho auth list'.
125 The 'rho auth show' command is the same as the 'rho auth list' command,
128 except that it only returns details for a single specified auth entry.
129 rho auth show --name name [--showkeys]
131 --name name
133 This required argument gives the authentication credentials
134 entry to display.
135 --showkeys
137 This displays the key fingerprint of the SSH key given in the
138 --file parameter when the authentication method was added. By
139 default, key information is not returned with 'rho auth show'.
140 Deleting auth Entries
143 It can be necessary to remove authentication credentials as the network
145 infrastructure changes. This is done using the 'clear' subcommand.
146 IMPORTANT: Remove the auth setting from any profile which uses it
148 before removing the auth entry. Otherwise, any attempt to use the pro‐
149 file attempts to use the non-existent auth entry, which causes the
150 'rho' command to fail.
151 rho auth clear --name name | --all
154 --name name
156 This argument gives the authentication credentials entry to
157 delete.
158 --all This deletes all stored authentication credentials.
160 PROFILES
164 Profiles define a collection of network information, including IP
165 addresses, SSH ports, and SSH credentials. A discovery scan can refer‐
166 ence a profile so that running the scan is automatic and repeatable,
167 without having to re-enter network information every time.
168 Creating and Editing Profiles
170 A profile is essentially a concise collection of the information that
172 rho needs to connect to a network or system. This means it contains 1)
173 servers to connect to, 2) SSH ports to use, and 3) authentication cre‐
174 dentials to use. Each of these parameters allowed multiple entries, so
175 the same profile can access a patchwork of servers and subnets, as
176 needed.
177 rho profile add --name name [--range ip_address ] [--ports ssh_ports ]
179 [--auth auth_profile ]
180 --name name
182 This required argument sets the name of the new profile. This
183 name is used to identify the profile in later operations. Use a
184 descriptive name, such as "ColoSubnet".
185 --range ip_address
187 This sets the IP address, hostname, or IP address range to use
188 when running discovery. There are several different formats that
189 are allowed for the ip_address value.
190 1. A specific hostname:
192 --range server.example.com
194 2. A specific IP address, in both standard and CIDR format:
196 --range 1.2.3.4
198 --range 1.2.3.4/24
200 3. Wildcards in IP addresses:
202 --range 1.2.3.*
204 4. An IP address range, in the form "IP - IP":
206 --range "1.2.3.4 - 1.2.3.255"
208 The --range setting also allows multiple entries, so non-con‐
210 tiguous ranges can be specified in the same profile. For exam‐
211 ple:
212 --range "1.2.3.4 - 1.2.3.100" --range "1.2.3.211" --range
214 "server.example.com"
215 These all show up in the profile entry as:
217 --ports ssh_ports
219 This gives a comma-separated list of allowed SSH ports to access
220 on the hosts. For example:
221 --ports 22,300,500
223 The default port is 22. This parameter is optional.
225 --auth auth_profile
227 This contains the name of the authentication profile (created
228 with 'rho auth add') to use to authentication to the servers
229 being scanned. To add more than one auth profile to the network
230 profile, run the --auth argument multiple times. For example:
231 --auth first_auth --auth second_auth
233 IMPORTANT: This auth profile must exist before attempting to add
235 the authentication profile to the network profile.
236 The only required parameter when a profile is created is its name. Some
239 parameters can be missing when it's first added and can be added later
240 or they can be modified using the 'rho profile edit' command.
241 rho profile edit --name name [--range ip_address ] [--ports ssh_ports ]
243 [--auth auth_profile ]
244 Although all three 'rho profile' parameters accept more than one set‐
246 ting, the 'rho profile edit' command is not additive. If a new argument
247 is passed, it overwrites whatever was originally in the profile, it
248 doesn't add a new attribute, even if the parameter is multi-valued. To
249 add or keep multiple values with the edit command, list all parameters
250 in the edit. For example, if a profile was created with an auth value
251 of "server1creds" and the same profile will be used to scan with both
252 server1creds and server2creds, edit as follows:
253 rho profile edit --name myprofile --auth server1creds --auth
255 server2creds
256 You can use 'rho profile show --name myprofile' to make sure that the
258 profile was properly edited.
259 Listing and Showing Profiles
262 The 'list' commands lists the details for all configured profiles. The
264 output includes the IP ranges, auth credentials, and ports for the pro‐
265 file.
266 rho profile list
268 The 'rho profile show' command is the same as the 'rho profile list'
270 command, except that it returns details for a single specific profile.
271 This is a handy command to verify edits to a profile.
272 rho profile show --name profile
274 Deleting Profiles
277 Any or all profiles can be deleted using the 'clear' subcommand.
279 rho profile clear --name name | --all
281 SCANNING
285 The 'scan' command is the one that actually runs discovery on the net‐
286 work. This command scans all of the servers within the range, and then
287 prints the information to a CSV file.
288 There are two ways to run a scan. The simplest way is to specify the
290 profile to use:
291 rho scan [--profile profile_name ] [--output file ] [--allow-agent
293 true|false] [--cache file ] [--show-fields true|false] [--report-format
294 options ]
295 --profile profile_name
297 Gives the name of the profile to use to run the scan.
298 --output file
300 Prints the output to a comma-separated values (CSV) file instead
301 of stdout.
302 --allow-agent true|false
304 Tells 'rho' to use the keys stored in the local ssh-agent. By
305 default, this is false, so that the credentials are used from
306 the profile.
307 --cache file
309 Loads the output file of a previous scan. This loads the suc‐
310 cessful connection information (SSH port, auth username, and
311 auth credentials) used to access each IP address in the range.
312 This allows the scan to progress more quickly because it doesn't
313 have to iterate through all of the auth credentials for the pro‐
314 file for each server. If credentials for the server aren't
315 available or the previous credentials fail, then the scan falls
316 back to the auth settings in the profile.
317 --show-fields
319 Prints the available values that can be returned in the scan
320 output.
321 auth.name:name of authentication class
322 auth.type:type of ssh authentication used
323 auth.username:username ssh
324 cpu.count:number of processors
325 cpu.cpu_family:cpu family
326 cpu.model_name:cpu model name
327 cpu.vendor_id:cpu vendor name
328 dmi.bios-vendor:bios vendor name
329 error:any errors that are found
330 etc-release.etc-release:contents of /etc/release (or equivalent)
331 instnum.instnum:installation number
332 ip:ip address
333 port:ssh port
334 redhat-release.name:name of package that provides 'redhat-release'
335 redhat-release.release:release of package that provides 'redhat-release'
336 redhat-release.version:version of package that provides 'redhat-release'
337 systemid.system_id:Red Hat Network system id
338 systemid.username:Red Hat Network username
339 virt.virt:host, guest, or baremetal
340 virt.type:type of virtual system
341 uname.all:uname -a (all)
342 uname.hardware_platform:uname -i (hardware_platform)
343 uname.hostname:uname -n (hostname)
344 uname.kernel:uname -r (kernel)
345 uname.os:uname -s (os)
346 uname.processor:uname -p (processor)
347 --report-format options
349 Sets the values to include in the CSV output, in order. The pos‐
350 sible values are displayed with 'rho scan --show-fields'. Three
351 fields are required, 'ip,port,authname'.
352 Alternatively, the scan can be run without using any profile and just
355 passing all of the profile (or profile and auth) parameters with the
356 scan command:
357 rho scan [--range ip_address ] [--ports ssh_ports ] [--username name ]
359 [--auth auth_credentials ] [--output file ] [--allow-agent true|false]
360 [--cache file ] [--show-fields true|false] [--report-format options ]
361 VIEWING AND LOADING CONFIGURATION
365 The configuration for using 'rho' is stored in the .rho.conf file. This
366 file is automatically created and AES-128 encrypted when the first auth
367 entry or profile is created.
368 The .rho.conf file is basically a simple JSON file, so it is possible
370 to create a .conf file and then load the configuration all at once,
371 rather than using 'rho' to create the file. This file has to be a
372 plaintext, raw JSON file; when it is loaded, 'rho' will properly read
373 and encrypt it. This is done using the 'importconfig' command.
374 rho importconfig --from-file /path/to/file.conf
376 --from-file /path/to/file
378 Identifies the JSON configuration file to use. This argument is
379 required.
380 The complete configuration of the .rho.conf file can be viewed using
383 the 'rho dumpconfig' command. This displays both profiles and auths,
384 printed to stdout.
385 rho dumpconfig
387 OPTIONS FOR ALL COMMANDS
391 A handful of options are allowed with every command for rho.
392 rho ... [--config file ] [--log file ] [--log-level debug|info|warn‐
394 ing|error|critical] [--help]
395 --config file
397 By default, rho reads its configuration from $HOME/.rho.conf.
398 rho.conf is an AES-128 encrypted JSON file created by the rho
399 utility. This option points the tool to a different location.
400 The file does not need to exist first; the rho tool automati‐
401 cally creates and encrypts the specified config file the first
402 time it is referenced.
403 --log file
405 This writes the output from the command to a specific log file.
406 Otherwise, the logging information is written to stout.
407 --log-level level
409 This sets the logging level for the command. This moves progres‐
410 sively from the logging only critical failures (critical) to
411 logging everything about the command (debug). If this is not
412 set, the default is critical.
413 --help This prints the help for the rho command or subcommand.
415 ENVIRONMENT VARIABLES
419 There is currently two environment variables that can be set when using
420 rho to avoid password prompts.
421 IMPORTANT: Storing passwords in environment variables is especially
423 dangerous. Be very cautious about using these environment variables in
424 a production environment.
425 RHO_PASSPHRASE
427 The AES-128 encrypted $HOME/.rho.conf file must be accessed
428 every time rho is run. This file stores all of the profile
429 information. A passphrase must be entered to access this file;
430 the phrase is set the first time the file is created. Normally,
431 the command prompts for this passphrase and it must be entered
432 manually. The RHO_PASSPHRASE environment variable sets the pass‐
433 word.
434 RHO_AUTH_PASSWORD
436 The SSH credentials prompt for the authentication password when‐
437 ever the scan is run or the credentials are updated. This SSH
438 password can be set using the RHO_AUTH_PASSWORD environment
439 variable.
440
444 When the scan runs successfully, it outputs a CSV file that can be used
445 to inventory the servers on the network. The output file has the fol‐
446 lowing format:
447 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
448 For example:
450 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
451 ip
453 The IP address of the server machine picked up in the scan.
455 port
457 The SSH port number used to access the server.
459 kernel
461 The kernel for the server.
463 processor
465 The processor type for the server.
467 platform
469 The hardware platform for the server.
471 release name
473 The type of release. For Red Hat Linux, this is redhat-release.
475 For up- and downstream releases, this could be centos-release or
476 fedora-release. The formats for other Unix and Linux distribu‐
477 tions depends on the distribution.
478 release version
480 The major version of the release.
482 release number
484 The release number for the operating system release.
486 system ID
488 The identifier for the server, as in /etc/sysconfig/rhn/sys‐
490 temid. For Red Hat releases only.
491 username
493 The username used by the server to bind to Red Hat Network for
495 updates, as in /etc/sysconfig/rhn/systemid. For Red Hat
496 releases only.
497 instnum
499 The instance number for the server for entitlement management,
501 as in /etc/sysconfig/rhn/systemid. For Red Hat releases only.
502 release
504 The full release name, as in the /etc/*release file. Mainly for
506 operating systems other than Red Hat Linux.
507 CPU count
509 The number of CPUs on the machine.
511 CPU vendor
513 The name of the CPU manufacturer, from the /proc/cpuinfo file.
515 BIOS vendor
517 The name of the BIOS vendor, from running dmidecode -s bios-ven‐
519 dor.
520 virtual guest/host
522 The type of virtual machine. This can be baremetal (no virtual
524 machines), host, or guest.
525 virtual type
527 The type of virtual service. This can be xen, qemu, kvm, or
529 vmware.
530 auth type
532 The SSH authentication method used by rho. This can be ssh (sim‐
534 ple password) or ssh_key.
535 auth username
537 The username used by rho to bind to the system.
539 auth name
541 The name of the auth profile used by rho for the scan.
543 error
545 Any errors returned by the SSH process. This is normally "login
547 failed" or "unable to connect".
548
551 Adding new auth credentials
552 rho auth add --name new-creds --username rho-user --file
553 /etc/ssh/ssh_host_rsa_key
554 Creating a new profile
556 rho profile add --name new-profile
557 Editing a profile
559 rho profile edit --name new-profile --range "1.2.3.0 -
560 1.2.3.255" --auth new-creds --auth other-creds --ports
561 22,318,415
562 Running a scan without a profile
564 rho scan --range "1.2.3.0 - 1.2.3.255" --username rho-user
565 --port 122 --output /home/jsmith/Desktop/output.csv
566 Running a scan with a profile
568 rho scan --profile new-profile --output /home/jsmith/Desk‐
569 top/output.csv
570
573 The credentials used to access servers are stored with the profile con‐
574 figuration in an AES-128 encrypted configuration file (rho.conf). A
575 passphrase is used to access this file. The passphrase and decrypted
576 file contents are in the system memory, and could theoretically be
577 written to disk if they were to be swapped out.
578 While the password-related environment variables can be set to run
580 'rho' without prompts (such as scheduling a cron job), setting these
581 variables is extremely risky. Be exceptionally cautious about using
582 these variables.
583
586 The rho tool was originally written by Adrian Likins <alikins-at-red‐
587 hat.com>, Devan Goodwin <dgoodwin-at-redhat.com>, and Jesus M.
588 Rodriguez <jesusr-at-redhat.com> of Red Hat, Inc.
589
592 (c)2009 Red Hat, Inc. Licensed under the GNU Public License version 2.
593version 0.1 October 28, 2009 rho(1)