1 files changed, 91 insertions, 0 deletions
diff --git a/doc/admin/journald/index.rst b/doc/admin/journald/index.rst
new file mode 100644
index 0000000..ddb93e4
--- /dev/null
+++ b/doc/admin/journald/index.rst
@@ -0,0 +1,91 @@
+OpenLMI Journald Provider documentation
+=======================================
+
+OpenLMI Journald is a CIM provider exposing `systemd <http://freedesktop.org/wiki/Software/systemd/>`_
+journald log records and basic means of iteration and log writing.
+
+Classes used by the provider were chosen to mimic the sblim-cmpi-syslog provider
+set of classes allowing drop-in replacement in production tools. We haven't been
+able to find a profile it conforms to though. There's a related DMTF profile
+`DSP1010 "Record Log Profile" <http://www.dmtf.org/sites/default/files/standards/documents/DSP1010_2.0.0.pdf>`_
+which may be subject to extension of this provider in the future.
+As a benefit, by using the parent classes (e.g. :ref:`CIM_LogRecord<CIM-LogRecord>`), one is able
+to mix log records from orthodox syslog and journald together.
+
+
+Provider features
+------------------
+
+This is a short list of provider features:
+ * log records reading
+ * log record iteration using persistent iterators
+ * new records indication
+ * writing new log records
+
+For the moment, global journal is used, all journal files are mixed together.
+
+The provider also comes with a test suite covering most of its functionality.
+
+
+.. _inst-enum-limit:
+
+Number of LMI_JournalLogRecord instances enumerated limitation
+--------------------------------------------------------------
+
+Testing the provider showed up an issue with enumeration of :ref:`LMI_JournalLogRecord<LMI-JournalLogRecord>`
+instances. On the testing machine there was 199583 journal records, which is
+simply too much for the CIMOM, exceeding memory and the resulting XML reply
+limits.
+
+An artificial limit has been set, currently to 1000 most recent records. This
+limit is set by the ``JOURNAL_MAX_INSTANCES_NUM`` define in ``Journal.h`` source
+file.
+
+The  :ref:`LMI_JournalMessageLog<LMI-JournalMessageLog>` class provides several
+methods for iterating and seeking in a complete log.
+
+
+New log records writing security concerns
+-----------------------------------------
+
+The provider has an ability to send new messages to the log. This may be percieved
+as a security issue in someone's eyes as long as you can specify custom message
+format that is sent to the log. The only obstacle preventing anyone in sending
+spoof messages is the rather weak CIM authentication model.
+
+However, as long as journald is a structured logging system, further information
+is stored along every log record. Messages sent through the OpenLMI Journald
+provider may be identified by supplemental fields such as ``_COMM`` and ``_EXE``,
+pointing to a CIMOM that had been running the provider code or even the ``CODE_FUNC``
+field, pointing to a specific function that invoked the journald library code.
+
+
+Potential indications endless loop
+----------------------------------
+
+Just a note for implementing a system processing the indications. Having no
+specific filter for the indication subscription and performing an action
+within the indication handler that involves a message being sent to syslog
+may result in an endless loop as long such action generates another indication
+for the fresh syslog message. Even a CIMOM in certain situations (i.e. debugging
+in verbose mode) may generate additional messages while sending an indication
+that in turn will generate another one.
+
+
+Contents
+---------
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+
+.. ifconfig:: includeClasses
+
+   OpenLMI Journald CIM Classes:
+
+   .. toctree::
+      :maxdepth: 1
+
+      mof/tree
+      mof/index