Valvulad plugin development manual

Introduction to valvula plugin developement

Writing a Valvulad server plugin consists of creating a C module that is loaded at run time by the server. To write that module you'll have to use Valvula API.

The recommended way to start is to take mod-test.c as a base example to extend upon. To that end, grab a copy from https://dolphin.aspl.es/svn/publico/valvula/plugins/mod-test/mod-test.c

Also, grab a copy of the Makefile.am (https://dolphin.aspl.es/svn/publico/valvula/plugins/mod-test/Makefile.am) to bootstrap your module compilation. On that Makefile.am you'll see the essentials about getting that module compiled.

Finally, you'll need a module pointer, which is a small xml file, which is installed at /etc/valvula/mods-available, that allows valvula server to locate your compiled plugin. Take a look at https://dolphin.aspl.es/svn/publico/valvula/plugins/mod-test/mod-test.xml to have a copy too.

So, to summarize, you'll need the following files:

Of course, you don't want your module to be called mod-test right? Change that into something meaningful to the module's function.

Plugin run-time activation

Before getting into the details about each handler inside a module let's consider how the code will flow. Assuming you have everything compiled and activated, your module will be called like this:

That's the very basic function. Then, your module can receive a call to ModReconfFunc requesting to reload configuration (a kind of run-time init function). This is received when the user/administrator sends a SIGHUP signal to reload the process. This handler is optional but recommended.

Finally, your module may receive a call to ModUnloadFunc indicating the module is going to be unloaded (a kind of run-time close function). There, you'll have to implement all resource release code.

Plugin installation notes

Now, before getting into details about how modules are created, a few notes about installing new modules. This is as easy as:

>> valvulad-mgr.py -o
>> service valvulad restart

Plugin testing notes (checking Valvula without having postfix running)

To test your new module or any other modules, you can do the obvious operation which is sending a test to postfix to see what happens.

However, it is also possible to test valvula server directly without having postfix running. Use the following command to configure a request as if it were sent by the postfix server:

>> valvulad-mgr.py -t

That will ask for the required details and will connect to the port indicated by the user, producing a network interation exactly the same as if it were done by postfix.

This command can also be used to check valvula is working (for a checker/monitor).

Plugin developement notes

The following are general notes that you can use to solve common questions while using valvula API ( Valvula API) :

How do I check if a user was autenticated?

Use valvula_is_authenticated

How do I check if the sending user is a local user?

Use valvulad_run_is_local_address

And a local domain?

Use valvulad_run_is_local_domain