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:

• The module itself (mod-test.c) : https://dolphin.aspl.es/svn/publico/valvula/plugins/mod-test/mod-test.c
• A makefile to get it compiled : https://dolphin.aspl.es/svn/publico/valvula/plugins/mod-test/Makefile.am
• A module pointer : https://dolphin.aspl.es/svn/publico/valvula/plugins/mod-test/mod-test.xml

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:

• 1. First, the ModInitFunc (in our case test_init) function will be called first at valvula startup. There, you'll have to place all initialization code you need to make the module work. This function is only called once.
• 2. Then, for every request postfix passes to Valvula, and in the case your module is connected to the listener port (see 1. Valvulad server configuration), then your module will be called at ValvulaProcessRequest (in our case test_process_request). That function will have to make a decision about that request by returning any of the available values found at: ValvulaState. Optionally you can also return a message to postfix so he can report that message to the user (and record it into the log). We will get into more details about this function later.
• 3. At the end, in the case valvula is closing/stoping, ModCloseFunc (in our case test_close) will be called. There you'll have to release resources and save state for later recovery (if any).

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:

• 1. Copy the compiled module into (mod-your-mod.so), for example, /usr/lib/valvulad/modules.
• 2. Then, copy your updated module pointer (mod-your-mod.xml) into /etc/valvula/mod-available. Make your the content of that file actually points to the full path of your .so
• 3. After that, you shoul be able to run the following command to check if the module is detected (at least), by the configuration:

>> valvulad-mgr.py -o

• 4. After that, to test the module, you must connect it to a valvula listener. See (see 1. Valvulad server configuration).
• 5. Finally, don't forget restart valvula to have it load your new brand module:

>> 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