*******************************************************************************
* OpenLMI                                                                     *
*******************************************************************************

The OpenLMI project provides a common infrastructure for the management of Linux
systems. Capabilities include configuration, management and monitoring of
hardware, operating systems, and system services. OpenLMI includes a set of
services that can be accessed both locally and remotely, multiple language
bindings, standard APIs, and standard scripting interfaces.


*******************************************************************************
* OpenLMI-tools                                                               *
*******************************************************************************

OpenLMI-tools is a set of command line tools for OpenLMI-providers.

OpenLMI-tools currently consists of:

* lmishell
    This tool provides interactive shell for CIM objects management.

*******************************************************************************
* Build Dependencies                                                          *
*******************************************************************************

For proper usage of the tools, the python environment is required. Tools also
require pywbem module.

*******************************************************************************
* Installation                                                                *
*******************************************************************************

Following steps will install cli-tools and python modules, that contain
python clients for each OpenLMI provider.

$ mkdir build && cd build
$ ../configure --prefix=/usr
# make install

*******************************************************************************
* Example usage                                                               *
*******************************************************************************

Following examples show, how to use lmishell:

* general usage example:
    - how to start a shell:
        $ lmishell
        >

    - how to exit from the shell:
        > <ctrl+d>
        $
    - how to use previous commands:
        - press up arrow to list previous commands in history
        - reverse-search by <ctrl+r> and type substring of the command

    - how to clear a history:
        > clear_history()

    - how to connect to a remote machine:
        > c = connect("hostname", "username", "password")

        or

        > c = connect("hostname", "username")
        password: <not echoed>
        >
    - how to turn off display "sugar" for return values:
        > use_display_sugar(False)

* example how to stop a service:
    $ lmishell
    > c = connect("hostname", "username", "password")
    > service = c.root.cimv2.LMI_Service.first_instance("service")
    > service.Status
    OK
    > service.StopService()
    hostname: ok (0)
    > service.Status
    Stopped
    > <ctrl+d>
    $

* example how to show a class documentation:
    $ lmishell
    > c = connect("hostname", "username", "password")
    > lmi_service = c.root.cimv2.LMI_Service
    > lmi_service.doc()
        ... class documentation ...
    <q>
    > <ctrl+d>
    $

* example how to show an instance documentation with properties:
    $ lmishell
    > c = connect("hostname", "username", "password")
    > service = c.root.cimv2.LMI_Service.first_instance()
    > service.doc()
        ... instance documentation with properties ...
    > <ctrl+d>
    $

* example how to print available namespaces, classes, methods, etc
    $ lmishell
    > c = connect("hostname", "username", "password")
    > c.print_namespaces()
    root
    > c.root.print_namespaces()
    cimv2
    interop
    PG_InterOp
    PG_Internal
    > c.root.cimv2.print_classes()
        ... available classes ...
    > service = c.root.cimv2.LMI_Service.first_instance()
    > service.print_methods()
        ... instance methods ...
    > service.print_properties()
        ... instance properties ...
    > <ctrl+d>
    $

* example how to get associated objects with an instance
    $ lmishell
    > c = connect("hostname", "username", "password")
    > instance = c.root.cimv2.LMI_Group.first_instance()
    > associated_objects = instance.associators()
    > <ctrl+d>
    $
* example how to get association objects with an instance
    $ lmishell
    > c = connect("hostname", "username", "password")
    > os = c.root.cimv2.Linux_OperatingSystem.first_instance()
    > association_objects = os.references()
    > <ctrl+d>

* example how to update an object property value
    $ lmishell
    > c = connect("hostname", "username", "password")
    > user = c.root.cimv2.LMI_Account.first_instance()
    > user.LoginShell = "/usr/bin/zsh"
    > user.push()
    > <ctrl+d>
    $

* example how to delete an instance from CIM broker
    $ lmishell
    > c = connect("hostname", "username", "password")
    > instance = c.root.cimv2.LMI_Account.first_instance()
    > instance.delete()
    > <ctrl+d>
    $
