Added documentation of openlmi.conf file.

This applies only to the top level combined documentation,
if a provider introduces its own config file and options, it
still must be mentioned in the provider's docs.

2 files changed, 66 insertions, 0 deletions

diff --git a/tools/gendoc/doc/config.rst b/tools/gendoc/doc/config.rst
new file mode 100644
index 0000000..7bf292f
--- /dev/null
+++ b/tools/gendoc/doc/config.rst
@@ -0,0 +1,65 @@
+Configuration
+=============
+
+Configuration files
+-------------------
+
+``/etc/openlmi/openlmi.conf`` is OpenLMI master configuration file.
+
+Each provider may introduce additional configuration files, see their
+documentation. If a provider uses its own configuration file, the
+provider-specific one is parsed first and all missing options are
+then read from OpenLMI master configuration file.
+
+Using this approach, administators can set e.g. one namespace for all
+providers in ``/etc/openlmi/openlmi.conf`` and different log levels
+for some providers in their configuration files.
+
+File format
+-----------
+Configuration files has simple .ini syntax, with ``#`` or ``;`` used for
+comments.
+
+Default configuration::
+
+     [CIM]
+     Namespace=root/cimv2
+     SystemClassName=Linux_ComputerSystem
+
+     [Log]
+     Level=ERROR
+     Stderr=false
+
+======= =================== ==================== ===========
+Section Option name         Default value        Desciption
+======= =================== ==================== ===========
+``CIM`` ``Namespace``       root/cimv2           Namespace where OpenLMI providers are registered.
+``CIM`` ``SystemClassName`` Linux_ComputerSystem Name of CIM_ComputerSystem class, which is used to represent the computer system. It will be used as ``SystemClassName`` property value of various classes.
+``Log`` ``Level``           ERROR                Chooses which messages are logged, either to CIMOM and (if configured) to standard error output. Available levels (sorted by severity) are:
+
+                                                    * CRITICAL
+                                                    * ERROR
+                                                    * WARNING
+                                                    * INFO
+                                                    * DEBUG
+                                                    * TRACE_WARNING
+                                                    * TRACE_INFO
+                                                    * TRACE_VERBOSE
+
+                                                 Levels below INFO (= TRACE_WARNING, TRACE_INFO and DEBUG) are useful mainly for debugging and bug reporting.
+``Log`` ``Stderr``          false                Toggles sending of log messages to standard error output of the CIMOM.
+======= =================== ==================== ===========
+
+Logging
+=======
+
+If logging is enabled, all log messages with level INFO and above are sent to
+CIMOM using standard CMPI ``CMLogMessage`` function. Consult documentation of
+your CIMOM how to enable output of these messages into CIMOM logs.
+
+Messages with TRACE_WARNING and below are sent to CIMOM using ``CMTraceMessage``
+and should be visible in CIMOM tracing log. Again, please consult your CIMOM
+documentation how to enable tracing logs.
+
+With ``Stderr`` configuration option enabled, all logs are sent both to CIMOM
+and to the standard error output of the CIMOM.
diff --git a/tools/gendoc/doc/index.rst b/tools/gendoc/doc/index.rst
index b2a39fa..88db9a4 100644
--- a/tools/gendoc/doc/index.rst
+++ b/tools/gendoc/doc/index.rst
@@ -18,6 +18,7 @@ Table of Content
    :maxdepth: 2
 
    install
+   config
    clones/openlmi-providers/src/account/doc/source/index
    clones/openlmi-providers/src/logicalfile/doc/source/index
    clones/openlmi-networking/build/doc/admin/index