How to customize the configuration files generated by Zentyal

January 4, 2011

As you know, the Linux small business serverĀ Zentyal automatically configures all the network services needed by a SMB. This includes writing of all the necessary configuration files (/etc/samba/smb.conf, /etc/squid/squid.conf, …). Typically most of the users don’t want or simply don’t need to manually edit these files because the Zentyal administration interface provides enough elements to customize the configuration of the services. But there is a bunch of advanced users that usually need to go further, fine tuning the automatically generated configuration to better fit their needs or even set up features that are not covered (yet :P) by Zentyal server.

The aim of this post is to tell you about a new feature that was recently included (in the 2.0.10 version of the core package) to ease the customization of the configuration templates. But first let me briefly explain how the templates system work and what were the customization possibilities the users had before this new improvement.

The actual configuration files of each service are overwritten each time the service is restarted or changes are saved from the administration interface. The contents of each file are generated by using a Mason template which mainly consist of a skeleton of the actual file including some substitution variables and some small pieces of code like conditions or loops.

For example, the template that corresponds to he main Squid configuration file, /etc/squid/squid.conf, is located at /usr/share/ebox/stubs/squid/squid.conf.mas. In general, all the templates follow the rule /usr/share/ebox/stubs/<modulename>/<filename>.mas.

Having this in mind, you should never be tempted to directly edit a configuration file managed by Zentyal in /etc. It’s clearly better to edit the template, because that way it doesn’t matter if the configuration is rewritten, it will always contain your modifications. But this is not a perfect solution, what happens when the Zentyal module that contains the template is updated? Yes, the template is also overwritten. To avoid this, we introduced a hooks mechanism some time ago.

Under /etc/ebox/hooks you can add scripts (in any language) that will be executed before and after writing the configuration, and also before and after restarting the service daemons. In this directory you can find generic example files for the four types of supported hooks (presetconf, postsetconf, preservice and postservice). And in addition, you find here an already created firewall.postservice hook script that directly allows you to add any custom iptables rule you may want to add.

Let’s see a practical example. Imagine you want to add ad-blocking capabilities to the Zentyal content filter and you’ve found this post in the community forum explaining how to do it. A better way to do the second step without modifying the template file would be to create a /etc/ebox/hooks/squid.postsetconf script with the following line:

echo "url_rewrite_program /usr/bin/adzapper.wrapper" >> /etc/squid/squid.conf

That way, right after the squid.conf file generation is finished, our customized line will be appended to the end of the file.

So, let’s go now with the new possibility. Maybe it’s a bit overkill in this case, but it is really useful if instead of adding a new line you want to make deeper changes in the configuration template. Just execute the following commands:

mkdir -p /etc/ebox/stubs/squid
cp /usr/share/ebox/stubs/squid/squid.conf.mas /etc/ebox/stubs/squid
echo "url_rewrite_program /usr/bin/adzapper.wrapper" \
    >> /etc/ebox/stubs/squid/squid.conf.mas

After that, our custom line will be added forever to our custom template, and this template will be used for generating the configuration instead of the default one. It won’t get overwritten by any software update. Easy, right?

Finally, I don’t want to finish the post without thanking Oliver, the community member who not only gave the idea, but also sent a patch with his modifications in the Zentyal code. This allowed us to add this improvement quickly. I also want to encourage any of you to follow Oliver’s steps and become active contributors. Together we can make a great project!