summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorRainer Gerhards <rgerhards@adiscon.com>2007-06-18 10:04:23 +0000
committerRainer Gerhards <rgerhards@adiscon.com>2007-06-18 10:04:23 +0000
commitdfe12b03eb40535d3393239d9acac155c82ab8f6 (patch)
treebb978ad3992dbed1ab77777000d24246ec686af0 /doc
parente58ff8a7a07fb042a4e5b5eae7c671199a2d677b (diff)
downloadrsyslog-dfe12b03eb40535d3393239d9acac155c82ab8f6.tar.gz
rsyslog-dfe12b03eb40535d3393239d9acac155c82ab8f6.tar.xz
rsyslog-dfe12b03eb40535d3393239d9acac155c82ab8f6.zip
added new document on recording syslog priority to log files
Diffstat (limited to 'doc')
-rw-r--r--doc/manual.html108
-rw-r--r--doc/property_replacer.html15
-rw-r--r--doc/rsyslog_recording_pri.html134
3 files changed, 201 insertions, 56 deletions
diff --git a/doc/manual.html b/doc/manual.html
index 8e15cc91..f3bb40cb 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -1,54 +1,54 @@
-<html>
-<head>
-<title>rsyslog documentation</title>
-</head>
-<body>
-<h1>RSyslog - Documentation</h1>
-<p><b><a href="http://www.rsyslog.com/">Rsyslog</a> is an enhanced syslogd
-supporting, among others, <a href="rsyslog_mysql.html">MySQL</a>, syslog/tcp,
-fine grain output format control, and the ability to filter on any message part.</b>
-It is quite compatible to stock
-sysklogd and can be used as a drop-in replacement. Its <a href="features.html">
-advanced features</a> make it suitable for enterprise-class,
-<a href="rsyslog_stunnel.html">encryption protected syslog</a>
-relay chains while at the same time being very easy to setup
-for the novice user.</p>
-<p>Visit the <a href="status.html">rsyslog status page</a> to obtain current
-version information and ports. <b>If you like rsyslog, you might want to lend us
-a helping hand. </b>It doesn't require a lot of time - even a single mouse click
-helps. Learn <a href="how2help.html">how to help the rsyslog project</a>.</p>
-<p><b>Follow the links below for the</b></p>
-<ul>
-<li><a href="rsyslogd.man.txt">rsyslogd man page</a>
-<li><a href="rsyslog_conf.html">configuration file syntax (rsyslog.conf)</a>
-<li>a commented <a href="sample.conf.html">sample rsyslog.conf</a>
-<li><a href="bugs.html">rsyslog bug list</a><li><a href="rsyslog_packages.html"> rsyslog packages</a><li><a href="generic_design.html">backgrounder on generic syslog application design</a></ul>
-<p><b>We have some in-depth papers on</b></p>
-<ul>
- <li><a href="install.html">installing rsyslog</a></li>
- <li><a href="rsyslog_stunnel.html">ssl-encrypting syslog with stunnel</a></li>
- <li><a href="rsyslog_mysql.html">writing syslog messages to MySQL</a></li>
- <li><a href="rsyslog_php_syslog_ng.html">using php-syslog-ng with rsyslog</a></li>
-</ul>
-<p>Also, there is an article from Dennis Olvany on
-<a href="rsyslog084-freebsd5.4.txt">Syslog-to-SQL with rsyslog-0.8.4 on FreeBSD 5.4</a>
-(which unfortunately is a bit outdated now). Thanks to Ozgur Karatas, we also have a <a href="http://www.rsyslog.com/index.php?module=Static_Docs&func=view&f=/turkish-install-1.0.1.pdf">turkish install howto</a> (online-only, based on the 1.0.1 release).</p>
-<p>Our <a href="history.html">rsyslog history</a> page is for you if you would like to learn a little more
-on why there is an rsyslog at all.</p>
-<p>Documentation is added continously. Please note that the documentation here
-matches only the current version of rsyslog. If you use an older version, be sure
-to use the doc that came with it.</p>
-<p><b>You can also browse the following online ressources:</b></p>
-<ul>
-<li><a href="http://www.rsyslog.com/module-Static_Docs-view-f-manual.html.phtml">rsyslog online documentation</a></li>
-<li><a href="http://www.rsyslog.com/Topic3.phtml">rsyslog FAQ</a></li>
-<li><a href="http://www.rsyslog.com/PNphpBB2.phtml">rsyslog discussion forum</a></li>
-<li><a href="http://www.rsyslog.com/Topic4.phtml">rsyslog change log</a></li>
-<li><a href="http://www.monitorware.com/en/syslog-enabled-products/">syslog device configuration guide</a> (off-site)</li>
-</ul>
-<p>And don't forget about the <a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a>.
-If you are interested in the &quot;backstage&quot;, you may find
-<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer</a>'s
-<a href="http://rgerhards.blogspot.com/">syslog blog</a> an interesting read.</p>
-</body>
-</html>
+<html>
+<head>
+<title>rsyslog documentation</title>
+</head>
+<body>
+<h1>RSyslog - Documentation</h1>
+<p><b><a href="http://www.rsyslog.com/">Rsyslog</a> is an enhanced syslogd
+supporting, among others, <a href="rsyslog_mysql.html">MySQL</a>, syslog/tcp,
+fine grain output format control, and the ability to filter on any message part.</b>
+It is quite compatible to stock
+sysklogd and can be used as a drop-in replacement. Its <a href="features.html">
+advanced features</a> make it suitable for enterprise-class,
+<a href="rsyslog_stunnel.html">encryption protected syslog</a>
+relay chains while at the same time being very easy to setup
+for the novice user.</p>
+<p>Visit the <a href="status.html">rsyslog status page</a> to obtain current
+version information and ports. <b>If you like rsyslog, you might want to lend us
+a helping hand. </b>It doesn't require a lot of time - even a single mouse click
+helps. Learn <a href="how2help.html">how to help the rsyslog project</a>.</p>
+<p><b>Follow the links below for the</b></p>
+<ul>
+<li><a href="rsyslogd.man.txt">rsyslogd man page</a>
+<li><a href="rsyslog_conf.html">configuration file syntax (rsyslog.conf)</a>
+<li>a commented <a href="sample.conf.html">sample rsyslog.conf</a>
+<li><a href="bugs.html">rsyslog bug list</a><li><a href="rsyslog_packages.html"> rsyslog packages</a><li><a href="generic_design.html">backgrounder on generic syslog application design</a></ul>
+<p><b>We have some in-depth papers on</b></p>
+<ul>
+ <li><a href="install.html">installing rsyslog</a></li>
+ <li><a href="rsyslog_stunnel.html">ssl-encrypting syslog with stunnel</a></li>
+ <li><a href="rsyslog_mysql.html">writing syslog messages to MySQL</a></li>
+ <li><a href="rsyslog_php_syslog_ng.html">using php-syslog-ng with rsyslog</a></li> <li><a href="rsyslog_recording_pri.html">recording the syslog priority (severity and facility) to the log file</a></li>
+</ul>
+<p>Also, there is an article from Dennis Olvany on
+<a href="rsyslog084-freebsd5.4.txt">Syslog-to-SQL with rsyslog-0.8.4 on FreeBSD 5.4</a>
+(which unfortunately is a bit outdated now). Thanks to Ozgur Karatas, we also have a <a href="http://www.rsyslog.com/index.php?module=Static_Docs&func=view&f=/turkish-install-1.0.1.pdf">turkish install howto</a> (online-only, based on the 1.0.1 release).</p>
+<p>Our <a href="history.html">rsyslog history</a> page is for you if you would like to learn a little more
+on why there is an rsyslog at all.</p>
+<p>Documentation is added continously. Please note that the documentation here
+matches only the current version of rsyslog. If you use an older version, be sure
+to use the doc that came with it.</p>
+<p><b>You can also browse the following online ressources:</b></p>
+<ul>
+<li><a href="http://www.rsyslog.com/module-Static_Docs-view-f-manual.html.phtml">rsyslog online documentation</a></li>
+<li><a href="http://www.rsyslog.com/Topic3.phtml">rsyslog FAQ</a></li>
+<li><a href="http://www.rsyslog.com/PNphpBB2.phtml">rsyslog discussion forum</a></li>
+<li><a href="http://www.rsyslog.com/Topic4.phtml">rsyslog change log</a></li>
+<li><a href="http://www.monitorware.com/en/syslog-enabled-products/">syslog device configuration guide</a> (off-site)</li>
+</ul>
+<p>And don't forget about the <a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a>.
+If you are interested in the &quot;backstage&quot;, you may find
+<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer</a>'s
+<a href="http://rgerhards.blogspot.com/">syslog blog</a> an interesting read.</p>
+</body>
+</html>
diff --git a/doc/property_replacer.html b/doc/property_replacer.html
index a6618616..9bd77cec 100644
--- a/doc/property_replacer.html
+++ b/doc/property_replacer.html
@@ -36,8 +36,12 @@ BSD syslogd. For example, when TAG is "named[12345]", programname is "named".</t
to a <a href="http://www.monitorware.com">MonitorWare</a> backend (also for
<a href="http://www.phplogcon.org/">phpLogCon</a>)</td></tr>
<tr><td><b>syslogfacility</b></td><td>the facility from the message - in numerical form</td></tr>
-<tr><td><b>syslogpriority</b></td><td>the priority (actully severity!) from the
- message - in numerical form</td></tr>
+<tr>
+ <td><b>syslogseverity</b></td><td>severity from the
+ message - in numerical form</td>
+</tr>
+<tr><td><b>syslogpriority</b></td><td>an alis for syslogseverity - included for
+ historical reasons (be careful: it still is the severity, not PRI!)</td></tr>
<tr><td><b>timegenerated</b></td><td>timestamp when the message was RECEIVED. Always in
high resolution</td></tr>
<tr><td><b>timereported</b></td><td>timestamp from the message. Resolution depends on
@@ -106,5 +110,12 @@ are defined:</p>
replacement character like space.</td></tr>
</table>
+<h2>Further Links</h2>
+<ul>
+ <li>Article on &quot;<a href="rsyslog_recording_pri.html">Recording the Priority of
+ Syslog Messages</a>&quot; (describes use of templates to record severity and
+ facility of a message)</li>
+</ul>
+
</body>
</html>
diff --git a/doc/rsyslog_recording_pri.html b/doc/rsyslog_recording_pri.html
new file mode 100644
index 00000000..c84d47fa
--- /dev/null
+++ b/doc/rsyslog_recording_pri.html
@@ -0,0 +1,134 @@
+<html><head>
+<title>Writing syslog Data to MySQL</title>
+<meta name="KEYWORDS" content="syslog, mysql, syslog to mysql, howto">
+</head>
+<body>
+<h1>Recording the Priority of Syslog Messages</h1>
+ <P><small><i>Written by
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
+ Gerhards</a> (2007-06-18)</i></small></P>
+<h2>Abstract</h2>
+<p><i><b>The so-called priority (PRI) is very important in syslog messages,
+because almost all filtering in syslog.conf is based on it.</b> However, many
+syslogds (including the Linux stock sysklogd) do not provide a way to record
+that value. In this article, I'll give a brief overview of how PRI can be
+written to a log file.</i></p>
+<h2>Background</h2>
+<p>The PRI value is a combination of so-called severity and facility. The
+facility indicates where the message originated from (e.g. kernel, mail
+subsystem) while the severity provides a glimpse of how important the message
+might be (e.g. error or informational). Be careful with these values: they are
+in no way consistent accross applications (especially severity). However, they
+still form the basis of most filtering in syslog.conf. For example, the
+directive (aka &quot;selector line)</p>
+<p align="center">
+<code>mail.* /var/log/mail.log</code>
+</p>
+<p>means that messages with the mail facility should be stored to
+/var/log/mail.log, no matter which severity indicator they have (that is telling
+us the asterisk). If you set up complex conditions, it can be annoying to find
+out which PRI value a specific syslog message has. Most stock syslogds do not
+provide any way to record them.</p>
+<h2>How is it done?</h2>
+<p>With <a href="http://www.rsyslog.com/">rsyslog</a>, PRI recording is simple.
+All you need is the correct template. Even if you do not use rsyslog on a regular
+basis, it might be a handy tool for finding out the priority.</p>
+<p>Rsyslog provides a flexible system to specify the output formats. It is
+template-based. A template with the traditional syslog format looks as follows:</p>
+<p align="center">
+<code>$template TraditionalFormat,&quot;%timegenerated% %HOSTNAME% %syslogtag%%msg:::drop-last-lf%\n&quot;</code>
+</p>
+<p>The part in quotes is the output formats. Things between percent-signs are
+so-called <a href="property_replacer.html">messages properties</a>. They are replaced with the respective content
+from the syslog message when output is written. Everything outside of the
+percent signs is literal text, which is simply written as specified.</p>
+<p>Thankfully, rsyslog provides message properties for the priority. These are
+called &quot;PRI&quot;, &quot;syslogfacility&quot; and &quot;syslogpriority&quot; (case is important!). They are numerical
+values. Starting with rsyslog 1.13.4, there is also a property &quot;PRI-text&quot;, which
+contains the priority in friendly text format (e.g. &quot;syslog.info&quot;). For the rest
+of this article, I assume that you run version 1.13.4 or higher.</p>
+<p>Recording the priority is now a simple matter of adding the respective field
+to the template. It now looks like this:</p>
+<p align="center">
+<code>$template TraditionalFormatWithPRI,&quot;%PRI-text%: %timegenerated% %HOSTNAME% %syslogtag%%msg:::drop-last-lf%\n&quot;</code>
+</p>
+<p>Now we have the right template - but how to write it to a file? You probably
+have a line like this in your syslog.conf:</p>
+<p align="center"><code>*.* -/var/log/messages.log</code></p>
+<p>It does not specify a template. Consequently, rsyslog uses the traditional
+format. In order to use some other format, simply specify the template after the
+semicolon:</p>
+<p align="center"><code>*.* -/var/log/messages.log;TraditionalFormatWithPRI</code></p>
+<p>That's all you need to do. There is one common pitfall: you need to define
+the template before you use it in a selector line. Otherwise, you will receive
+an error.</p>
+<p>Once you have applied the changes, you need to restart or HUP rsyslogd. It
+will then pick the new configuration.</p>
+<h2>What if I do not want rsyslogd to be the standard syslogd?</h2>
+<p>If you do not want to switch to rsyslog, you can still use it as a setup aid.
+A little bit of configuration is required.</p>
+<ol>
+ <li>Download, make and install rsyslog</li>
+ <li>copy your syslog.conf over to rsyslog.conf</li>
+ <li>add the template described above to it; select the file that should use
+ it</li>
+ <li>stop your regular syslog daemon for the time being</li>
+ <li>run rsyslogd (you may even do this interactively by calling it with the
+ -n additional option from a shell)</li>
+ <li>stop rsyslogd (press ctrl-c when running interactively)</li>
+ <li>restart your regular syslogd</li>
+</ol>
+<p>That's it - you can now review the priorities.</p>
+<h2>Some Sample Data</h2>
+<p>Below is some sample data created with the template specified above. Note the
+priority recording at the start of each line.</p>
+<p>
+<code>kern.info&lt;6&gt;: Jun 15 18:10:38 host kernel: PCI: Sharing IRQ 11 with 00:04.0<br>
+kern.info&lt;6&gt;: Jun 15 18:10:38 host kernel: PCI: Sharing IRQ 11 with 01:00.0<br>
+kern.warn&lt;4&gt;: Jun 15 18:10:38 host kernel: Yenta IRQ list 06b8, PCI irq11<br>
+kern.warn&lt;4&gt;: Jun 15 18:10:38 host kernel: Socket status: 30000006<br>
+kern.warn&lt;4&gt;: Jun 15 18:10:38 host kernel: Yenta IRQ list 06b8, PCI irq11<br>
+kern.warn&lt;4&gt;: Jun 15 18:10:38 host kernel: Socket status: 30000010<br>
+kern.info&lt;6&gt;: Jun 15 18:10:38 host kernel: cs: IO port probe 0x0c00-0x0cff: clean.<br>
+kern.info&lt;6&gt;: Jun 15 18:10:38 host kernel: cs: IO port probe 0x0100-0x04ff: excluding 0x100-0x107 0x378-0x37f 0x4d0-0x4d7<br>
+kern.info&lt;6&gt;: Jun 15 18:10:38 host kernel: cs: IO port probe 0x0a00-0x0aff: clean.<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:24 host dd: 1+0 records out<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:24 host random: Saving random seed: succeeded<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:25 host portmap: portmap shutdown succeeded<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:25 host network: Shutting down interface eth1: succeeded<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:25 host network: Shutting down loopback interface: succeeded<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:25 host pcmcia: Shutting down PCMCIA services: cardmgr<br>
+user.notice&lt;13&gt;: Jun 15 18:17:25 host /etc/hotplug/net.agent: NET unregister event not supported<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:27 host pcmcia: modules.<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:29 host rc: Stopping pcmcia: succeeded<br>
+local7.notice&lt;189&gt;: Jun 15 18:17:30 host rc: Starting killall: succeeded<br>
+syslog.info&lt;46&gt;: Jun 15 18:17:33 host [origin software=&quot;rsyslogd&quot; swVersion=&quot;1.13.3&quot; x-pid=&quot;2464&quot;] exiting on signal 15.<br>
+syslog.info&lt;46&gt;: Jun 18 10:55:47 host [origin software=&quot;rsyslogd&quot; swVersion=&quot;1.13.3&quot; x-pid=&quot;2367&quot;][x-configInfo udpReception=&quot;Yes&quot; udpPort=&quot;514&quot; tcpReception=&quot;Yes&quot; tcpPort=&quot;1470&quot;] restart<br>
+user.notice&lt;13&gt;: Jun 18 10:55:50 host rger: test<br>
+syslog.info&lt;46&gt;: Jun 18 10:55:52 host [origin software=&quot;rsyslogd&quot; swVersion=&quot;1.13.3&quot; x-pid=&quot;2367&quot;] exiting on signal 2.</code></p>
+<h2>Feedback Requested</h2>
+<P>I would appreciate feedback on this paper. If you have additional ideas,
+comments or find bugs, please
+<a href="mailto:rgerhards@adiscon.com">let me know</a>.</P>
+<h2>References and Additional Material</h2>
+<ul>
+ <li><a href="http://www.rsyslog.com">www.rsyslog.com</a> - the rsyslog site</li>
+</ul>
+<h2>Revision History</h2>
+<ul>
+ <li>2007-06-18 *
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
+ * initial version created</li>
+</ul>
+<h2>Copyright</h2>
+<p>Copyright (c) 2007
+<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
+and <a href="http://www.adiscon.com/en/">Adiscon</a>.</p>
+<p>Permission is granted to copy, distribute and/or modify this document under
+the terms of the GNU Free Documentation License, Version 1.2 or any later
+version published by the Free Software Foundation; with no Invariant Sections,
+no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be
+viewed at <a href="http://www.gnu.org/copyleft/fdl.html">
+http://www.gnu.org/copyleft/fdl.html</a>.</p>
+</body>
+</html> \ No newline at end of file