I am missing information about the imdiag module. It isn't listed in http://www.rsyslog.com/doc/v7-stable/configuration/modules.html or somewhere else or did I miss something?

As this is not currently supported by doctools, we need to check all files for such occurrences. An example is this here:

http://www.rsyslog.com/doc/newdoc/messageparser.html#what-are-message-parsers

See the start of the page. It's probably also in other places.

Best to start the process in v5-stable, but we may need to work upwards as newer docs may have additional occurrences.

See attached screenshot

The section "Encrypting Syslog Traffic with TLS (SSL)" is repeated multiple times linking to different html pages.

Under
http://www.rsyslog.com/doc/master/tutorials/tls_cert_summary.html
http://www.rsyslog.com/doc/master/tutorials/tls_cert_ca.html

I have several broken links to images.

Example:

<img alt="TLS/SSL protected syslog" src="../_images/tls_cert.jpg" />
<img alt="" src="../_images/tls_cert_100.jpg" />

Brought up by @davidelang and makes a lot of sense.

I propose that we add a new "usecases" "branch" to the documentation. It should contain descriptions of actual use cases, and most importantly provide config snippets that can simply be copy&pasted. Of course, it makes sense to populate this branch with common use cases first, but more exotic ones should also be added. In any case, the core content should be relatively brief, probably with links to more elaborate material.

The goal is to support users who just want to get a specific task done but do not want to dig too deep into rsyslog specifics.

I'll add a sample in my own fork so that we can get a better idea of what I have on my mind.

Formating in the bottom ;)

see rsyslog/rsyslog@a61f1fe

The examples are unreadable, seems they are missing the right markup to be flagged as verbatim code

file: /master/configuration/modules/omlibdbi.html

The doc looks like it is missing RainerScript description, which smells strongly like an incomplete import.

Promises a sample under "Caveats/Known Bugs" but there is no sample

See sample in the bottom

Output file syncing and the meaning of a dash in front of a log file name is not documented at all in the rsyslog.conf.5 man page; it is only documented in source/compatibility/v3compatibility.rst in the rsyslog-doc repository, where it is hard to find.

Could this please be added / moved to the rsyslog.conf.5 man page?

(I should probably have reported this against the syslog repository, sorry.)

The html doc uses textboxes for config file samples. These boxes have been converted as plain text, and so the config sample are unreadable. For an example, check the imuxsock doc, but that's unfortunately a problem all over the place.

When building the Debian package for rsyslog-doc, I get the following error message:
E: rsyslog-doc source: source-is-missing source/_static/jquery.js
E: rsyslog-doc source: source-is-missing source/_static/underscore.js
W: rsyslog-doc: embedded-javascript-library usr/share/doc/rsyslog-doc/html/_static/jquery.js
W: rsyslog-doc: embedded-javascript-library usr/share/doc/rsyslog-doc/html/_static/underscore.js

Looking at https://github.com/rsyslog/rsyslog-doc/tree/master/source/_static I don't see a good reason to ship those files in the source directory (aside from rsyslog.css, which atm is disabled in conf.py). Please consider removing those files. They are auto-generated by sphinx

Formatting in the example in the bottom is wrong

A lot of modules use outdated configuration directives, like $ModLoad.
The should use the new, preferred syntax.

This is just an example:

# grep \$ModLoad * -R
compatibility/v3compatibility.rst:  $ModLoad immark # provides --MARK-- message capability
compatibility/v3compatibility.rst:  $ModLoad imudp # provides UDP syslog reception
compatibility/v3compatibility.rst:  $ModLoad imtcp # provides TCP syslog reception
compatibility/v3compatibility.rst:  $ModLoad imgssapi # provides GSSAPI syslog reception
compatibility/v3compatibility.rst:  $ModLoad imuxsock # provides support for local system logging (e.g. via logger command)
compatibility/v3compatibility.rst:  $ModLoad imklog # provides kernel logging support (previously done by rklogd)
compatibility/v3compatibility.rst:  $ModLoad immark
compatibility/v3compatibility.rst:  $ModLoad imudp
compatibility/v3compatibility.rst:  $ModLoad imudp
compatibility/v3compatibility.rst:  $ModLoad imklog
compatibility/v3compatibility.rst:statements to the top of your rsyslog.conf (but after the $ModLoad's!) -
concepts/messageparser.rst:can be loaded via $ModLoad just like any other loadable module. It is
configuration/ruleset/rsconf1_rulesetcreatemainqueue.rst:  $ModLoad imtcp
configuration/ruleset/rsconf1_rulesetparser.rst:-  load your custom parsers via $ModLoad
configuration/ruleset/rsconf1_rulesetparser.rst:$ModLoad imudp $ModLoad pmdevice1 # load parser "device1.parser" for
configuration/ruleset/rsconf1_rulesetparser.rst:device 1 $ModLoad pmdevice2 # load parser "device2.parser" for device 2
configuration/global/options/rsconf1_modload.rst:$ModLoad
configuration/global/options/rsconf1_modload.rst:``$ModLoad ommysql # load MySQL functionality $ModLoad /rsyslog/modules/ompgsql.so # load the postgres module via absolute path``
configuration/rsyslog-example.conf:# $ModLoad - Dynamically loads a plug-in and activates it
configuration/rsyslog-example.conf:$ModLoad ommysql  # load MySQL functionality
configuration/rsyslog-example.conf:$ModLoad /rsyslog/modules/somemodule.so # load a module via absolute path
configuration/modules/ommail.rst:  $ModLoad ommail
configuration/modules/ommail.rst:  $ModLoad ommail
configuration/modules/omrelp.rst:  $ModLoad omrelp
configuration/modules/mmnormalize.rst:$ModLoad mmnormalize $mmnormalizeRuleBase /path/to/rulebase.rb \*.\*
configuration/modules/omsnmp.rst:   $ModLoad omsnmp
configuration/modules/imptcp.rst:  $ModLoad imptcp # needs to be done just once 
configuration/modules/omlibdbi.rst:$ModLoad omlibdbi $ActionLibdbiDriver mysql $ActionLibdbiHost
configuration/modules/omhdfs.rst:  $ModLoad omhdfs $OMHDFSFileName /var/log/logfile \*.\* :omhdfs:
configuration/modules/imfile.rst:  $ModLoad imfile # needs to be done just once 
configuration/modules/imtcp.rst:  $ModLoad imtcp # needs to be done just once
configuration/modules/omfwd.rst:  $ModLoad omfwd
configuration/modules/gssapi.rst:-  $ModLoad omgssapi - load output gss module
configuration/modules/gssapi.rst:-  $ModLoad `imgssapi <imgssapi.html>`_ - load input gss module
configuration/modules/omuxsock.rst:  $ModLoad omucsock
configuration/modules/mmsnmptrapd.rst:$ModLoad mmsnmptrapd # needs to be done just once # ... other module
configuration/modules/ommysql.rst:$ModLoad ommysql $ActionOmmysqlServerPort 1234 # use non-standard port
configuration/modules/omoracle.rst:            $ModLoad omoracle
configuration/modules/imgssapi.rst:  $ModLoad imgssapi # needs to be done just once
configuration/modules/imrelp.rst:  $ModLoad imrelp # needs to be done just once
configuration/modules/imsolaris.rst:  $ModLoad imsolaris
configuration/modules/pmlastmsg.rst:$ModLoad pmlastmsg # this parser is NOT a built-in module # note that
configuration/modules/omudpspoof.rst:$ModLoad omudpspoof $ActionOMUDPSpoofTargetHost server.example.com
configuration/modules/omudpspoof.rst:$ModLoad omudpspoof $template spoofaddr,"192.0.2.1" $template
configuration/modules/omudpspoof.rst:$ModLoad omudpspoof $template spoofaddr,"192.0.2.1"
configuration/modules/im3195.rst:  $ModLoad im3195 $Input3195ListenPort 1601
configuration/modules/index.rst:been loaded (using $ModLoad).
configuration/modules/imklog.rst:  $ModLoad imklog
configuration/modules/imudp.rst:   $ModLoad imudp # needs to be done just once
configuration/modules/impstats.rst:  $ModLoad impstats
configuration/modules/omruleset.rst:$ModLoad omruleset # define ruleset for commonly written file $RuleSet
configuration/modules/omruleset.rst:$ModLoad omruleset # define "second" ruleset $RuleSet nested
configuration/modules/imuxsock.rst:  $ModLoad imuxsock # needs to be done just once
configuration/modules/imuxsock.rst:  $ModLoad imuxsock # needs to be done just once
configuration/modules/imuxsock.rst:  $ModLoad imuxsock # needs to be done just once
configuration/modules/imuxsock.rst:  $ModLoad imuxsock # needs to be done just once
configuration/modules/imuxsock.rst:  $ModLoad imuxsock # needs to be done just once
configuration/modules/mmjsonparse.rst:$ModLoad mmjsonparse \*.\* :mmjsonparse:
configuration/modules/imkmsg.rst:$ModLoad imkmsg
configuration/actions.rst:  $ModLoad ommysql
installation/install_from_source.rst: $ModLoad immark # provides --MARK-- message capability
installation/install_from_source.rst: $ModLoad imudp # provides UDP syslog reception
installation/install_from_source.rst: $ModLoad imtcp # provides TCP syslog reception
installation/install_from_source.rst: $ModLoad imuxsock # provides support for local system logging
installation/install_from_source.rst: $ModLoad imklog # provides kernel logging support
tutorials/tls_cert_udp_relay.rst:    $ModLoad imudp    # load UDP server plugin
tutorials/database.rst:    ``$ModLoad ommysql``
tutorials/database.rst:    ``$ModLoad ompgsql``
tutorials/tls.rst:        $ModLoad imtcp # load TCP listener
tutorials/high_database_rate.rst:$ModLoad ommysql # load the output driver (use ompgsql for PostgreSQL)
tutorials/high_database_rate.rst:$ModLoad imudp # network reception $UDPServerRun 514 # start a udp
tutorials/high_database_rate.rst:server at port 514 $ModLoad imuxsock # local message reception
tutorials/high_database_rate.rst:$ModLoad ommysql # load the output driver (use ompgsql for PostgreSQL)
tutorials/high_database_rate.rst:$ModLoad imudp # network reception $UDPServerRun 514 # start a udp
tutorials/high_database_rate.rst:server at port 514 $ModLoad imuxsock # local message reception
tutorials/tls_cert_server.rst:    $ModLoad imuxsock # local messages
tutorials/tls_cert_server.rst:    $ModLoad imtcp # TCP listener
tutorials/reliable_forwarding.rst:$ModLoad imuxsock # local message reception $WorkDirectory /rsyslog/work
tutorials/reliable_forwarding.rst:$ModLoad imuxsock # local message reception $WorkDirectory /rsyslog/work

I would love to see the doc integrated into the rsyslog.com site, and have it look like a natural / "normal" page on the site. This obviously needs some fiddeling. I have experimentally uploaded the current content as is to here:

http://www.rsyslog.com/doc/newdoc/index.html

Obviously, the doc has lost much of its appeal. The question is if we can get this somehow integrated into the site or if we need to find some alternative. Again, I'd prefer integration.

There are quite a bit of errors during Sphix-build.

http://www.rsyslog.com/doc/v5-stable/whitepapers/rsyslog_ng_comparison.html
http://www.rsyslog.com/doc/v5-stable/compatibility/v3compatibility.html
http://www.rsyslog.com/doc/v5-stable/bugs.html

A formal definition of the RainerScript syntax will aid in generating valid rsyslog configurations. Any format is acceptable and ABNF is not required.

See attached screenshot

After loading the documentation, the drop-down list is broken, the doc menu items are invisible. Might be a CSS issue.

at least in template.rst

As I'd like to discuss this on github (and archive here), I think I use an issue (even though it's not really one ;)).

I notice that we have enabled the wiki on github. Does it really make sense to do that? I see that we need to have some instructions to go with the documentation itself (kind of "meta-doc" for the doc project). I see four places where it could reside:

• github wiki
• rsyslog wiki
• README-type of files
• regular doc files

I tend to think that regular doc files would be best, so that the "how to document" part becomes part of the doc itself -- maybe in it's own subdirectory.

There are conflicts when merging v5-stable into v7-stable. These should be fixed ASAP as they prevent using proper workflow.

http://www.rsyslog.com/doc/master/configuration/modules/omruleset.html references
http://www.rsyslog.com/doc/master/configuration/modules/rainerscript_call.html but this symlink is broken.

See http://www.gossamer-threads.com/lists/rsyslog/users/13915

Hi,

It would be nice to create an asset directory/hierarchy to hold all images, javascript, stylesheets... this would make the main hierarchy much cleaner

Keep it on
Bests

I guess this needs input from Rainer, but I consider the tutorial about encryption using stunnel outdated / obsolete and would suggest that it is removed.
Rsyslog has much better encryption facilities builtin nowadays like e.g. described in
http://www.rsyslog.com/doc/master/tutorials/tls_cert_summary.html

JSON is trendy.
There is more chance that people have heard about JSON than rsyslog.

After some digging I found some json-features in rsyslog.
This is cool, because it allows rsyslog to be used as a scalable service bus, which passes json to listeners based on certain criteria.

In the documentation I cannot really find it easily..so a quick google will probably point people to:

http://blog.gerhards.net/2012/03/json-and-rsyslog-templates.html

How about making a section with the title 'passing json to rsyslog' ?
I think it would be smart marketingwise and good to promote popular formats supported by rsyslog.

We need a new TOC structue that is easy to follow and appealing to beginners. @radu-gheorghe already made a suggestion, which I have put into the repo:

https://github.com/rsyslog/rsyslog-doc/blob/master/proposed-toc

We should work on that proposal in order to get closer to a final version. Alternatively, we can implement it and make changes as we go along. Comments and feedback both on the process as well as the actual TOC are appreciated. If no comments occur, we probably go ahead and begin to implement the propsal.

With commit 5de8140 a new template for module descriptions was implemented/suggested. I like this template, but I think that "module directives" and "input directives" are not proper terms. IMHO these are "parameters". "Directive" to me has a somewhat more active co-notation. Whereas in v7+, these are just "parameters" provided to the module() and input() objects.

In regard to the legacy stuff (later on the pages), I think "directive" is the correct term to use. So I would like to have a quick discussion which term is more understandable to users and make sure we settle on one set of terms and document this term usage so that it will be consistent throughout the doc (in general, adding a "howto write the doc" documentation would IMHO also be a valuable part of the new doc).

The current structure looks like a good start, but it needs improvement. Doc pages within a chapter are not necessarily ordered like they should be. How is the structure of the manual generated, especially how to influence the order of subdirectories and files within the directory?

The immark module is not yet documented. When you start with the new syntax you have to read the source code to find the Interval parameter.

In section "Sponsors and Community" [0] there is

If you are upgrading from rsyslog v2 or stock sysklogd, be sure to read the rsyslog v3 compatibility
notes, and if you are upgrading from v3, read the rsyslog v4 compatibility notes and if you upgrade 
from v4, read the rsyslog v5 compatibility notes.

Not only is this list incomplete (see #44), I also think it doesn't belong into this section and rather under "Compatibility" [1]

[0] http://www.rsyslog.com/doc/master/#sponsors-and-community
[1] http://www.rsyslog.com/doc/master/#compatibility

Right now, there no longer is a v7-devel version of rsyslog and it is unlikely that we will get one again (usually we have only one devel version, with that being that most current one --> master --> v8-devel).

So we need to merge v7-devel into v7-stable and

git rm -b v7-devel

Should v7-devel be required again for whatever reasons, we can re-create the branch. That's exactly what I do with rsyslog's program source tree.

The links to internal pages and external resources look strange and are not clickable. Is this a html import problem? In any case, we should get proper hypertext again, where the link text is clickable and can be different from the anchor (following the "how to author great hypertext" guidelines).

This page looks pretty much outdated to me.
This should be updated or removed. Maybe the update could be automated by using the git history?

http://www.rsyslog.com/doc/v8-devel/configuration/global/options/rsconf1_repeatedmsgreduction.html

I think this defaults to off, but the page doesn't make that clear.

This is really something that breaks a lot of log processing and so should be discouraged

first, it would help to have a sample showing several logs, then the same thing with this turned on. One thing is that I believe the behaviour changed over versions. In very old versions the message logged was just "last message repeated N times", but I believe around version 4 or so it changed to include the message after this so you could tell what message was repeated.

then there should be a blurb saying that while turning this on can save some space in logs, most log analysis tools need to see the repeated messages, they can't handle the "last message repeated" format. This is a feature that worked decades ago when logs were small and reviewed by a human, it fails badly on high volume logs processed by tools.

The chosen theme at http://www.rsyslog.com/doc/master/ doesn't really match the look of the main rsyslog website especially the fonts and colors should be adjusted

The compatibility page is incomplete.
The rsyslog git repository ships the following files

doc/v3compatibility.html
doc/v4compatibility.html
doc/v5compatibility.html
doc/v6compatibility.html
doc/v7compatibility.html
doc/v8compatibility.html

... to match upcoming release

A user report I received on the web site below. I think it is related to the doc generation process:

I'm not sure if I'm directing this to the right place, but I couldn't find anything for feedback about the web site and this seemed like the best option to send to.

I was looking at the documentation on http://www.rsyslog.com, and got an error trying to follow a link. I was at this page - http://www.rsyslog.com/doc/v7-stable/configuration/modules.html#id2 and I tried to follow the link for omfile under Output Modules (http://www.rsyslog.com/doc/v7-stable/configuration/omfile.html), but I get the error "Invalid file specified". I tried omfwd, omjournal, ompipe, and omusrmsg, and they all get the same error. I also tried imfile under Input Modules, but I get the same error.

I'm on Windows 7, using a Chrome browser. I've tried it under Internet Explorer as well, but get the same results.

I do like the new look, it just appears that you have a hiccup here to fix.

We need to define a standard way of describing a parameter. This is already inconsistent in the the original html doc and was on the "this needs to be fixed" list there as well.

IMHO, each parameter needs to have

• parameter name
• type (string, number, boolean, ...)
• mandatory yes/no
• available in which versions
• longer description

All of this should of course come in a consistent formatting (which was not the case in the html doc).

A lot of pages have a broken "back" hyperlink, e.g.
http://www.rsyslog.com/doc/master/configuration/modules/omfile.html
It not only looks odd, but it also points to a non-existing file and you get "
Invalid file specified"

Promises Configuration Parameters....