dsyslog configuration guide
6/15/2008 Jeff Katz

dsyslog ships with an example configuration file that aims to have dsyslog 
operate as a drop-in replacement for syslogd. 

However, the true power of dsyslog is just how versatile its configuration can
be. 

Since the entirety of dsyslog is modularized, you can pretty much configure 
dsyslog to behave however you'd like. In this document, we will attempt to 
present all the information required to configure dsyslog to your heart's 
content.

The configuration file is an ascii text file which supports statements and
comments. Comments are any line that begins with # or //, as well as c-style
multi-line comments (blocks beginning with /* and ending with */. Statements 
should be terminated with a semicolon (;).  
	
Everything that is not a comment is a statement. With a blank configuration,
the only statements that are valid are loadmodule statements. You will want to
load a source module and an output module at a very minimum. These statements
will look like the following:
	
		loadmodule "source_localsock.so";
		loadmodule "output_file.so";
		
These two statements load the modules source_localsock and output_file. With
just these two statements, dsyslog can already get logging information from 
the local system socket and write it to a file. 
	
To do configure this very behavior, you will use the 'source' and 'output' 
statements. The source and output statements are syntactically very similar.
The source statement gives command arguments to a source module, whereas the
output statement gives command arguments to an output module. These arguments
can tell the modules what files to monitor, where to write, what permissions
to use, etc. In our case, we want to read from /dev/sock and write to 
/var/log/dsyslog_example. We add the following statements to accomplish that
goal: 
	
		source localsock { path "/dev/log"; };
		output file { path "/var/log/dsyslog_example"; };
	
If we stopped editing our configuration file with just these four statements,
we'd have a (crude, but) working system logger. 

In addition to sources and outputs, dsyslog supports modules of type filter and
conditional.

Conditional modules allow dsyslog to change its behavior based on certain
conditions, for instance: multiple, duplicate messages or messages from
a certain source. Filter modules allow dsyslog to change the output messages 
based on certain filters, such as a regex, or to drop certain messages
completely.

To take advantage of these additional modules, first we'll have to load them
with the loadmodule directive. The cond_literal module allows for literal 
comparisons in conditional statements, so lets load that one first. Remember 
how? It's easy:

		loadmodule "cond_literal.so";
		
Once this module is loaded, we can take advantage of additional parameters to 
the output statement. For instance:

		output file { path "/var/log/dsyslog_example"; condition literal 
		{ program "!in.qpopper"; }; };

Will direct dsyslog to log all messages that are NOT from the qmail daemon to
our log file located at /var/log/dsyslog_example. 

There are numerous examples of these and other modules in the example
configuration file that ships with the dsyslog distribution. The authors 
encourage you to tinker and find out what works for you.