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
|
<html>
<head>
<title>rsyslog.conf file</title>
</head>
<body>
<a href="rsyslog_conf_global.html">back</a>
<h2>$GenerateConfigGraph</h2>
<p><b>Type:</b> global configuration directive</p>
<p><b>Default:</b> </p>
<p><b>Available Since:</b> 4.3.1 <b>CURRENTLY NOT AVAILABLE</b></p>
<p><b>Description:</b></p>
<b>This directive is currently not supported. We had to disable it when we improved the
rule engine. It is considerable effort to re-enable it. On the other hand, we are about
to add a new config system, which will make yet another config graph method necessary.
As such we have decided to currently disable this functionality and re-introduce it when
the new config system has been instantiated.
</b></p>
<p>This directive permits to create (hopefully) good-looking visualizations of rsyslogd's
configuration. It does not affect rsyslog operation. If the directive is specified multiple
times, all but the last are ignored. If it is specified, a graph is created. This happens
both during a regular startup as well a config check run. It is recommended to include
this directive only for documentation purposes and remove it from a production
configuraton.
<p>The graph is not drawn by rsyslog itself. Instead, it uses the great open source tool
<a href="http://www.graphviz.org">Graphviz</a> to do the actual drawing. This has at least
two advantages:
<ul>
<li>the graph drawing support code in rsyslog is extremly slim and without overhead
<li>the user may change or further annotate the generated file, thus potentially
improving his documentation
</ul>
The drawback, of course, is that you need to run Graphviz once you have generated
the control file with rsyslog. Fortunately, the process to do so is rather easy:
<ol>
<li>add "$GenerateConfigGraph /path/to/file.dot" to rsyslog.conf (from now on, I
will call the file just file.dot). Optionally, add "$ActionName" statement
<b>in front of</b> those actions that you like to use friendly names with. If you do
this, keep the names short.
<li>run rsyslog at least once (either in regular or configuration check mode)
<li>remember to remove the $GenerateConfigGraph directive when you no longer need it (or
comment it out)
<li>change your working directory to where you place the dot file
<li>if you would like to edit the rsyslog-generated file, now is the time to do so
<li>do "dot -Tpng file.dot > file.png"
<li>remember that you can use "convert -resize 50% file.png resized.png" if
dot's output is too large (likely) or too small. Resizing can be especially useful if
you intend to get a rough overview over your configuration.
</ol>
After completing these steps, you should have a nice graph of your configuration. Details
are missing, but that is exactly the point. At the start of the graph is always (at least
in this version, could be improved) a node called "inputs" in a tripple hexagon
shape. This represents all inputs active in the system (assuming you have defined some,
what the current version does not check). Next comes the main queue. It is given in a
hexagon shape. That shape indicates that a queue is peresent and used to de-couple
the inbound from the outbound part of the graph. In technical terms, here is a
threading boundary. Action with "real" queues (other than in direct mode)
also utilize this shape. For actions, notice that a "hexagon action" creates
a deep copy of the message. As such, a "discard hexagon action" actually does
nothing, because it duplicates the message and then discards <b>the duplicate</b>.
At the end of the diagram, you always see a "discard" action. This indicates
that rsyslog discards messages which have been run through all available rules.
<p>Edges are labeled with information about when they are taken. For filters, the type of
filter, but not any specifics, are given. It is also indicated if no filter is
applied in the configuration file (by using a "*.*" selector). Edges without
labels are unconditionally taken. The actions themselfs are labeled with the name of
the output module that handles them. If provided, the name given via
"ActionName" is used instead. No further details are provided.
<p>If there is anything in red, this should draw your attention. In this case, rsyslogd
has detected something that does not look quite right. A typical example is a discard
action which is followed by some other actions in an action unit. Even though something
may be red, it can be valid - rsyslogd's graph generator does not yet check each and
every speciality, so the configuration may just cover a very uncommon case.
<p>Now let's look at some examples. The graph below was generated on a fairly standard
Fedora rsyslog.conf file. It had only the usually commented-out last forwarding action
activated:
<p align="center">
<img src="rsyslog_confgraph_std.png" alt="rsyslog configuration graph for a default fedora rsyslog.conf">
<p>This is the typical structure for a simple rsyslog configuration. There are a couple of
actions, each guarded by a filter. Messages run from top to bottom and control branches
whenever a filter evaluates to true. As there is no discard action, all messages will
run through all filters and discarded in the system default discard action right after
all configured actions.
</p>
<p>A more complex example can be seen in the next graph. This is a configuration I
created for testing the graph-creation features, so it contains a little bit of
everything. However, real-world configurations can look quite complex, too (and I
wouldn't say this one is very complex):
<p align="center">
<img src="rsyslog_confgraph_complex.png">
</p>
<p>Here, we have a user-defined discard action. You can immediately see this because
processing branches after the first "builtin-file" action. Those messages
where the filter evaluates to true for will never run through the left-hand action
branch. However, there is also a configuration error present: there are two more
actions (now shown red) after the discard action. As the message is discarded, these will
never be executed. Note that the discard branch contains no further filters. This is
because these actions are all part of the same action unit, which is guarded only by
an entry filter. The same is present a bit further down at the node labeled
"write_system_log_2". This note has one more special feature, that is label
was set via "ActionName", thus is does not have standard form (the same
happened to the node named "Forward" right at the top of the diagram.
Inside this diagram, the "Forward" node is executed asynchonously on its own
queue. All others are executed synchronously.
<p>Configuration graphs are useful for documenting a setup, but are also a great
<a href="troubleshoot.html">troubleshooting</a> resource. It is important to
remember that <b>these graphs are generated
from rsyslogd's in-memory action processing structures</b>. You can not get closer
to understanding on how rsyslog interpreted its configuration files.
So if the graph does not look
what you intended to do, there is probably something worng in rsyslog.conf.
<p>If something is not working as expected, but you do not spot the error immediately,
I recommend to generate a graph and zoom it so that you see all of it in one great picture.
You may not be able to read anything, but the structure should look good to you and
so you can zoom into those areas that draw your attention.
<p><b>Sample:</b></p>
<p><code><b>$DirOwner /path/to/graphfile-file.dot</b></code></p>
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual
index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
Copyright © 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
version 2 or higher.</font></p>
</body>
</html>
|
