added output module template

so far, this is mostly some documentation, but I hope that during
the process of creating output modules out of it we will get good
questions and thus can extend the template. In any case, it should
be better than what we had so far...

5 files changed, 260 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index 3488dfb2..8c8442e2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,5 @@
+---------------------------------------------------------------------------
+Version 4.1.6  [DEVEL] (rgerhards), 2009-03-??
 - implemented function support in RainerScript. That means the engine
   parses and compile functions, as well as executes a few build-in
   ones. Dynamic loading and registration of functions is not yet
@@ -5,8 +7,7 @@
   NOTE: nested function calls are not yet supported due to a design
   issue with the function call VM instruction set design.
 - implemented the strlen() RainerScript function
----------------------------------------------------------------------------
-Version 4.1.6  [DEVEL] (rgerhards), 2009-03-??
+- added a template output module
 ---------------------------------------------------------------------------
 Version 4.1.5  [DEVEL] (rgerhards), 2009-03-11
 - bugfix: parser did not correctly parse fields in UDP-received messages
diff --git a/Makefile.am b/Makefile.am
index aaca570d..7bb6af8e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -88,6 +88,10 @@ if ENABLE_IMTEMPLATE
 SUBDIRS += plugins/imtemplate
 endif
 
+if ENABLE_OMTEMPLATE
+SUBDIRS += plugins/omtemplate
+endif
+
 if ENABLE_IMFILE
 SUBDIRS += plugins/imfile
 endif
@@ -114,5 +118,5 @@ SUBDIRS += tests
 # temporarily be removed below. The intent behind forcing everthing to compile
 # in a make distcheck is so that we detect code that accidently was not updated
 # when some global update happened.
-DISTCHECK_CONFIGURE_FLAGS=--enable-gssapi_krb5 --enable-imfile --enable-snmp --enable-pgsql --enable-libdbi --enable-mysql --enable-imtemplate --enable-relp --enable-rsyslogd --enable-mail --enable-klog  --enable-diagtools --enable-gnutls
+DISTCHECK_CONFIGURE_FLAGS=--enable-gssapi_krb5 --enable-imfile --enable-snmp --enable-pgsql --enable-libdbi --enable-mysql --enable-omtemplate --enable-imtemplate --enable-relp --enable-rsyslogd --enable-mail --enable-klog  --enable-diagtools --enable-gnutls
 ACLOCAL_AMFLAGS = -I m4
diff --git a/configure.ac b/configure.ac
index 4763fcd5..0c9483ca 100644
--- a/configure.ac
+++ b/configure.ac
@@ -631,9 +631,7 @@ AC_SUBST(LIBLOGGING_CFLAGS)
 AC_SUBST(LIBLOGGING_LIBS)
 
 
-# settings for the template input module; copy and modify this code
-# if you intend to add your own module. Be sure to replace imtemplate
-# by the actual name of your module.
+# settings for the file input module;
 AC_ARG_ENABLE(imfile,
         [AS_HELP_STRING([--enable-imfile],[file input module enabled @<:@default=no@:>@])],
         [case "${enableval}" in
@@ -649,8 +647,7 @@ AC_ARG_ENABLE(imfile,
 #
 AM_CONDITIONAL(ENABLE_IMFILE, test x$enable_imfile = xyes)
 
-AM_CONDITIONAL(ENABLE_IMTEMPLATE, test x$enable_imtemplate = xyes)
-# end of copy template - be sure to serach for imtemplate to find everything!
+
 # settings for the template input module; copy and modify this code
 # if you intend to add your own module. Be sure to replace imtemplate
 # by the actual name of your module.
@@ -671,6 +668,26 @@ AM_CONDITIONAL(ENABLE_IMTEMPLATE, test x$enable_imtemplate = xyes)
 # end of copy template - be sure to serach for imtemplate to find everything!
 
 
+# settings for the template output module; copy and modify this code
+# if you intend to add your own module. Be sure to replace omtemplate
+# by the actual name of your module.
+AC_ARG_ENABLE(omtemplate,
+        [AS_HELP_STRING([--enable-omtemplate],[Compiles omtemplate template module @<:@default=no@:>@])],
+        [case "${enableval}" in
+         yes) enable_omtemplate="yes" ;;
+          no) enable_omtemplate="no" ;;
+           *) AC_MSG_ERROR(bad value ${enableval} for --enable-omtemplate) ;;
+         esac],
+        [enable_omtemplate=no]
+)
+#
+# you may want to do some library checks here - see snmp, mysql, pgsql modules
+# for samples
+#
+AM_CONDITIONAL(ENABLE_OMTEMPLATE, test x$enable_omtemplate = xyes)
+# end of copy template - be sure to serach for omtemplate to find everything!
+
+
 AC_CONFIG_FILES([Makefile \
 		runtime/Makefile \
 		tools/Makefile \
@@ -683,6 +700,7 @@ AC_CONFIG_FILES([Makefile \
 		plugins/immark/Makefile \
 		plugins/imklog/Makefile \
 		plugins/imtemplate/Makefile \
+		plugins/omtemplate/Makefile \
 		plugins/imfile/Makefile \
 		plugins/imrelp/Makefile \
 		plugins/imdiag/Makefile \
@@ -713,6 +731,7 @@ echo "RELP support enabled:                     $enable_relp"
 echo "imdiag enabled:                           $enable_imdiag"
 echo "file input module enabled:                $enable_imfile"
 echo "input template module will be compiled:   $enable_imtemplate"
+echo "output template module will be compiled:   $enable_omtemplate"
 echo "Large file support enabled:               $enable_largefile"
 echo "Networking support enabled:               $enable_inet"
 echo "GnuTLS network stream driver enabled:     $enable_gnutls"
diff --git a/plugins/omtemplate/Makefile.am b/plugins/omtemplate/Makefile.am
new file mode 100644
index 00000000..58ddc794
--- /dev/null
+++ b/plugins/omtemplate/Makefile.am
@@ -0,0 +1,8 @@
+pkglib_LTLIBRARIES = omtemplate.la
+
+omtemplate_la_SOURCES = omtemplate.c omtemplate.h
+omtemplate_la_CPPFLAGS =  $(RSRT_CFLAGS) $(PTHREADS_CFLAGS)
+omtemplate_la_LDFLAGS = -module -avoid-version
+omtemplate_la_LIBADD = 
+
+EXTRA_DIST = 
diff --git a/plugins/omtemplate/omtemplate.c b/plugins/omtemplate/omtemplate.c
new file mode 100644
index 00000000..e35968ad
--- /dev/null
+++ b/plugins/omtemplate/omtemplate.c
@@ -0,0 +1,220 @@
+/* omtemplate.c
+ * This is a template for an output module. It implements a very
+ * simple single-threaded output, just as thought of by the output
+ * plugin interface.
+ *
+ * NOTE: read comments in module-template.h for more specifics!
+ *
+ * File begun on 2009-03-16 by RGerhards
+ *
+ * Copyright 2009 Rainer Gerhards and Adiscon GmbH.
+ *
+ * This file is part of rsyslog.
+ *
+ * Rsyslog is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Rsyslog is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Rsyslog.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * A copy of the GPL can be found in the file "COPYING" in this distribution.
+ */
+#include "config.h"
+#include "rsyslog.h"
+#include <stdio.h>
+#include <stdarg.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+#include <signal.h>
+#include <errno.h>
+#include <time.h>
+#include "dirty.h"
+#include "syslogd-types.h"
+#include "srUtils.h"
+#include "template.h"
+#include "module-template.h"
+#include "errmsg.h"
+#include "cfsysline.h"
+
+MODULE_TYPE_OUTPUT
+
+/* internal structures
+ */
+DEF_OMOD_STATIC_DATA
+DEFobjCurrIf(errmsg)
+
+typedef struct _instanceData {
+	/* here you need to define all action-specific data. A record of type 
+	 * instanceData will be handed over to each instance of the action. Keep
+	 * in mind that there may be several invocations of the same type of action
+	 * inside rsyslog.conf, and this is what keeps them apart. Do NOT use
+	 * static data for this!
+	 */
+	unsigned iSrvPort;	/* sample: server port */
+} instanceData;
+
+/* config variables
+ * For the configuration interface, we need to keep track of some settings. This
+ * is done in global variables. It works as follows: when configuration statements
+ * are entered, the config file handler (or custom function) sets the global
+ * variable here. When the action then actually is instantiated, this handler
+ * copies over to instanceData whatever configuration settings (from the global
+ * variables) apply. The global variables are NEVER used inside an action
+ * instance (at least this is how it is supposed to work ;)
+ */
+static int iSrvPort = 0;	/* sample: server port */
+
+
+BEGINcreateInstance
+CODESTARTcreateInstance
+ENDcreateInstance
+
+
+BEGINisCompatibleWithFeature
+CODESTARTisCompatibleWithFeature
+	/* use this to specify if select features are supported by this
+	 * plugin. If not, the framework will handle that. Currently, only
+	 * RepeatedMsgReduction ("last message repeated n times") is optional.
+	 */
+	if(eFeat == sFEATURERepeatedMsgReduction)
+		iRet = RS_RET_OK;
+ENDisCompatibleWithFeature
+
+
+BEGINfreeInstance
+CODESTARTfreeInstance
+	/* this is a cleanup callback. All dynamically-allocated resources
+	 * in instance data must be cleaned up here. Prime examples are
+	 * malloc()ed memory, file & database handles and the like.
+	 */
+ENDfreeInstance
+
+
+BEGINdbgPrintInstInfo
+CODESTARTdbgPrintInstInfo
+	/* permits to spit out some debug info */
+ENDdbgPrintInstInfo
+
+
+BEGINtryResume
+CODESTARTtryResume
+	/* this is called when an action has been suspended and the
+	 * rsyslog core tries to resume it. The action must then
+	 * retry (if possible) and report RS_RET_OK if it succeeded
+	 * or RS_RET_SUSPENDED otherwise.
+	 * Note that no data can be written in this callback, as it is
+	 * not present. Prime examples of what can be retried are
+	 * reconnects to remote hosts, reconnects to database,
+	 * opening of files and the like.
+	 * If there is no retry-type of operation, the action may
+	 * return RS_RET_OK, so that it will get called on its doAction
+	 * entry point (where it receives data), retries there, and
+	 * immediately returns RS_RET_SUSPENDED if that does not work
+	 * out. This disables some optimizations in the core's retry logic,
+	 * but is a valid and expected behaviour. Note that it is also OK
+	 * for the retry entry point to return OK but the immediately following
+	 * doAction call to fail. In real life, for example, a buggy com line
+	 * may cause such behaviour.
+	 * Note that there is no guarantee that the core will very quickly
+	 * call doAction after the retry succeeded. Today, it does, but that may
+	 * not always be the case.
+	 */
+ENDtryResume
+
+BEGINdoAction
+CODESTARTdoAction
+	/* this is where you receive the message and need to carry out the
+	 * action. Data is provided in ppString[i] where 0 <= i <= num of strings
+	 * requested.
+	 * Return RS_RET_OK if all goes well, RS_RET_SUSPENDED if the action can
+	 * currently not complete, or an error code or RS_RET_DISABLED. The later
+	 * two should only be returned if there is no hope that the action can be
+	 * restored unless an rsyslog restart (prime example is an invalid config).
+	 * Error code or RS_RET_DISABLED permanently disables the action, up to
+	 * the next restart.
+	 */
+ENDdoAction
+
+
+BEGINparseSelectorAct
+CODESTARTparseSelectorAct
+CODE_STD_STRING_REQUESTparseSelectorAct(1)
+	/* first check if this config line is actually for us
+	 * This is a clumpsy interface. We receive the action-part of the selector line
+	 * and need to look at the first characters. If they match our signature
+	 * ":omtemplate:", then we need to instantiate an action. It is recommended that
+	 * newer actions just watch for the template and all other parameters are passed in
+	 * via $-config-lines, this will hopefully be compatbile with future config syntaxes.
+	 * If we do not detect our signature, we must return with RS_RET_CONFLINE_UNPROCESSED
+	 * and NOT do anything else.
+	 */
+	if(strncmp((char*) p, ":omtemplate:", sizeof(":omtemplate:") - 1)) {
+		ABORT_FINALIZE(RS_RET_CONFLINE_UNPROCESSED);
+	}
+
+	/* ok, if we reach this point, we have something for us */
+	p += sizeof(":omtemplate:") - 1; /* eat indicator sequence  (-1 because of '\0'!) */
+	CHKiRet(createInstance(&pData));
+
+	/* check if a non-standard template is to be applied */
+	if(*(p-1) == ';')
+		--p;
+	/* if we have, call rsyslog runtime to get us template. Note that StdFmt below is
+	 * the standard name. Currently, we may need to patch tools/syslogd.c if we need
+	 * to add a new standard template.
+	 */
+	CHKiRet(cflineParseTemplateName(&p, *ppOMSR, 0, OMSR_RQD_TPL_OPT_SQL, (uchar*) " StdFmt"));
+	
+	/* if we reach this point, all went well, and we can copy over to instanceData
+	 * those configuration elements that we need.
+	 */
+	pData->iSrvPort = (unsigned) iSrvPort;	/* set configured port */
+
+CODE_STD_FINALIZERparseSelectorAct
+ENDparseSelectorAct
+
+
+BEGINmodExit
+CODESTARTmodExit
+ENDmodExit
+
+
+BEGINqueryEtryPt
+CODESTARTqueryEtryPt
+CODEqueryEtryPt_STD_OMOD_QUERIES
+ENDqueryEtryPt
+
+
+/* Reset config variables for this module to default values.
+ */
+static rsRetVal
+resetConfigVariables(uchar __attribute__((unused)) *pp, void __attribute__((unused)) *pVal)
+{
+	DEFiRet;
+	iSrvPort = 0; /* zero is the default port */
+	RETiRet;
+}
+
+
+BEGINmodInit()
+CODESTARTmodInit
+	*ipIFVersProvided = CURR_MOD_IF_VERSION; /* we only support the current interface specification */
+CODEmodInit_QueryRegCFSLineHdlr
+	CHKiRet(objUse(errmsg, CORE_COMPONENT));
+	/* register our config handlers */
+	/* confguration parameters MUST always be specified in lower case! */
+	CHKiRet(omsdRegCFSLineHdlr((uchar *)"actionomtemplteserverport", 0, eCmdHdlrInt, NULL, &iSrvPort, STD_LOADABLE_MODULE_ID));
+	/* "resetconfigvariables" should be provided. Notat that it is a chained directive */
+	CHKiRet(omsdRegCFSLineHdlr((uchar *)"resetconfigvariables", 1, eCmdHdlrCustomHandler, resetConfigVariables, NULL, STD_LOADABLE_MODULE_ID));
+ENDmodInit
+
+/* vi:set ai:
+ */