software: added configuration section to doc

2 files changed, 152 insertions, 0 deletions

diff --git a/src/software/doc/admin/configuration.rst b/src/software/doc/admin/configuration.rst
new file mode 100644
index 0000000..10f9c98
--- /dev/null
+++ b/src/software/doc/admin/configuration.rst
@@ -0,0 +1,151 @@
+Configuration
+=============
+There are various options affecting behaviour of *OpenLMI Software* provider.
+All of them can be fine-tuned using two configuration files. The main one is
+located at: ::
+    
+    /etc/openlmi/software/software.conf
+
+The other one is a global configuration file for all providers in *OpenLMI*
+project and serves as a fallback, for options not specified in the main one.
+It's located in: ::
+
+    /etc/openlmi/openlmi.conf
+
+Since this is a common setup for all *OpenLMI* providers, administator can
+specify options common to all in the global configuration file, while the
+values specific for particular provider can be overriden in its main one
+(``/etc/openlmi/${provider}/${provider}.conf``).
+
+Treating boolean values
+-----------------------
+Options expecting boolean values treat following strings as valid ``True``
+values:
+
+    * ``True``
+    * ``1``
+    * ``yes``
+    * ``on``
+
+While the following are considered ``False``:
+
+    * ``0``
+    * ``no``
+    * ``False``
+    * ``off``
+
+These words are checked in a case-insensitive way. Any other value isn't
+considered valid [1]_.
+
+Options
+-------
+Follows a list of valid options with sections enclosed in square brackets.
+
+*CIM* options
+~~~~~~~~~~~~~
+
+    ``[CIM] Namespace`` : defaults to ``root/cimv2``
+        Is a *CIM* namespace, where *CIM* classes of this provider are
+        registered.
+
+    ``[CIM] SystemClassName`` : defaults to ``PG_ComputerSystem``
+        Sets the class name used to refer to computer system. Different cimmoms
+        can instrument variously named computer systems and some may not
+        instrument any at all. `Sfcb`_ is an example of the later, it needs the
+        ``sblim-cmpi-base`` package installed providing the basic set of
+        providers containing ``Linux_ComputerSystem``. So in case you run a
+        ``Sfcb`` or you preferr to use providers from ``sblim-cmpi-base``
+        package, you need to change this to ``Linux_ComputerSystem``.
+
+*YUM* options
+~~~~~~~~~~~~~
+Options related to the use of *YUM* API and its configuration.
+
+    ``[Yum] LockWaitInterval`` : defaults to 0.5
+        Number of seconds to wait before next try to lock yum package database.
+        This applies, when yum database is locked by another process.
+
+    ``[Yum] FreeDatabaseTimeout = 60`` : defaults to 60
+        Number of seconds to keep package cache in memory after the last use
+        (caused by user request). Package cache takes up a lot of memory.
+
+*Log* options
+~~~~~~~~~~~~~
+
+    ``[Yum] Level`` : defaults to ``ERROR``
+        Can be set to one of the following:
+        
+            * ``CRITICAL``
+            * ``ERROR``
+            * ``WARNING``
+            * ``INFO``
+            * ``DEBUG``
+            * ``TRACE_WARNING``
+            * ``TRACE_INFO``
+            * ``TRACE_VERBOSE``
+
+        It specifies the minimum severity of messages that shall be logged.
+        Messages having ``DEBUG`` or more severe level are sent to *CIMOM*
+        using standard function ``CMLogMessage()``. Tracing messages (whose
+        level names start with ``TRACE_`` use the ``CMTraceMessage()`` instead.
+
+        Please consult the documentation of your *CIMOM* to see, how these
+        messages can be treated and logged to different facilities.
+
+        .. note::
+            This does not have any effect if the ``[Log] FileConfig`` option is
+            set.
+
+    ``[Yum] Stderr`` : defaults to ``False``
+        Whether to enable logging to standard error output. This does not
+        affect logging to *CIMOM* which stays enabled independently of this
+        option.
+
+        This is mostly usefull when debugging with *CIMOM* running on
+        foreground.
+
+        .. note::
+            This does not have any effect if the ``[Log] FileConfig`` option is
+            set.
+
+        .. seealso::
+            Since this accepts boolean values, refer to
+            `Treating boolean values`_ for details.
+
+    ``[Yum] FileConfig`` : defaults to empty string
+        This option overrides any other logging option. It provides complete
+        control over what is logged, when and where. It's a path to a logging
+        configuration file with format specified in:
+        http://docs.python.org/2/library/logging.config.html#configuration-file-format
+        Path can be absolute or relative. In the latter case it's relative to
+        a directory of this configuration file.
+
+*YumWorkerLog* options
+~~~~~~~~~~~~~~~~~~~~~~
+This section is targeted mostly on developpers of *OpenLMI Software* provider.
+*YUM* API is accessed exclusively from separated process called ``YumWorker``.
+Because separated process can not send its log messages to *CIMOM*, its
+logging configuration needs to be configured extra.
+
+    ``[YumWorkerLog] OutputFile`` : defaults to empty string
+        This is an absolute or relative path to a file, where the logging
+        will be done. Without this option set, logging of ``YumWorker`` is
+        disabled (assuming the ``[YumWorkerLog] FileConfig`` option is also
+        unset). 
+
+    ``[YumWorkerLog] Level`` : defaults to ``DEBUG``
+        This has generally the same meaning as ``Level`` in previous section
+        (`Log options`_). Except this affects only logging of ``YumWorker``
+        process.
+
+    ``[YumWorkerLog] FileConfig`` : defaults to empty string
+        Similar to the ``FileConfig`` option in `Log options`_. This overrides
+        any other option in this section.
+
+-------------------------------------------------------------------------------
+
+.. [1] Default value will be used as a fallback. This applies also to other
+       non-boolean options in case of invalid value.
+
+.. ****************************************************************************
+.. _Sfcb: http://sourceforge.net/apps/mediawiki/sblim/index.php?title=Sfcb
diff --git a/src/software/doc/admin/index.rst b/src/software/doc/admin/index.rst
index 5278214..93043b8 100644
--- a/src/software/doc/admin/index.rst
+++ b/src/software/doc/admin/index.rst
@@ -13,6 +13,7 @@ Contents:
 
     introduction
     dmtf
+    configuration
     usage
 
 .. ifconfig:: includeClasses