En/4.1/Appendix B: Development and advanced configuration

From Zentyal Linux Small Business Server
Jump to: navigation, search


Importing configuration data

Although Zentyal UI interface greatly eases the system administrator work, some configuration tasks through the interface can be tedious if you have to perform them repeatedly. For example, adding 100 new user accounts or enabling an e-mail account for all 100 users.

These tasks can be automated easily through the Application Programming Interface (API) which is provided by Zentyal. You only need a basic knowledge of Perl(1), and to know the public methods exposed by the Zentyal modules you want to use. In fact, Zentyal web interface uses the same programming interface.

[1] Perl is a high-level, general-purpose, interpreted, dynamic

programming language. http://www.perl.org/

An example on how to create a small utility is shown below, using the Zentyal API to automatically add an arbitrary number of users defined in a Comma Separated Values (CSV) file


use strict;
use warnings;

use EBox;
use EBox::Samba::User;
use File::Slurp;

my @lines = read_file('users.csv');
chomp (@lines);


my $parent = EBox::Samba::User->defaultContainer();

for my $line (@lines) {
    my ($username, $givenname, $surname, $password) = split(',', $line);
        samAccountName => $username,
        parent => $parent,
        givenName => $givenname,
        sn => $surname,
        password => $password


Save the file with the name bulkusers and grant it execution permission using the following command: chmod +x bulkusers.

Before running the script, you must have a file called users.csv in the same directory. The appearance of this file should be as follows:

jfoo,John,Foo,jfoopassword, jbar,Jack,Bar,jbarpassword,Finally, you must be in the directory where the files are placed and run:

sudo ./bulkusersThis section has shown a small example of task automation using the Zentyal API, but the possibilities are almost unlimited.

Advanced Service Customization

You may need to extend Zentyal's modules functionality to suit your needs. Zentyal offers you two different mechanisms to do so in such a way that you can still benefit from the abstraction, automation and context offered by the framework.

stubs: Templates that will be used to generate the configuration files used by the daemons. Modifying or creating a stub, you can customize the behaviour of any module, for example, adding a safe port to squid (HTTP Proxy) configuration.

hooks: Scripts that will be triggered during specific checkpoints of the life cycle of a module, for example adding a rule that marks certain types of traffic in the firewall after refreshing Zentyal's rules.


The Zentyal modules, once enabled, overwrite the original system configuration files for the services they manage. Modules do this through templates that essentially contain the structure of a configuration file for the service. Some parts of the resulting file are parametrized through variables provided by the framework.

Configuration file from stub

Modifying the configuration files directly is incorrect, because these files will be overwritten each time the templates are processed (saving changes, for example). Zentyal's own configuration templates can be found in /usr/share/zentyal/stubs, and their names are the original configuration file, plus the .mas extension, for example /usr/share/zentyal/stubs/dns/named.conf.mas. Modifying these templates is not a good solution either, because they will be overwritten if the software package is updated or reinstalled.

Therefore, to make your changes persistent, you can copy the original template file to a directory in /etc/zentyal/stubs/ with the name of the module.

For example:

sudo mkdir /etc/zentyal/stubs/dns sudo cp /usr/share/zentyal/stubs/dns/named.conf.options.mas /etc/zentyal/stubs/dnsAnother advantage of copying the templates to /etc/zentyal/stubs/ is that you can keep control of the modifications that you have done over the original templates, and you will always be able to check these differences using the 'diff' tool. For example, for the former case:

diff /etc/zentyal/stubs/dns/named.conf.options.mas /usr/share/zentyal/stubs/dns/named.conf.options.masFor the next example, let's suppose you don't want to allow the DMZ network, which is internal but not so trusted, to perform DNS full zone transfers.

You will create the directory /etc/zentyal/stubs/dns and copy the files named.conf.local.mas and named.conf.options.mas.

You add the DMZ group containing the desired network ranges in named.conf.local.mas:

acl "DMZ" {;;

};And then forbid zone transfers to this object in named.conf.options.mas:

allow-transfer { !DMZ; internal-local-nets; };Remember to restart the module after modifying the files:

sudo service zentyal dns restart


It is possible that you need to perform certain additional actions at some point of the execution state of a module. For example, when Zentyal saves changes related to the firewall, the first thing the firewall module does is to remove all existing rules, and then add the ones configured in Zentyal. If you manually add a custom iptables rule that is not covered by Zentyal interface, it will disappear when saving firewall module changes. To tweak that behavior, Zentyal lets you run scripts while the saving changes process is being performed. There are six points during the process when you may execute these scripts, also known as hooks. Two of them are general and the remaining four are per module:

  • Before saving changes:

In /etc/zentyal/pre-save directory all scripts with running permissions are run before starting the save changes process.

  • After saving changes:

Scripts with running permissions in /etc/zentyal/post-save directory are executed when the process is finished.

  • Before saving module configuration:

Writing /etc/zentyal/hooks/<module>.presetconf file being <module> the module name you want to tailor, the hook is executed prior to overwriting the module configuration.

  • After saving module configuration:

/etc/zentyal/hooks/<module>.postsetconf file is executed after saving <module> configuration.

  • Before restarting the service:

/etc/zentyal/hooks/<module>.preservice is executed. This script could be useful to load Apacheā„¢ modules, for instance.

  • After restarting the service:

/etc/zentyal/hooks/<module>.postservice is executed. For the firewall case, all the extra rules can be added here.

Let's suppose your server has a transparent proxy, but you wish to exclude a certain network segment from the automatic redirection of HTTP connections. You will create the file /etc/zentyal/hooks/firewall.postservice with the following content:

  1. !/bin/bash

iptables -t nat -I premodules -s -p tcp -m tcp --dport 80 -j ACCEPTafter that, you will give execution permissions to the file and restart the service:

sudo chmod +x firewall.postservice sudo service zentyal firewall restartThese options have great potential and allow highly customizable Zentyal operations.

Community support

Community support is provided mainly on the Internet. There are many occasions in which the community is able to support itself. That is, the users help each other.

The community members are an important, even fundamental, providers of information for the product development. Users contribute by discovering hidden bugs and help developers to improve the product so it becomes more attractive to more users.

This voluntary support, logically, does not offer any guarantees. If a user asks a question, it is possible that no reply is given depending on the question format, timing or any other circumstances.

Zentyal community support channels is centered on the forum (2), although mailing lists (3) and IRC channels (4) are also available.

[4] irc.freenode.net server, #zentyal (English) and

#zentyal-es (Spanish) channels.

All this information is available, with further documentation, in the community section of the Zentyal web site (http://www.zentyal.org).

Personal tools


Zentyal Wiki

Zentyal Doc