Valvulad server administration manual


1. Valvulad server configuration

Assuming you already have Valvulad server binaries installed in your system you must create a valvula.conf file at /etc/valvula

1) In general you can use as example the template bundled. For that run:

>> cp /etc/valvula/valvula.example.conf /etc/valvula/valvula.conf

2) After that, create a mysql database and a user associated to it. Check your OS documentation on how to do this. Please, do not use system administrator MySQL account directly with valvula.

3) Now with you MySQL credentails, set them inside valvula.conf inside database section:

<!-- default mysql configuration -->
<config driver="mysql" dbname="valvula" user="valvula" password="valvula" host="localhost" port="" />

4) After this, you can check if valvula is able to use your MySQL account by running the following. It should output that everything is working.

>> valvulad -b
INFO: Database connection working OK

Now you have base Valvulad installed. Now you have to enable modules and connect them to postfix configuration. See next.

2. Enabling Valvulad server modules

you need python-axl installed in your system in order to have working.
To have it installed, take a look at
For debian systems, you can also install it by running:
>> apt-get install python-axl

Please, read each module documentation to know more about them and their features.

2.1 Types of module activation: with or without port association

There are two types of module activation in valvula:

1) Enabling module without port association (for example: -e mod-object-resolver)

2) Enabling module with port association (for example: -m mod-slm 3080)

The difference is that valvula allows you to associate different modules to different TCP policy ports. This way you can have a blacklisting module in some port and a policy limit in another. You can also combine them in different orders to achieve different results.

For all these cases we are talking about activating modules with port association, that is, modules that are enabled and registered to be called when the request is received in such port.

However, there are modules, like mod-object-resolver which adds handlers and configures valvulad engine. That is, they are not meant to be run at certain port or to process request. They are just modules that can be enabled or disabled (using -e to enable and -d to disable).

2.2 Enabling modules with port association

Assuming you know what modules you want you have to:

1) Run the following command to list all modules available:

>> -o
Module: mod-slm
Module: mod-mquota
Module: mod-bwl

2) Now, you have to now what listeners/ports are already declared by Valvula where you can run modules. These listeners are just Valvulad server entry points where postfix can delegate policy. If you don't undestand it, don't worry too much. Keep on reading and you'll understand by example.

>> -l

3) If there are not listeners added, you must add at least one. Do it by running the following (that adds, for example, a valvulad listener at 3080 TCP/port):

>> -a 3080

NOTE: this will update /etc/valvula/valvula.conf file. Please, have a look at it to know what's going on.

Now, this listener/port is an eligible place to run modules that will control/modify postfix decisions about mail passing through it.

4) Now, assuming you want to enable mod-slm, you enable it at a particular listener by running the following command.

>> -m mod-slm 3080

NOTE: this will update /etc/valvula/valvula.conf file. Please, have a look at it to know what's going on.

5) After that, restart valvula by running something like:

>> service valvulad restart

6) Now, you must connect this module to postfix in a particular section. The point here is that postfix will call valvula server, at a particular listener, where you have configured a set of modules. Also, the place where postfix is connect to valvula is important. In general, it is recommended to connect valvulad server at smtpd_recipient_restrictions section. If you want to know what are the postfix section and a description run:

>> -s

7) Assuming we want to connect postfix to delegate decisions to valvula at smtpd_recipient_restrictions on the port/listener 3080, just run:

>> -c smtpd_recipient_restrictions 3080 first

This command means that you are connecting valvula listener located at 3080, at the postfix's section called smtpd_recipient_restrictions. The first is telling to make that connection to be first policy executed by postfix on that section. You can also use last to change the place accordingly.

8) Now you are done. Just reload postfix and watch postfix+valvula function by running:

>> service postfix reload
>> tail -f /var/log/mail.log

3. Hey, it isn't working, what should I do!

Don't panic. It depends on the error you are having but if it's fatal, please, just comment out "check_policy_service" declaration at /etc/postfix/ that is conecting postfix to valvula so your server can keep going as it was configured. After commeting that declaration reload postfix:

>> service postfix reload

Then, you can count on us at the mailing list to get some help: