recent rsyslog changes

Again, I am doing small changes, mostly review, at this time. So I have batched up some things. Probably I’ll switch back to a more daily mode, as it allows to keep better in touch. We’ll see (comments appreciated).

Here comes the log:

2007-09-10
– bumped version number to 1.19.6
– fixed a bug that in –enable-debug mode caused an assertion when the
discard action was used
2007-09-07
– added eCmdHdlrGetWord command handler
– added $ModDir config directive
– modified $ModLoad so that an absolute path may be specified as
module name (e.g. /rsyslog/ommysql.so)
– applied patch by varmojfekoj two fix two potential segfault situations
– cleaned up some signed/unsinged char issues
– released 1.19.5
2007-09-10
– bumped version number to 1.19.6
– fixed a bug that in –enable-debug mode caused an assertion when the
discard action was used
2007-09-11
– applied patch by varmojfekoj to change signal handling to the new
sigaction API set (replacing the depreciated signal() calls and its
friends.
– did a full review of all remaining TODO items in code – nothing of
importance found (but some minor nits like comments fixed)
– cleaned up compiler warnings
– applied patch by varmojfekoj to FIX a bug that could cause
segfaults if empty properties were processed using modifying
options (e.g. space-cc, drop-cc)
– fixed man bug: rsyslogd supports -l option
– checked -s/-l option and found that they work as expected – closed case
– added some comments in relation to -s/-l option
– released 1.19.6
– removed compiler warnings in non-debug mode
– fixed a bug that caused the CStr class to not honor the parameter to
return NULL on empty string – causes a mem leak and can create favourable
environment for other bugs (as it leads to empty hostnames)
– pulled 1.19.6 (no downloads so far), created new 1.19.6 with the bugfix,
re-released that (now tagged v1-19-6b in cvs)

bug hunting…

We have received feedback that the 1.19.x releases of rsyslog contain a bug that leads to a segfault after some time. Of course, this is a very bad thing to happen. After all, the primary goal for the rsyslog project is reliability and it should be able to survive even in the worst conditions (e.g. low system memory). So this bug is clearly unacceptable and has received highest priority.

Unfortunately, it is hiding very well. We are all looking into troubleshooting this beast. Thankfully, there is a lot of community support, especially with testing. What makes this bug so hard to find is, among others, the inability to reproduce it in lab. So the project is totally dependent on user feedback. As current reports have shown, we also currently assume that releases prior to 1.19.0 can also be affected – so it is not as easy as checking the changes.

I receive very valuable help by varmojfekoj. He is already a frequent and great contributor of patches. His skills and experience are extremely valuable and I am very glad to have him work on this project. Please give him a big hand. Thanks, varmojfekoj, the project would not be that far without your help!

While the bug itself is obviously a very bad thing, it has some good side-effects. Most importantly, the code is getting another round of very in-depth review. That review has already brought up some fixes for obscure situations. Situations that I’d expect to happen extremely infrequently (if at all) in reality. But now even those are fixed. And I am sure that the review will bring even more benefit as it continues. Of course, I’d be glad if we find the bug ASAP, but it is good to know that all that work also provides additional benefit (at least that keeps my depression level low ;)).

The bad thing, besides the bug itself, is that the bug hunt obviously defers other work. Most importantly, I refrain from making any changes that may not be related to clean up or bug fixing. I think it is not smart to introduce new code (read: complexity) at this stage of the project. And, of course, all resources should focus on fixing that bug, so there wouldn’t even be time to enhance other parts of the code. So for all of you waiting for new features: please bear with us, the implementation schedule will slip a little bit.

If you experience stability problems, please report. Each reports helps us understand the problem somewhat better.

recent rsyslog changes

Now that I am back working on the rsyslog code, I will continue to provide information about what I am doing. In most cases, however, I will not provide daily logs. The reason is that I currently focus on new design and will leave rsyslog code mature. So changes will be relatively infrequent (at least I plan so ;]).

Here is the work log for the past days:

2007-09-04
– integrated patches from Michel Samia and varmojfekoj
– released 1.19.4
– changed some calls to CStr class to their “safe” counterpart – they could
cause program aborts if the object in question was an empty string
2007-09-05
– added some links to doc
– removed an invalid config sample from sample.conf
– changed part of the CStr interface so that better error tracking
is provided and the calling sequence is more intuitive (there were
invalid calls based on a too-weired interface)
– (hopefully) fixed some remaining bugs rooted in wrong use of
the CStr class. These could lead to program abort.
2007-09-06
– added forwarding information to sysklogd (requires special template)
to config doc

rsyslog config again…

I am writing a lot about rsyslog config file formats these days. Now I think I come closer to a result. The past days, I have thought a lot about potential formats. Now, I have created configuration samples in the rsyslog wiki. Also, some others have posted hints.

I now have two favorites: one is a XML-based format. Its advantage is that it would be easy to use when (if) we implement NETCONF protocol. If I assume NETCONF will actually become *the* configuration standard, this is a big pro argument for that format. However, I consider the format to be exceptionally bulky and pretty less intuitive. In other words, I do not really like it – but that doesn’t mean it is a bad choice.

What I like more is a programming-language like format (and especially the last sample in the wiki article). It looks somewhat more “natural” to me, but this may be because I like programming languages ;) In any case, I think it is easier to grasp and modify, but of course it is not standardized. Plus, there are three different samples, each in a different style and level of verbosity.

The question is now what users consider to be best. I sincerely hope to receive feedback, as I probably have only one “shot” at this for the foreseeable future (well… I have to admit that I thought about dynamically loadable config file parsers, but that adds probably too much complexity).

So if you have anything to say, please speak up now!
If you do not know where to make yourself heard, simply post to the rsyslog forum thread on the config file format.

where is liblogging heading to?

I just received a question whether or not I plan to change the build system for liblogging to a modern one, just like I have done with rsyslog recently.

As a reminder, liblogging is the library that provides RFC 3195 functionality to rsyslog. Of course, others can integrate it too. Writing liblogging was a considerable effort. When I did this, I had hoped that RFC 3195 would become much more dominant in the logging space. Unfortunately, the current version became a failure. This is also one reason that rsyslog supports receiving messages via 3195 but not sending them – the interest was too low (to phrase it politely) and other features received priority.

Liblogging development is currently “on hold”. I was tempted to completely abandon it, but then Cisco moved RFC 3195 support into IOS. That was one thing that made me hope that the standard may become accepted in the long term. Recently, while designing rsyslog v3, I noticed that rfc 3195 (or more precisely BEEP, RFC 3080) indeed offers a very good choice for protocol extensions. I am currently very seriously thinking about re-vitalizing liblogging and make it the foundation of rsyslog-to-rsyslog communication.

But there are also a number of other subtleties. Most importantly, the current RFC 3195 is insufficient for practical purposes. For example, it limits message size to 1K. It also does not support new syslog headers. The IETF is considering a new version of 3195, which will fix these shortcomings. Of course, I can go ahead and use from 3195 what makes sense to me and extend the rest on my own. But that will cause trouble in the long term and I do not really like that.

There are also some funding issues. As you possibly know, we fund our projects also via closed-source Windows software (e.g. MonitorWare Agent or EventReporter). The current liblogging has a BSD-style license. That was chosen in the hope it will help to make it a standard. However, it also enables our closed-source competitors to pull our work without contributing anything back.

So, to be honest, if we go ahead and do a new substantial effort on liblogging, we will probably release it under GPLv3. That enables everybody who does open source to use it, but prohibits our closed-source competitor to integrate the library. Of course, we need to retain the right to use it ourselfs in our commercial products, but I think it can be arranged in a way that is compatible with GPLv3 – at least I have seen a number of projects doing that.

To summarize in short words: liblogging is currently on hold and will be for at least some more weeks. We are deciding if we extend it. If so, that will go along with rsyslog development.

rsyslog v3 object model and message flow

I thought quite a while about the upcoming configuration file format today. I
have to admit, I am not very satisfied with the outcome. I have a few potential
formats, but either they are too brief (and quite complex) or there is a lot of
text. Also, I am not satisfied yet with the flexibility of the format. I guess
this is a harder nut to crack than I thought. Unfortunately, I can not yet post
any of the ideas, as I have done them on paper and they are probably unreadable
to anybody but me. Bear with me, I’ll create an online version these days.

But to understand any config file formats, you need to know more about the
object model. A first version of that model has materialized on my mind, and
actually rsyslog 1.18.0 and above is already supporting parts of it. To aid
understanding (and get some discussion going), I have created a quick outline of
what I have in mind. It’s textual, it’s incomplete and it can not be formally
verified. Still, I think (sincerely hope), it is useful. So I decided to post
what I currently have. Besides the actual object model discussion, it will help
a great deal in understanding what needs to be in the config file (thus it’s
currently a bit biased towards configurable objects and internal ones are almost
completely missing).

rsyslog v3 Objects

Rsyslog uses objects, even though it is written in C. This can quite well be
done. Only at some points (like inheritance) we need to fiddle a bit with the
language. But nothing to hard to be done. We try to keep object overhead very
low, so it should be more like traditional C than C++.

module

The module object is the base class for anything that even remotely looks
like a loadable object. In the long term, that might eventually be almost
everything. It handles the necessary plumbing like loading modules, keeping
track of module status, querying interface and all those things… It does not
by itself provide any module-specific actions.

input

An input gatheres messages (events) from external sources. Current typical
examples are UDP or TCP based syslog. However, there is no architectural limit,
so in the long term an input module may also gather SNMP traps or file lines.
Please note that an input does not necessarily parse the obtained event by
itself – this may be delegated to a parser module (this whole thing still needs
to be thought out).

output

An output module receives strings from the engine and writes them to some
ultimate destination. Popluar examples are files, databases or remote syslog
servers.

action

The action object is the "engine wrapper" around an output module. It
provides numerous servies to the output. Most importantly, it provides the core
plumbing behind restarting and queueing actions.

function

A function object (and lodable module) provides extensibility for internal
processing. Version 3.0 will support programming-like functions, which replace
and extend the property replacer options. For example, we may want to extract
characters 5 to 10 and convert them to lower case. With current rsyslog, this
works as follows: %msg:5:10:lower%. With Version 3, it will look much nicer (at
least I hope so): lower(substr(%msg, 5, 10)). The exact sytax and semantics of
how this is used in the config file is under development – but I think you can
get the idea from the example. The core improvement featuere-wise is that with
functions, rsyslog can very esaily be extended by just programming a small
plug-in with a new function. Do to the programming-like strucuture, the new
function can be combined with all exisitng ones.

Functions will be supported everywhere a string is supported, which means
everywhere. Examples are filters, output format (templates) and file name
generation.

Message Flow

This is a brief description of how a message (an event) flows inside rsyslog.

The message text is received by the input module. The input module, possibly
with the help of a parser module uses the message text to create a msg-in memory
structure. This msg structure enters rsyslog’s main processing queue. As soon as
possible, the msg object is dequeued. Now the rule engine processes the rule set.
A rule set object contains multiple rule object, which are executed in order
until either all rules are processed or a discard action is encountered. If
there are multiple rule set objects bound to a single input module, they are
also executed in the configured order (the normal discard action will discard a
message for one rule set, but an additional rule set will  continue to
process the msg object. A special case of the discard action can be envisioned,
which discards a msg object for all bound rule sets.. Each rule object contains
filter objects and action objects. First, all filter objects are executed. That
means, their expressions are evaluated. If there are multiple filter objects,
their result is combined in a AND operation (other modes are not supported –
that could be easily done by crafting a specific filter expression, so we do not
encourage an additional set of complexity be allowing additional boolean
operators when multiple filter objects are used inside a single rule). If the
outcome of the overall filter object evaluation results in true ("to be
processed"), all action objects are called. The are called in the order of their
appearance in the config file (no exceptions here). The msg object is used to
generate that string required by the action (note that the msg object itself is
NOT passed to the action, this is a security and encapsulation boundary). For
string generation, function plug-ins may posibly be called (this is also the
case during filter procesing). The resulting strings are  passed to the
execute method of the action object. That object decides if queing,
rate-limiting or other functionality generically available to all actions is the
be carried out. All of this is done by the action object itself. Finally, the
strings are passed from the action object to the actual output object (a plug-in).
The output objct takes the strings and performs whatever processing needs to be
done. After all actions, rules and rule sets have been processed (or when a
discard action occurs), the msg object is destroyed. Please note that even than
a copy may be held in memory, because that might be needed for duplicate message
reduction and similiar features. Thus, msg is reference-counted and actually
only destroyed when the count reaches zero.

Please note that there are a number of utility objects involved. For clarify,
these have been omitted. Also, all function calls return a meaningful return
state. The caller will process that state with care. In some cases, however,
this may mean ignore a failed call, because this is the most appropriate thing
to do (e.g. when an action fails – if we’d abort processing the msg object, we’d
do much more harm).

Data flow

This is a brief and not so accurate picture of the data flow. It concentrates
on the role of plug-ins.

input module(parser) -> rule engine (custom functions) -> action (with
aggregated output module)

Known Open Issues with Plug-ins

The object model is not yet fully designed, so there is nothing bad about
open issues. I list them, so that the do not get lost.

Probably the number one question is how message-modifying plug-ins can be
created. I think about things like implementing syslog-sign or TLS security. It
is my current, unverified, view that we must have something like "filter-plug-ins"
which can be placed inside the message data flow to modify the message text and/or
the msg object.

Copyright © 2007 by
Rainer Gerhards

Last Updated: 2007-08-30

on the importance of plug-ins for rsyslog

Rsyslog currently offers only very rough support for plug-ins: only the MySQL plugin is available as a plugin. Even the output plug-in structure is not yet finished. So it looks like plug-is are quite unimportant to rsyslog. Right?

Wrong! Totally wrong! If there is a single feature that is absolutely critical to rsyslog, it is plug-in support. Plug-ins offer a way to provide dynamically loadable extensions of the core functionality. Provided the plug-in interface (API) is clean and well-designed, that can come without any performance hit.

Now don’t just think about plug-ins for exotic features. What if almost everything is a plug-in? Well, in that case the code loaded in memory (the footprint) can be exacty tailored to what is needed. This is most benefitial for small, embedded system with limited resources available. On the other hand, this doesn’t limit a highly capable system of offering a very rich functionality. It just loads different plug-ins.

Remember that almost all functionality can be implemented as a plugin. Inputs (E.g. UDP syslog or local domain sockets) and outputs (e.g. database output or message forwarding) make somewhat natural plugins. But plugins can also be used in filtering. For example, the (expensive) regexp functionality could be provided by a plugin. As could be different message parsers.

This is exactly the way rsyslog is heading: we will try to provide an ultry-slim framework which offers just the basic things needed to orchestrate the plug-ins. Most of the functionality will indeed be available via plug-ins, dynamically loaded as needed.

I am not yet sure when we will reach his goal. But the object model design and the overall design direction heads into this area. With that design philosophy, we can make rsyslog really universally available, even on low-powered devices (loading just a few plug-ins). At the high end, systems with a lot of plug-ins loaded will be able to handle the most demanding tasks.

And, of course, plug-ins will hopefully not only be provided by the rsyslog project itself. It is our sincere hope that others will also begin to contribute functionality in the form of plug-ins. To facilitate that, we strive to create very simple plug-in interfaces. For example, all threading details will be handled by the core engine itself and plug-ins will be able to think they are running on a single thread. The core engine will handle the proper sync operations. Of course, plug-ins in need to use themselves a sophisticated threading model can do so – but it is not a requirement. Hopefully, that’ll make it very easy to create plug-ins and thus be very easy to contribute extended functionality for rsyslog. That, we hope, will help create a lively community and thus a breakthrough syslog project.

on the rsyslog config file format…

A strength of rsyslog is that it support stock syslogd’s config file format. One of its weaknesses, however, is that it support stock syslogd’d config file format.

Sound strange? Jepp – but it isn’t. Understanding the old config format is great when it comes to replacing stock syslogd. It’s easy for package maintainers and it is also easy for users (who do not necessarily need to learn anything new). However, that format is clumsy, especially when compared to syslog-ng. So there is already a lot of criticism for supporting that format.

To make matters worse, rsyslog’s enhanced functionality requires some enhanced configuration directives. They have evolved as rsyslog has evolved. Currently, they are only somewhat ugly. But the more the project evolves, the more ugly they will become.

In short words: I do not like the current config file format.
But on the other hand, I also do not like spending much time “just” on creating another config file parser. And I do not like the learning curve associated with it.

Seth Vidal, some weeks ago, recommended to have a directive in the config file specifying whether it is old-style or new-style. I’ll probably follow this route. That would enable us to keep backwards compatible and allow users to re-use their knowledge. In “old format mode”, features would be limited by the file format (and the users’ ability to deal with it). The full glory would only be available in “new format mode”. That sounds just fair, especially as users need to learn the new functionality and then it does not really matter if the need to learn a new conf format while they go along.

OK, that seems to be (somewhat solved).

But what format should be the new style format? Seth Vidal recommended a natural language like format (see his post on the rsyslog mailing list). However, there are many things unanswered. We don’t just have filters, we have many things.

Let’s go to the root question: what is a config file good for? In my personal view, it should

  • enable the user to specify what the product should do in an easy and simple to follow way
  • allow the application to create internal control structures that specify how the application works

Both are equally important. But the second one tells us the at least part of the config file structure is dictated by the applications object design (or call it [mnodular] structure).

So I think to do the config file right, one first needs to know the application’s object model. For rsyslog, this is not yet published. Even further: it is not yet fully designed. The 1.x versions, as well as part of the 2.x version does not have a real object design (but 2.x has at least a partial one and is somewhat like an interim release on a way to the full model).

As a side-note, this is also the reason stock syslogd and early rsyslog works with such a simple config file: it is a monolithic application and such a one is served perfectly by an equally-monolithic config file. I intend to publish a full object model for rsyslog 3.0 in the fall/winter 2007 time frame. Then, we can look at the specifics of the config file.

Now back to the number one requirement for a config file: user friendliness. We know we need something that is capable to work with a complex object model. But how to phrase this?

I currently see four choices:

  1. a pure natural-language look-alike like suggested by Seth Vidal (actually more a programming like type
  2. a purely XML-based file
  3. something like the apache config
  4. something close to the way syslog-ng does things

I have to admit I am sceptic for a pure #1 approach. Natural language is intuitive for filter conditions, but it looks probably somewhat funny with most other object (which have a large number of properties). With pure XML, it is quite the opposite. It is very well with most objects, but a filter tree in XML is just plain ugly. So the most tempting choices for me are either something apache- or syslog-ng-like.

I have some mental problem with picking up the syslog-ng format, it just sound right to me. But this can be overcome. The question is if we get us into trouble when we extend the syslog-ng format and syslog-ng does a similar thing. That can become quite ugly.

An apache like format also has its drawbacks. I am not sure yet if inheritance will work well in a syslogd (but, hey, isn’t that what we currently already have?). But it sounds like a good choice. Is that something that we should model to see if any weaknesses or trouble spots occur?

Well… I can’t answer. What do you, our users, think? I would really appreciate feedback on possible config file format. I have set up a wiki page for suggestions. I would really appreciate if users could post what they would find a useful config file format.

When the object model is ready, we as the community at whole can then decide what the best possible config file format would be. If we are lucky, we’ll have a clear, easy-to-read config file format that matches the object model by winter 2007.

on rsyslog versions

What I said about rsyslog versions these days may sound a bit strange. I am talking about 3.x, but yet we are only at 1.x. Do I intend to bump version numbers just for the fun of it. No! But the schema I originally had in my mind has proven to be infective. Initially, minor versions starting from .10 were reserved for devel builds, while anything below was reserved for stable ones. Consequently, we have a stable 1.0.5 right now and a devel of 1.19.0. However, the 1.19.0 is a very far departure from 1.0.5.

So I now have decided that the 1.x devel series will become 2.x stable. In fall/winter, I have a number of very large changes for rsyslog on my mind. These changes will be so considerate that the end result can not be a 2.0 version. This time I want to make this clear from the beginning. As such, the new devel series will actually start at 3.x.

So hopefully this all will make sense now: I’ll continue a bit to use the 1.19 (or higher) series for things that will become the next stable release). Around September/October, it will actually be released as 2.0.0 stable (and then receive mostly fixes). As soon as this is done, development will immediately continue with 3.x, which will be the release with new object model, enhanced threading, more plug-ins and all that…

I hope that clarifies now – and makes at least some sense to you.

rsyslog changes for 2007-08-14

Do you remember? I promised to make no more major changes to rsyslog until around September. Among the things I did not intend to do was a plug-in interface. And, yes, I did not do that. But varmojfekoj, a frequent contributor, did it ;)

As varmojfekoj says himself, this is not a full-blown plugin implementation. But he has converted the MySQL output module into a loadable plugin. The current output module interface API has some restrictions, so it is not 100% clean – but by far clean enough to be used in practice.

The big advantage of having this plug-in is that package maintainers now can create two packages for rsyslog: one for the base system and another one for the mysql functionality. This removes a lot of problems. For example, when rsyslog was compiled with MySQL support, it would have required the MySQL client to be present. This would not be acceptable for a default syslogd (after all, each system would need to have MySQL client installed…) – clearly unacceptable. Now the base (default) system can be supplied without MySQL (which is no longer tied in). And those who desired database logging, can simply add the MySQL plug-in add-on package. That package will of course pull the MySQL client, but that’s fine if you would actually like to use it (sounds only fair, doesn’t it?).

OK, finally, here is my (small) work log:

– integrated patch from varmojfekoj to make the mysql module a loadable
one
many thanks for the patch, MUCH appreciated
– added some code to support the forward-compatibilty directive
$ModLoad MySQL – this is now internally translated to the right name
Needs to be revisited, but is clean enough for now.