diff options
Diffstat (limited to 'doc/modules.html')
| -rw-r--r-- | doc/modules.html | 94 |
1 files changed, 0 insertions, 94 deletions
diff --git a/doc/modules.html b/doc/modules.html deleted file mode 100644 index 4eae6db..0000000 --- a/doc/modules.html +++ /dev/null @@ -1,94 +0,0 @@ -<html><head> -<title>Writing syslog Data to MySQL</title> -<meta name="KEYWORDS" content="syslog, mysql, syslog to mysql, howto"> -</head> -<body> -<h1>About rsyslog Modules</h1> -<P><small><i>Written by -<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> (2007-07-28)</i></small></P> -<p><font color="#FF0000"><b>This document is incomplete. The module interface is -also quite incomplete and under development. Do not currently use it!</b></font> -You may want to visit <a href="http://rgerhards.blogspot.com/">Rainer's blog</a> -to learn what's going on.</p> -<h2>Overview</h2> -<p>In theory, modules provide input and output, among other functions, in -rsyslog. In practice, modules are only utilized for output in the current -release. The module interface is not yet completed and a moving target. We do -not recommend to write a module based on the current specification. If you do, -please be prepared that future released of rsyslog will probably break your -module. </p> -<p>A goal of modularization is to provide an easy to use plug-in interface. -However, this goal is not yet reached and all modules must be statically linked.</p> -<h2>Module "generation"</h2> -<p>There is a lot of plumbing that is always the same in all modules. For -example, the interface definitions, answering function pointer queries and such. -To get rid of these laborious things, I generate most of them automatically from -a single file. This file is named module-template.h. It also contains the -current best description of the interface "specification".</p> -<p>One thing that can also be achieved with it is the capability to cope with a -rapidly changing interface specification. The module interface is evolving. -Currently, it is far from being finished. As I moved the monolithic code to -modules, I needed (and still need) to make many "non-clean" code hacks, just to -get it working. These things are now gradually being removed. However, this -requires frequent changes to the interfaces, as things move in and out while -working towards a clean interface. All the interim is necessary to reach the -goal. This volatility of specifications is the number one reasons I currently -advise against implementing your own modules (hint: if you do, be sure to use -module-template.h and be prepared to fix newly appearing and disappearing data -elements).</p> -<h2>Naming Conventions</h2> -<h3>Source</h3> -<p>Output modules, and only output modules, should start with a file name of -"om" (e.g. "omfile.c", "omshell.c"). Similarly, input modules will use "im" and -filter modules "fm". The third character shall not be a hyphen.</p> -<h2>Module Security</h2> -<p>Modules are directly loaded into rsyslog's address space. As such, any module -is provided a big level of trust. Please note that further module interfaces -might provide a way to load a module into an isolated address space. This, -however, is far from being completed. So the number one rule about module -security is to run only code that you know you can trust.</p> -<p>To minimize the security risks associated with modules, rsyslog provides only -the most minimalistic access to data structures to its modules. For that reason, -the output modules do not receive any direct pointers to the selector_t -structure, the syslogd action structures and - most importantly - the msg -structure itself. Access to these structures would enable modules to access data -that is none of their business, creating a potential security weakness.</p> -<p>Not having access to these structures also simplifies further queueing and -error handling cases. As we do not need to provide e.g. full access to the msg -object itself, we do not need to serialize and cache it. Instead, strings needed -by the module are created by syslogd and then the final result is provided to -the module. That, for example, means that in a queued case $NOW is the actual -timestamp of when the message was processed, which may be even days before it -being dequeued. Think about it: If we wouldn't cache the resulting string, $NOW -would be the actual date if the action were suspended and messages queued for -some time. That could potentially result in big confusion.</p> -<p>It is thought that if an output module actually needs access to the while msg -object, we will (then) introduce a way to serialize it (e.g. to XML) in the -property replacer. Then, the output module can work with this serialized object. -The key point is that output modules never deal directly with msg objects (and -other internal structures). Besides security, this also greatly simplifies the -job of the output module developer.</p> -<h2>Action Selectors</h2> -<p>Modules (and rsyslog) need to know when they are called. For this, there must -a an action identification in selector lines. There are two syntaxes: the -single-character syntax, where a single characters identifies a module (e.g. "*" -for a wall message) and the modules designator syntax, where the module name is -given between colons (e.g. ":ommysql:"). The single character syntax is -depreciated and should not be used for new plugins.</p> -<p>An in-depth discussion of module designation in action selectors can be found -in this forum thread:</p> -<p> -<a href="http://www.rsyslog.com/index.php?name=PNphpBB2&file=viewtopic&p=678#678"> -http://www.rsyslog.com/index.php?name=PNphpBB2&file=viewtopic&p=678#678</a></p> -<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> |