diff options
Diffstat (limited to 'doc/admin/journald')
| -rw-r--r-- | doc/admin/journald/index.rst | 91 | ||||
| -rw-r--r-- | doc/admin/journald/usage.rst | 55 |
2 files changed, 146 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 diff --git a/doc/admin/journald/usage.rst b/doc/admin/journald/usage.rst new file mode 100644 index 0000000..69fe48b --- /dev/null +++ b/doc/admin/journald/usage.rst @@ -0,0 +1,55 @@ +OpenLMI Journald usage +====================== + +The OpenLMI Journald provider depends on running journald daemon. See the `systemd +<http://www.freedesktop.org/software/systemd/man/systemd-journald.service.html>`_ +manual for how to enable the journald service. + + +Listing a log +------------- + +This example shows simple enumeration through available :ref:`LMI_JournalLogRecord<LMI-JournalLogRecord>` +instances in classic syslog-like format:: + + #!/usr/bin/lmishell + c = connect("localhost", "pegasus", "test") + for rec in c.root.cimv2.LMI_JournalMessageLog.first_instance().associators(): + print "%s %s %s" % (rec.MessageTimestamp.datetime.ctime(), rec.HostName, rec.DataFormat) + +.. note:: + Only a limited number of records are being enumerated and printed out, please + see the :ref:`inst-enum-limit` remark. + + +Iterating through the log +------------------------- + +This example uses iterator methods of the :ref:`LMI_JournalMessageLog<LMI-JournalMessageLog>` +class to continuously go through the whole journal:: + + #!/usr/bin/lmishell + c = connect("localhost", "pegasus", "test") + inst = c.root.cimv2.LMI_JournalMessageLog.first_instance() + r = inst.PositionToFirstRecord() + iter_id = r.rparams['IterationIdentifier'] + while True: + x = inst.GetRecord(IterationIdentifier=iter_id, PositionToNext=True) + if x.rval != 0: + break + print "".join(map(chr, x.rparams['RecordData'])) + iter_id = x.rparams['IterationIdentifier'] + + +Sending new message to log +-------------------------- + +Simple example that uses :ref:`LMI_JournalLogRecord.create_instance()<LMI-JournalLogRecord>` +CIM method to send a new message in the log:: + + #!/usr/bin/lmishell + c = connect("localhost", "pegasus", "test") + c.root.cimv2.LMI_JournalLogRecord.create_instance({"CreationClassName": "LMI_JournalLogRecord", + "LogCreationClassName": "LMI_JournalMessageLog", + "LogName": "Journal", + "DataFormat": ""}) |