diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2005-08-05 08:21:42 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2005-08-05 08:21:42 +0000 |
| commit | fd620ea3361d11d490e033adc24ca453a4936964 (patch) | |
| tree | a12bf8e1cd79274a56d86a0574c45e863717a773 | |
| parent | b6c5d998a8dcac443cfa80d756e6dfc0c367d64a (diff) | |
| download | rsyslog-fd620ea3361d11d490e033adc24ca453a4936964.tar.gz rsyslog-fd620ea3361d11d490e033adc24ca453a4936964.tar.xz rsyslog-fd620ea3361d11d490e033adc24ca453a4936964.zip | |
doc updates (php-syslog-ng howto)
| -rw-r--r-- | doc/manual.html | 1 | ||||
| -rw-r--r-- | doc/rsyslog_php_syslog_ng.html | 149 |
2 files changed, 150 insertions, 0 deletions
diff --git a/doc/manual.html b/doc/manual.html index 48863933..dd263cf7 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -24,6 +24,7 @@ version information and ports.</p> <ul>
<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>
diff --git a/doc/rsyslog_php_syslog_ng.html b/doc/rsyslog_php_syslog_ng.html new file mode 100644 index 00000000..b88550d7 --- /dev/null +++ b/doc/rsyslog_php_syslog_ng.html @@ -0,0 +1,149 @@ +<html><head>
+<title>Using php-syslog-ng with rsyslog</title>
+<meta name="KEYWORDS" content="syslog, php-syslog-ng, mysql, howto, rsyslog">
+</head>
+<body>
+<h1>Using php-syslog-ng with rsyslog</h1>
+ <P><small><i>Written by
+ <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
+ Gerhards</a> (2005-08-04)</i></small></P>
+<h2>Abstract</h2>
+<p><i><b>In this paper, I describe how to use
+<a href="http://www.vermeer.org/projects/php-syslog-ng">php-syslog-ng</a> with
+<a href="http://www.rsyslog.com/">rsyslogd</a>. </b> Php-syslog-ng is a
+popular web interface to syslog data. Its name stem from the fact that it
+usually picks up its data from a database created by
+<a href="http://www.balabit.com/products/syslog_ng/">syslog-ng</a> and some
+helper scripts. However, there is nothing syslog-ng specific in the database.
+With rsyslogd's high customizability, it is easy to write to a syslog-ng like
+schema. I will tell you how to do this, enabling you to use php-syslog-ng as a
+front-end for rsyslogd - or save the hassle with syslog-ng database
+configuration and simply go ahead and use rsyslogd instead.</i></p>
+<h2>Overall System Setup</h2>
+<p>The setup is pretty straightforward. Basically, php-syslog-ng's interface to
+the syslogd is the database. We use the schema that php-syslog-ng expects and
+make rsyslogd write to it in its format. Because of this, php-syslog-ng does not
+even know there is no syslog-ng present.</p>
+<h2>Setting up the system</h2>
+<p>For php-syslog-ng, you can follow its usual setup instructions. Just skip any
+steps refering to configure syslog-ng. Make sure you create the database schema
+in <a href="http://www.mysql.com/">MySQL</a>. As of this writing, the expected schema can be created via this script:</p>
+<blockquote>
+ <code>CREATE DATABASE syslog<br>
+ !<br>
+ USE syslog<br>
+ !<br>
+ CREATE TABLE logs (<br>
+ host varchar(32) default NULL,<br>
+ facility varchar(10) default NULL,<br>
+ priority varchar(10) default NULL,<br>
+ level varchar(10) default NULL,<br>
+ tag varchar(10) default NULL,<br>
+ date date default NULL,<br>
+ time time default NULL,<br>
+ program varchar(15) default NULL,<br>
+ msg text,<br>
+ seq int(10) unsigned NOT NULL auto_increment,<br>
+ PRIMARY KEY (seq),<br>
+ KEY host (host),<br>
+ KEY seq (seq),<br>
+ KEY program (program),<br>
+ KEY time (time),<br>
+ KEY date (date),<br>
+ KEY priority (priority),<br>
+ KEY facility (facility)<br>
+ ) TYPE=MyISAM;</code>
+</blockquote>
+<p>Please note that at the time you are reading this paper, the schema might have changed.
+Check for any differences. As we customize rsyslogd to the schema, it is vital
+to have the correct one. If this paper is outdated,
+<a href="mailto:rgerhards@adiscon.com">let me know</a> so that I can fix it.</p>
+<p>Once this schema is created, we simply instruct rsyslogd to store received
+data in it. I wont go into too much detail here. If you are interested in some
+more details, you might find my paper "<a href="rsyslog_mysql.html">Writing
+syslog messages to MySQL</a>" worth reading. For this article, we simply modify
+<a href="rsyslog_conf.html">rsyslog.conf </a>so that it writes to the database.
+That is easy. Just these two lines are needed:</p>
+<blockquote>
+ <code><font color="green">$template syslog-ng,"insert into logs(host, facility, priority, tag, date,
+ time, msg) values ('%HOSTNAME%', %syslogfacility%, %syslogpriority%,
+ %syslogtag%', '%timereported:::date-mysql%', '%timereported:::date-mysql%',
+ '%msg%')", SQL</font> <br>
+ <font color="red">*.* >mysql-server,syslog,user,pass;syslog-ng</font>
+ </code>
+</blockquote>
+<p>These are just <b>two</b> lines. I have color-coded them so that you see what
+belongs together (the colors have no other meaning). The green line is the
+actual SQL statement being used to take care of the syslog-ng schema. Rsyslogd
+allows you to fully control the statement sent to the database. This allows you
+to write to any database format, including your homegrown one (if you so desire).
+Please note that there is a small inefficiency in our current usage: the
+ <code><font color="green">'%timereported:::date-mysql%'</font></code>
+property is used for both the time and the date (if you wonder about what all
+these funny characters mean, see the <a href="property_replacer.html">rsyslogd
+property replacer manual</a>) . We could have extracted just the date and time
+parts of the respective properties. However, this is more complicated and also
+adds processing time to rsyslogd's processing (substrings must be extracted). So we take a full mysql-formatted timestamp and supply it to MySQL. The sql engine in turn
+discards the unneeded part. It works pretty well. As of my understanding, the
+inefficiency of discarding the unneeded part in MySQL is lower than the
+effciency gain from using the full timestamp in rsyslogd. So it is most probably
+the best solution.</p>
+<p>Please note that rsyslogd knows two different timestamp properties: one is
+timereported, used here. It is the timestamp from the message itself. Sometimes
+that is a good choice, in other cases not. It depends on your environment. The other one is the timegenerated
+property. This is the time when rsyslogd received the message. For obvious
+reasons, that timestamp is consistent, even when your devices are in multiple
+time zones or their clocks are off. However, it is not "the real thing". It's
+your choice which one you prefer. If you prefer timegenerated ... simply use it
+;)</p>
+<p>The line in red tells rsyslogd which messages to log and where to store it.
+The "*.*" selects all messages. You can use standard syslog selector line filters here if
+you do not like to see everything in your database. The ">" tells
+rsyslogd that a MySQL connection
+must be established. Then, "mysql-server" is the name or IP address of the
+server machine, "syslog" is the database name (default from the schema) and "user"
+and "pass" are the logon credentials. Use a user with low privileges, insert into the
+logs table is sufficient. "syslog-ng" is the template name and tells rsyslogd to
+use the SQL statement shown above.</p>
+<p>Once you have made the changes, all you need to do is reload (or HUP)
+rsyslogd. Then, you should see syslog messages flow into your database - and
+show up in php-syslog-ng.</p>
+<h2>Conclusion</h2>
+<P>With minumal effort, you can use php-syslog-ng together with rsyslogd. For
+those unfamiliar with syslog-ng, this configuration is probably easier to set up
+then switching to syslog-ng. For existing rsyslogd users, php-syslog-ng might be a nice
+add-on to their logging infrastructure.</P>
+<P>Please note that the <a href="http://www.monitorware.com/en/">MonitorWare family</a> (to which rsyslog belongs) also
+offers a web-interface: <a href="http://www.phplogcon.org/">phpLogCon</a>. At the time of this writing, phpLogCon's code
+is by far not as clean as I would like it to be. Also the user-interface is
+definitely not as intutive as pp-syslog-ng. From a functionality point of view,
+however, I think it already is a bit ahead. So you might
+consider using it. I have set up a <a href="http://demo.rsyslog.com/">demo server</a>.,
+You can have a peek at it
+without installing anything.</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.vermeer.org/projects/php-syslog-ng">php-syslog-ng</a></li>
+</ul>
+<h2>Revision History</h2>
+<ul>
+ <li>2005-08-04 *
+ <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) 2005
+<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 |