How to Contribute to rsyslog?
Rsyslog is a real open source project and open to contributions. By contributing, you help improve the state of logging as well as improve your own professional profile. Contributing is easy, and there are options for everyone – you don’t need to be developer.
These are many ways to contribute to the project:
- become a rsyslog ambassador and let other people know about rsyslog and how to utilize it for best results. Help rsyslog getting backlinks, be present on Internet news sites or at meetings you attend.
- help others by offering support on
- help with the documentation; you can either contribute
- to the rsyslog doc inside the project git
- to the rsyslog project web site — just ask us for account creation
- on the rsyslog wiki
- become a bug-hunter and help with testing rsyslog development releases
- help driving the rsyslog infrastructure with its web sites, wiki’s and the like
- help creating packages
- or, obviously, help with rsyslog code development
This list is not conclusive. There for sure are many more ways to contribute and if you find one, just let us know. We are very open to new suggestions and like to try out new things.
We have also some more in-depth information on specific contribution topics available and more is upcoming. Right now, dig down into
Again, your contribution is highly appreciated, and very rewarding. Participate in the open source movement!
Contribution Policy
Rsyslog is very open to contributions and they are highly appreciated. Basically, we accept any contribution that can potentially be of use for the rsyslog community. Documentation and code contributions are especially welcome. A successful contribution should
- come under the Apache Software License (ASL) 2.0; much of rsyslog’s code already has been converted to this license, but not everything yet. So please make sure you feel OK with ASL 2.0. We generally do not like GPL contributions any longer, as this causes trouble with the long-term goal of changing to ASL.
- provide a bugfix or feature that is -at least potentially- of general interest. If it’s really just for you and so specific that nobody else will ever want it, chances are a bit lower we’ll merge (except, of course, if it is an interesting PoC).
- a bit of documentation for new features or modules would be immensely useful. While we usually merge even without that, this actually means nobody will ever know about that particular new feature (we are way behind with doing our own doc, don’t expect us to document any other work ;)).
- do not break upward compatibility; if you really need to, discuss this on the rsyslog mailing list first
- do not unnecessarily duplicate a module; while we tend to accept such contributions, the process can take much longer as we will try to merge the functionality into the alread existing module
- if you contribute a new module with some non-standard tools, do not expect that we actually try the module out. We’ll usually merge it, but will flag it as non-project-supported and name the original author as contact points. Omoracle is one example. Don’t be put off contributing such a module — they can be immensly useful to the community, we just can’t work on all of them. If things become popular, we may involve ourselfs into it (ommongodb is an example for that).
- doc contributions should not be primarily promotional for some third party. If you contribute something you have originally written for another party, it’s usualy fine to include a “orignaly appeared on” backlink, but that should be sufficient.
As usual, these are just some general rules, and most of them common knowledge in any case. In simple words it’s very hard to find a reason NOT to merge a serious contribtion.
Where to find the rsyslog source code
Rsyslog’s source is kept in git repositories. Git is a system designed to support flexible de-centralized collaboration. The rsyslog project currently provides two official repositories. These are equal peers, pick the one that you prefer to work with.
By popular request, rsyslog is available on github. We do not provide further instructions as github users already know how to work with that site (and if you don’t, be told that they have great tutorials).
We also keep a repository on Adiscon’s git server. This may also contain some arcane branches not of popular interest (like custom builds and such). You can clone this repository either via http or git protocol (with the later being much faster). URLS are:
- git://git.adiscon.com/git/rsyslog.git
- http://git.adiscon.com/git/rsyslog.git
There is also a browsable version (gitweb) available at http://git.adiscon.com/?p=rsyslog.git;a=summary. This version also offers snapshots of each commit for easy download. You can use these if you do not have git present on your system.
action.execOnlyWhenPreviousIsSuspended preciseness
The “action.execOnlyWhenPreviousIsSuspended” parameter permits to conditionally execute an action only if the previous one is suspended. When an action actually gets suspended depends on the output module implementing the action, but the general rule is that an action suspends itself if there is a problem doing it’s job (e.g. a target server is down). This setting is generally used to implement failover destinations. So let’s call actions which have this attribute set “failover actions”.
Note that many action implement transactions to improve performance. If so, usually the success or error state of the action is only available after the transaction has been comitted. At this point, the messages have already been submitted to the action and the action could not set suspension state — simply because at that point everything looked fine. So when the failover action was about to be executed, the suspended flag was not set and the action not executed. Depending on system configuration, this can lead to loss of some messages during the failover process. If this seems totally unacceptable to you, you need to make sure that the transaction is committed after each message — this permits the output to obtain the actual success state (note that with some technologies, even this is not totally possible – a prime example is plain TCP syslog protocol).
To ensure commit of each message, the queue’s maximum batch size needs to be reduced to one. This can be done via the “queue.dequeuebatchsize” parameter. Note that reducing the batch size can have severe performance impact. Unfortunately, it is impossible to to have both high performance and precise failover actions. The simple reason is that for precise failover actions we need to know the result of the commit operation, which makes it necessary to do immediate commits.
Lower Bound for Queue Sizes
The queue.size parameter permits to specify the maximum queue size in number of messages. While not technically enforced, there is a lower limit on this parameter. Setting it to very low values (roughly below 100 messages) is not supported and can lead to unpredictable results. Also, future version my automatically adjust to a safe lower bound and/or decide to fail queue startup in those cases. So if you use very low values, do so at your own risk.
Howto anonymize messages that go to specific files
Rsyslog’s mmanon module is used to anonymize data. It is important to keep in you mind that mmanon actually modifies the message. So, as stated in the module documentation, the original, non-anonymized message can no longer be obtained once mmanon has been applied (except, of course, if the message was stored to a variable before calling mmanon). Continue reading “Howto anonymize messages that go to specific files”
How to add a module global parameter
In this git commit, two new module parameters are being added to omfile. They replace some hard-coded defaults for action parameters. This commit shows
- how to add module parameters
- how to apply them as defaults to action parameters
Please be sure to note the difference between module and action parameters.
Note that the new module parameters do not modify behavior of legacy (pre-v6) config statements. This is done intentionally to prevent complication with upward compatibility of old-style config files.
This commit is intentionally minimal in order to show the most important aspects. For a proper commit, the ChangeLog as well as the module documentation need to be updated as well. An example commit for the doc parts can be found here. It is usually suggested to do both tasks in a single commit (as they obviously closely belong together).
How to obtain a specific Doc Version?
There are very many rsyslog versions out in the wild. Each of these versions have different capabilities and consequently there is also different documentation required to match an exact version.
The rsyslog site always contains documentation for the latest development version (sometimes even features that just reside in git). While chances are good that the online doc can be used to solve a specific question, this is not guaranteed. Most importantly, older versions may have quite different rsyslog.conf formats that they support. As such, folks tend to ask how they can obtain a version of the documentation that exactly matches their version.
The answer is quite straightforward: most of the doc on the site comes from rsyslog’s project doc set, and that doc set is contained in each release tarball. So if you have e.g. 5.8.10 installed and want it’s doc, simply go ahead and download the relevant tarball. The full doc is contained in the “./doc” subdirectory. It’s in HTML format, so all you need to do is to point your browser at ./doc/index.html.
In many distributions it is even simpler, as there is a package rsyslog-doc (or similarly named), which contains that exact doc folder.
librelp 1.2.0
librelp 1.2.0 [download]
This version offers support for epoll() on platforms that provide it. This provides both better performance and the ability to handle many more connections.
Version 1.2.0 – 2013-07-15
– support for epoll() added
platforms that do not support it fall back to select()
– API extension: relpEngineSetOnGenericErr
sha256sum: 5a8870fd2ae496be08d100ef8a65807311f11d6976ed37b8e0cd8024872c31e5
librelp 1.1.5
librelp 1.1.5 [download]
This is a bug-fixing release that takes care of a memory leak on connection close as well as potential misadressing on session close.
Version 1.1.5 – 2013-07-05
– bugfix: memory leak on connection close
around 60 bytes of memory were lost on each connection close at the
server side (when the client initiated a close)
– bugfix: potential misadressing on session close
This can happen if also a write was outstanding, a quite unusable
situation. In that case, already freed memory was being accessed.
sha256sum: 2322d771bd6036dd11519509177722baa36bc0e61a5d6748cbce0addf7f43243