*******************************************************************************
* 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.

Following cli tools are part of this sub-project:

* lmiservice
    This tool provides remote service management. Supported operations with
    services are: start, stop, restart, enable, disable, reload, try-restart,
    cond-restart, reload-or-restart and status.

* lmipower
    This tool provides remote power management. Supported operations with
    remote machine are: poweroff, reboot, suspend, hibernate, force-poweroff,
    force-reboot.

* lmiuser
    This tool provides remote user management. Currently supported operations
    are: list-users, list-groups, group-members (list of groups, where
    the specified user belongs to), useradd.

* lmiip
    This tool provides remote networking management. Currently it provides
    following operations: set static ip address, remove address assigned
    to an interface, list ip address setting for all/selected interface.

* 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 command-line tools:

* lmiservice
    $ lmiservice -h <hostname> -u <username> -p <password> status <service_name>
    $ lmiservice -h <hostname> -u <username> -p <password> start <service_name>
    $ lmiservice -h <hostname> -u <username> -p <password> stop <service_name>

* lmipower
    $ lmipower -h <hostname> -u <username> -p <password> poweroff
    $ lmipower -h <hostname> -u <username> -p <password> reboot

* lmiuser
    $ lmiuser -h <hostname> -u <username> -p <password> list-users
    $ lmiuser -h <hostname> -u <username> -p <password> list-groups
    $ lmiuser -h <hostname> -u <username> -p <password> group-members <group_name>

* lmiip
    $ lmiip -h <hostname> -u <username> -p <password> addr show
        - shows available network interfaces and their associated addresses
    $ lmiip -h <hostname> -u <username> -p <password> addr set <address>/<mask> dev <device_name>
        - sets the ipv4 address to specified interface
    $ lmiip -h <hostname> -u <username> -p <password> addr

* lmi-shell
    - 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>
        $
