Comments on OpenLMI documentation overhaul

Russell Doty rdoty at redhat.com
Wed Oct 1 16:02:55 UTC 2014


First of all, I'm extremely impressed with the documentation overhaul! I
apologize for not responding sooner; as a feeble excuse I was on PTO
last week.

These comments cover LMIShell and LMI Metacommand. I will look at the
other sections later.

Notes on LMIShell

* http://docs.openlmi.org/en/latest/openlmi-tools/shell/classes.html

"Each class in LMIShell represents a class provided by a CIMOM" - I
think of the class as being implemented in a Provider and accessed
through the CIMOM. The CIMOM is basically an access method to get to
Providers.

Under Synchronous Methods should we mention that most methods we have
implemented are asynchronous, and that you can launch them and then do
other things while waiting for the method to finish? Perhaps add a
section on this before the Synchronous Methods section?


*
http://docs.openlmi.org/en/latest/openlmi-tools/shell/associated_objects.html

Would it be worthwhile having a brief discussion of what associations
are and how you use them to navigate the CIM object model?

* http://docs.openlmi.org/en/latest/openlmi-tools/shell/indications.html

We should mention that an Indicator is an event or alert that signals a
change on the managed system. Explain that an Indication is produced by
a Provider and received by a Listener or indication handler. Mention
that indications are built into Providers and that you can find them in
the Provider documentation.

General notes:

It would be nice to mention the standard scripts - what they are
intended for and where they live. Perhaps choose one as an example and
show how to use it and describe the various sections. Mention that these
scripts represent examples of recommended best practices for LMIShell
scripts. Mention that these scripts are also intended to be copied and
modified for specific purposes.


Notes on LMI Metacommand

Should this chapter come before the LMIShell chapter? LMI Metacommands
are likely to be the entry point into OpenLMI for most sysadmins.

*
http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/logicalfile/cmdline.html

We should mention that goals of the file command. Specifically, that it
is not intended to be a general purpose file manipulation command, and
that it does not have the ability to create, delete, or copy individual
files.

*
http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/powermanagement/cmdline.html

Note that the lmi power command is running inside the OS of the managed
system. Thus, it does not have the ability to power-on a system.
Power-on can be done manually or by accessing a BMC or managed power
switch. Power-on is currently out of scope for OpenLMI and the LMI
metacommand.

*
http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/realmd/cmdline.html

Unlike the previous commands, realmd isn't available by default. Mention
what needs to be done to install realmd and the realmd metacommand.

*
http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/service/cmdline.html

Should we mention it when we expect a command to take a significant
amount of time to complete? Something like "It may take 30-60 seconds to
return a list of all available services."

*
http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/software/cmdline.html

Mention that the software metacommand is built on yum and that some
operations may be slow. Notably, that a "lmi software list" of all
software packages may require over five minutes to return a list of
several thousand packages. We recommend using targeted searches instead
of full lists. Provide some examples of searching for packages. 

The SHOW and LIST commands are documented; should the SEARCH command
also be documented? It looks like you need to use SEARCH to get lists of
packages (like openlmi) and then use the LIST and SHOW commands. It
would be helpful to have some examples for how to use the SW
metacommand. I found it a bit confusing that you need to use "sw list
files openlmi-realmd" but "sw show pkg openlmi-realmd".


SSSD Command

Mention that SSSD is optional and must be installed before the
metacommand can be used.


STORAGE Command

It would be helpful to start out by identifying the commands that
provide information on storage vs. those that can modify storage. The
storage list, show, and tree commands display information. These are
likely to be the starting point for using the storage command.

Under LUKS mention that this is the encrypted file system.

Under THINLV and THINPOOL mention what thin provisioning is and how it
is used.


COMMAND DEVELOPMENT

*
http://docs.openlmi.org/en/latest/openlmi-tools/scripts/development.html

Is there an easy way to get the descriptions in the Term/Description
table to line wrap?

This section is excellent - something I've been looking for! I need to
spend some quality time with it before providing comments.



More information about the openlmi-devel mailing list