added a bit more information about modules

1 files changed, 43 insertions, 0 deletions

diff --git a/doc/modules.html b/doc/modules.html
index bd702596..b6d1383a 100644
--- a/doc/modules.html
+++ b/doc/modules.html
@@ -20,12 +20,55 @@ 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 &quot;generation&quot;</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 laborous 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 &quot;specification&quot;.</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 &quot;non-clean&quot; 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 torwards 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 
+&quot;om&quot; (e.g. &quot;omfile.c&quot;, &quot;omshell.c&quot;). Similarily, input modules will use &quot;im&quot; and 
+filter modules &quot;fm&quot;. 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 structurs 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 queueed 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 suspened and messages queued for 
+some time. That could potentially result in big confusion.</p>
+<p>It is thought that if an output modlue 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>Copyright</h2>
 <p>Copyright (c) 2007
 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>