.. _configuration:

Configuration
=============
*LMI metacommand* has the main configuration file located in: ::

    /etc/openlmi/scripts/lmi.conf

User can have his own configuration file taking precedence over anything in
global one above: ::

    $HOME/.lmirc

Configuration is written in INI-like configuration files. Please refer to
`ConfigParser`_'s documentation for details.

Follows a list of sections with their list of options. Most of the options
listed here can be overridden with command line parameters.

.. seealso::
    :py:mod:`~lmi.scripts.common.configuration`

.. _sect_main:

Section [Main]
--------------
.. _main_command_namespace:

CommandNamespace : ``string``
    Python namespace, where command entry points will be searched for.

    Defaults to ``lmi.scripts.cmd``.

.. _main_trace:

Trace : ``boolean``
    Whether the exceptions should be logged with tracebacks.

    Defaults to ``False``.

    Can be overridden with ``--trace`` and ``--notrace`` options on
    command-line.

    .. note::
        For most exceptions generated by scripts a *Verbosity* option
        needs to be highest as well for tracebacks to be printed.

.. _main_verbosity:

Verbosity: ``integer``
    A number within range -1 to 2 saying, how verbose the output shall be. This
    differs from `log_level`_, which controls the logging messages written to
    file. If logging to console is enabled it sets the minimum severity level.
    -1 Suppresses all messages except for errors. 0 shows warnings, 1 info
    messages and 2 enables debug messages. This option also affects the
    verbosity of commands, making them print more information to ``stdout``.

    Defaults to 0.

    Can be overridden with ``-v`` and ``-q`` flags on command-line.

Section [CIM]
-------------
.. _cim_namespace:

Namespace : ``string``
    Allows to override default CIM namespace, which will be passed to
    script library functions.

    Defaults to ``root/cimv2``.

Section [SSL]
-------------
.. _ssl_verify_server_certificate:

VerifyServerCertificate : ``boolean``
    Whether to verify server-side certificate, when making secured
    connection over https.

    Defaults to ``True``.

    Can be overridden with ``-n | --noverify`` flag on command-line.

Section [Format]
----------------
.. _format_human_friendly:

HumanFriendly : ``boolean``
    Whether to print values in human readable forms (e.g. with units).

    Defaults to ``False``.

    Can be overridden with ``-H | --human-frienly`` flag on command-line.

.. _format_lister_format:

ListerFormat : one of {``csv``, ``table``}
    What format to use, when listing tabular data. ``csv`` format allows for
    easy machine parsing, the second one is more human friendly.

    Defaults to ``table``.

    Can be overridden with ``-L | --lister-format`` option on command line.

.. _format_no_headings:

NoHeadings : ``boolean``
    Whether to suppress headings (column names) when printing tables.

    Defaults to ``False``.

    Can be overridden with ``-N | --no-headings`` option on command line.

Section [Log]
-------------
.. _log_level:

Level : one of {``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``}
    Minimal severity level of messages to log. Affects only logging to a
    file. See the `main_verbosity`_ option controlling console logging level.

    Defaults to ``ERROR``.

LogToConsole : ``boolean``
    Whether the logging to console is enabled.

    Defaults to ``True``

    On command-line the same could be achieved by redirecting ``stderr`` to
    ``/dev/null``.

.. _log_console_format:

ConsoleFormat : ``string``
    Format string used when logging to a console. This applies to warnings and
    more severe messages. Refer to `Format String` in python's documentation for
    details.

    Defaults to ``%(levelname)s: %(message)s``.

.. _log_console_info_format:

ConsoleInfoFormat : ``string``
    Format string used when logging to a console. Applies to info and debug
    messages. Refer to `Format String` in python's documentation for details.


    Defaults to ``%(message)s``.

.. _log_file_format:

FileFormat : ``string``
    Format string used, when logging to a console. This applies only when
    *OutputFile* is set (see below). Refer to `Format String` in python's
    documentation for details.

    Defaults to
        ``%(asctime)s:%(levelname)-8s:%(name)s:%(lineno)d - %(message)s``

.. _log_output_file:

OutputFile : ``string``
    Allows to set a path to file, where messages will be logged. No log
    file is written at default.

    Defaults to empty string.

    Can be overridden on command line with ``--log-file`` option.

.. ****************************************************************************

.. _`RFC 822`:        http://tools.ietf.org/html/rfc822.html
.. _ConfigParser:     http://docs.python.org/2/library/configparser.html
.. _Format String:    http://docs.python.org/2/library/logging.html#logrecord-attributes