1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
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.
Journald is a daemon working with journals. Journal is a log, a set of log
records, chronologically ordered. Records are structured, able to carry multiple
(custom) data fields. By implementation, journald is able to work with multiple
(separate) journals but we use the mixed way for the moment, which is typical
in production use.
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 defined by the ``JOURNAL_MAX_INSTANCES_NUM`` define in ``Journal.h``
source file. Please use iterators instead to get access to all records.
Iteration and iterators
-----------------------
Iteration is a different way of getting data through the log records. Comparing
to the usual instance enumeration, this is a sequential-like access with ability
to seek back and forth in the journal. Retrieving individual records might be
slower than direct random access though memory consumption is kept on a low
level.
Please check the :ref:`LMI_JournalMessageLog<LMI-JournalMessageLog>` class
reference for detailed description of available iterator-related methods.
Implemented iterator methods are :ref:`PositionToFirstRecord()<LMI-JournalMessageLog-PositionToFirstRecord>`,
:ref:`PositionAtRecord()<LMI-JournalMessageLog-PositionAtRecord>`,
:ref:`GetRecord()<LMI-JournalMessageLog-GetRecord>` and
:ref:`CancelIteration()<LMI-JournalMessageLog-CancelIteration>`. Only relative movement
is supported by the :ref:`PositionAtRecord()<LMI-JournalMessageLog-PositionAtRecord>` method.
A key element of the iteration process is the iteration identifier that is
typically passed in the methods listed above. Only the :ref:`PositionToFirstRecord()<LMI-JournalMessageLog-PositionToFirstRecord>`
method is able to create new iteration identifier without the need of specifying
one.
Iteration identifiers are specific to the provider and are opaque. They're are
persistent to some extent, surviving unexpected CIMOM runtime cleanup. The only
requirement for persistency to work is the journal record the iterator identifier
previously pointed to to be available at the time the iterator is reused.
I.e. it won't survive log rotation.
A remark for the :ref:`LMI_JournalMessageLog.GetRecord()<LMI-JournalMessageLog-GetRecord>`
method: the outgoing RecordData argument carries string data encoded in an array
of uint8 elements as defined by the model. This is quite limiting and also still
very free-form on the other hand. To conform the definition, we put UTF-8 encoded
string split by characters in the array and is up to clients to decode it back
to a readable form.
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
|
