Quickstart¶
The following section provides the info regarding how to prepare and use
ralph-cli
. After reading it, you'll be able to perform a successful scan of
your iDRAC/iLO host, and save its result (i.e. discovered hardware components)
to Ralph.
Installation¶
You can download a pre-built, self-contained ralph-cli
executable from
here. If your OS/architecture is not listed there, you can either
request it from us by opening an issue on our GitHub profile, or build
it from the source code. In the latter case, please refer to
How to build ralph-cli? section.
Configuring ralph-cli¶
At the initial run (e.g. ralph-cli --help
), ralph-cli
creates ~/.ralph-cli
directory, where its config file (config.toml
) is stored (along with scripts
sub-directory - more on this later). Its contents should look like this:
RalphAPIURL = "change_me"
RalphAPIKey = "change_me"
ManagementUserName = "change_me"
ManagementUserPassword = "change_me"
Before doing anything real, you need to replace dummy defaults denoted by
"change_me
string. For the meaning of those settings, which are all required,
see here.
Running scan scripts¶
ralph-cli
scans given IP address by executing one of the
scripts located in the ~/.ralph-cli/scripts
directory (you
may think of them as "plugins"). By default, it comes with two scripts:
idrac.py
and ilo.py
, which are both written in Python. If you have
python3
, pip
and virtualenv
in your $PATH
, you can continue to the next
paragraph - otherwise consult your package manager's manuals how to install
Python and also check out pip
's and virtualenv
's docs here and
here.
Having everything ready, we can perform the actual scan. Let's say that you have
some Dell PowerEdge R620 server, with iDRAC exposed on management IP
11.22.33.44
. Let's suppose that this server is added to Ralph, but in the
"Network" tab it has only this management IP visible - and nothing else. But you
know that this server has four network cards, and you want this information to
be available in Ralph too. Of course, you can log in to said iDRAC and copy
relevant information manually, but this is rather cumbersome, error-prone and
time-consuming. ralph-cli
to the rescue! You can achieve the same thing by
issuing:
ralph-cli scan 11.22.33.44 --script=idrac.py --components=eth --dry-run
...which would produce output similar to this:
INFO: Running in dry-run mode, no changes will be saved in Ralph.
Ethernet{id: 1, base_object_id: 1, mac: a1:b2:c3:d4:e5:aa, model_name: Intel(R) Ethernet 10G 4P X520/I350 rNDC, speed: 10 Gbps, firmware_version: 1.2.3} created successfully.
Ethernet{id: 2, base_object_id: 1, mac: a1:b2:c3:d4:e5:bb, model_name: Intel(R) Ethernet 10G 4P X520/I350 rNDC, speed: 10 Gbps, firmware_version: 1.2.3} created successfully.
Ethernet{id: 3, base_object_id: 1, mac: a1:b2:c3:d4:e5:cc, model_name: Intel(R) Ethernet 10G 4P X520/I350 rNDC, speed: 10 Gbps, firmware_version: 1.2.3} created successfully.
Ethernet{id: 4, base_object_id: 1, mac: a1:b2:c3:d4:e5:dd, model_name: Intel(R) Ethernet 10G 4P X520/I350 rNDC, speed: 10 Gbps, firmware_version: 1.2.3} created successfully.
Notice that we are running ralph-cli
in "dry-run" mode, which is a good idea
when you need some sort of control over your data. After examining this output
and finding it OK, you can safely issue the same command without --dry-run
switch. After that, you can check that the data was actually sent to Ralph by
going back to aforementioned "Network" tab in Ralph.
You may be wondering what would happen if you'd issue the same command again. Well, try it and see by yourself! Unless you've replaced some network card, you should see this message:
No changes detected.
And it means that the state of your server stored in Ralph reflects its actual
state in regards to network cards visible to idrac.py
script.
You may want to perform similar detection for other components as well, e.g.:
ralph-cli scan 11.22.33.44 --script=idrac.py --components=eth,mem,proc
...will try to detect network cards, memory and processors. For a possible
arguments for --components
switch, see the output for ralph-cli scan --help
command. By default (i.e. when you don't specify anything with --components
switch), ralph-cli
will look for all components (--components=all
).
There are two additional switches for scan
command, which may be useful for
you: --with-bios-and-firmware
and --with-model
. Let's see them in action by
issuing this command:
ralph-cli scan 11.22.33.44 --script=idrac.py --with-bios-and-firmware --with-model
...and we should get the output similar to this:
DataCenterAsset{id: 1, firmware_version: 1.10.10.10, bios_version: 1.2.3} updated successfully.
DataCenterAsset{id: 1, remarks: >>> ralph-cli: detected model name: Dell PowerEdge R620 <<<} updated successfully.
In the above example, the former switch detects firmware and BIOS versions of your iDRAC server, and writes them to Ralph - they can be examined by looking at "Basic info" tab in Ralph's GUI.
The latter tries to detect the model name of your server, but appends it into
the "Remarks" field (see "Basic info" tab once again) into a specially formatted
string denoted by >>> <<<
marks. The rationale behind this is that we don't
want to pollute the actual "Model" field in "Basic info" tab, with values that
may be slightly different due to some arbitrary changes in formatting
(e.g. "Dell PowerEdge R620" and "PowerEdge R620" are essentially the same
models, but different strings), so we think it's better to leave it as a kind of
suggestion for the person, who maintains this data in Ralph.
Going further¶
This tutorial gave you the minimum info needed to start using ralph-cli
for
detecting components of a Dell server running iDRAC. But you can go further than
that. There's another script bundled with ralph-cli
named ilo.py
, which is
intended for use with HP servers equipped with iLO service processor (and gives
slightly less info than iDRAC). And since both idrac.py
and ilo.py
are
scripts, not some binary plugins, you can freely modify them in-place (e.g, to
make them suit your needs better). But the best thing is, that you can actually
write your own scripts, in any language you want, as long as they conform to
Scripts Contract and you have means for running them from
your host (e.g. access to interpreter, required libraries etc.).