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

#!/usr/bin/perl

use strict;
use warnings;

use EBox;
use EBox::UsersAndGroups::User;

EBox::init();

my @users;
open (my $USERS, 'users');

while (my $line = <$USERS>) {
    chomp ($line);
    my $user;
    my ($username, $givenname, $surname, $password) = split(',', $line);
    $user->{'user'} = $username;
    $user->{'givenname'} = $givenname;
    $user->{'surname'} = $surname;
    $user->{'password'} = $password;
    push (@users, $user);
}
close ($USERS);

foreach my $user (@users) {
    EBox::UsersAndGroups::User->create($user, 0);
}

1;

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 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 ./bulkusers

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

Advanced Service Customisation

This section discusses two options for system customisation for users with special requirements:

  • Tailor service configuration files managed by Zentyal.
  • Perform actions in the process of saving changes in configuration.

When a module is responsible for automatically setting up a service, it tries to cover the most common configuration options. However, there are cases where there are so many configuration settings that it would be impossible for Zentyal to control them all. In addition to this, one of the main goals of Zentyal is simplicity. However, there are users who want to adjust some of those unhandled parameters to adapt Zentyal to their requirements. One of the possibilities of doing this is by editing the configuration files that handle the service directly.

Before deciding to modify a configuration file manually, you must understand how Zentyal works internally. 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 basic structure of a typical configuration file for the service. However, some of the parts are parametrised through variables. The values of these variables are assigned before overwriting the file and are taken from the configuration previously set using the Zentyal web interface.

How the configuration template system works

How the configuration template system works

Therefore, if you want to make your changes persistent, and prevent them from being overwritten every time Zentyal saves changes, you must edit templates instead of system configuration files. These templates are in /usr/share/zentyal/stubs and their names are the original configuration file names plus the .mas extension.

Take into account that these changes will persist even if you modify the Zentyal configuration; they will not apply anymore if you update the module containing the template. When you reinstall a package the .mas files will be overwritten. If you want these changes to be effective even when you update the module, you have to copy the template to /etc/zentyal/stubs/ inside the directory with the name of the module. This way, if you want, for example, to modify the template:file:/usr/share/zentyal/stubs/dns/named.conf.options.mas, you will create the directory /etc/zentyal/stubs/dns/, copy the template inside and modify this copy:

sudo mkdir /etc/zentyal/stubs/dns
sudo cp /usr/share/zentyal/stubs/dns/named.conf.options.mas /etc/zentyal/stubs/dns

Another 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.mas /etc/zentyal/stubs/dns

It is possible that you need to perform certain additional actions while Zentyal is saving changes instead of customising configuration files. 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 prevent that, 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. It is the ideal time to modify configuration templates from a module.
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. In the firewall case, all the extra rules must be added here.

These options have great potential and allow highly customisable Zentyal operations, offering better integration with the rest of the systems.

Development environment of new modules

Zentyal is designed with extensibility in mind and it is relatively simple to create new Zentyal modules.

Anyone with Perl language knowledge may take advantage of the Zentyal development framework to create web interfaces, and also benefit from the integration with the rest of the modules and the common features from the vast Zentyal library.

Zentyal design is completely object-oriented and it takes advantage of the Model-View-Controller (MVC) design pattern [2], so the developer only needs to define those features required by the data model. The remaining parts are generated automatically by Zentyal. To simplify the process further, a development tool called zmoddev [3] is provided to ease the development of new modules, auto-generating templates depending on the parameters provided by the user. This will save time, however, its explanation and development is beyond the scope of this course.

[2]An explanation about Model-View-Controller design pattern http://en.wikipedia.org/wiki/Model_View_Controller.
[3]zmoddev SVN repository access svn://svn.zentyal.org/zentyal/trunk/extra/zmoddev.

Zentyal is designed to be installed on a dedicated machine. This recommendation is also extended to the developing scheme. Developing on the same host is highly discouraged. The recommended option is to deploy a virtual system to develop as Appendix A: Test environment with VirtualBox explains in depth.

Release policy

Zentyal server development follows time based release cycle: a stable Zentyal release is published once a year, in September. The Zentyal Development Team has opted for time based release cycle most importantly because it makes easier, for both users and for developers, to make long-term decisions regarding the development, deployment and maintenance of the server and helps the Development Team to deliver well tested, high-quality software.

It is important to notice that all Zentyal releases are based on the Ubuntu LTS versions. Each Zentyal release is based on the Ubuntu LTS version that is available at the moment the release is launched.

Zentyal Release Cycle

There are three types of Zentyal server releases the Zentyal Development Team will publish during the Zentyal Release Cycle: Beta versions, Release Candidates and Stable versions. The stable versions will be supported for three years after which they reach their “end of life” date and become unsupported.

Zentyal Beta versions

Zentyal Beta versions are unstable software releases that are published from September to June. These beta versions introduce new features that are not yet fully tested for bugs. As the Zentyal Development Team follows the “Release early, release often” guideline, there might be an important number of beta versions published during this time period.

Beta releases always have odd major numbers: 1.1, 1.3, 1.5, 2.1, 2.3...

As Beta versions will eventually become stable releases, this means that 2.1 series followed this pattern: 2.1.1, 2.1.2, 2.1.3, .... 2.1.10, 2.1.11, 2.1.x -> 2.2

The 2.3 series will follow this pattern: 2.3.1, 2.3.2, 2.3.3, .... 2.3.10, 2.3.11, 2.3.x -> 3.0

Zentyal Release Candidates

Zentyal Release Candidates are published from July to September, during the three months stabilization period. There are as many release candidates as the Development Team deems necessary to stabilize the new code and bug fixes introduced before publishing the next stable version.

Release candidates always have the version number of the next stable release and the “rc” suffix to indicate that the version is a release candidate. A suffix of “rc1” would be used for the first release candidate, “rc2” for the second release candidate, “rc3” for the third release candidate, and so on: 3.0-rc1, 3.0-rc2...

Stable Zentyal versions

Stable Zentyal versions are published once a year, in September. Stable releases always have even major numbers: 1.0, 1.2, 1.4, 2.0, 2.2, 3.0... The first version number changes every time the base system, Ubuntu LTS version, is upgraded.

For example, the versions 1.0, 1.2 and 1.4 were based on Ubuntu 8.04 LTS , 2.0 and 2.2 were based on Ubuntu 10.04 LTS and the 3.0 will be based on Ubuntu 12.04 LTS.

Timetable

  • June: Zentyal development is frozen. Three months stabilization period starts. The necessary release candidate versions are published during this period.
  • September: Stable Zentyal version is published.
  • October-June: Zentyal development continues. The necessary beta versions are published during this period.

Support policy

The Zentyal Development Team offers three years of support for the stable Zentyal versions. This means that since the publication of a stable Zentyal version, support for all security issues as well as commercial support and subscription services will be granted for this version during the next three years. After this time period, the stable version reaches its “end of life” date and becomes unsupported.

Bug management policy

Each open source software project has its own bug management policy. As mentioned previously, the stable Zentyal versions are supported for three years during which support for all security issues is granted. In addition to security issues, other modifications might be added to fix several bugs at once. The latest Zentyal version always includes all the bug fixes.

The project management tool Trac [4] is used by the Zentyal Development Team to manage bugs and other tasks. It lets users open tickets to report problems and it is open to all users. Once the ticket is created by a user, its state can be tracked by the user through the web or e-mail. You may reach Zentyal Trac at http://trac.zentyal.org.

[4]Trac: is an enhanced Viki and issue tracking system for software development projects http://trac.edgewall.org.

It is highly recommendable to report a bug when you are fairly sure that your problem is really a bug and not just an expected result of the program under determined circumstances.

To report a bug, check first in the Trac if the bug was reported already. If not, report the bug via the Zentyal web interface (if the crash appears there) or manually via the Zentyal bug tracker. If the bug was reported already, you can still help by confirming that you have reproduced it and giving additional details about the issue.

It is absolutely necessary to include detailed steps to reproduce the issue so that the Zentyal Development Team can fix it. If you are reporting manually, include at least the /var/log/zentyal/zentyal.log file or any other useful information you think it’s related with your issue. Screenshots are also welcome if you think they will help to see the problem.

Finally, it is even better if you can provide a solution to the issue. This could be done by modifying the application itself through a patch or by following some steps to avoid the problem temporarily (workaround).

Patches and security updates

A patch is a modification in the source code used to fix a bug or add a new feature to that software. In open source projects, community members are able to send patches to the project maintainers and if the patches are considered suitable, then they will be merged into the application.

Developers themselves often publish official patches too, for example, fixing a known vulnerability. But, typically, projects like Zentyal, release a new version of the package - including the official patch.

You can check out the available community updates and install them using the web interface through the software module [5]. If you have a commercial server subscription [6], quality assured software updates will be automatically applied to your Zentyal server to guarantee your installation with maximum security and uptime.

[5]Software updates section shows this module in depth.
[6]http://www.zentyal.com/services/subscriptions/

Technical support

Open source software projects usually provide technical support to the users through different methods. Zentyal is not an exception.

You must distinguish between two kinds of support: the support provided to and by the community, which is free, and the commercial support, provided by companies that charge a fee for their services.

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 [7], although mailing lists [8] and IRC channels [9] are also available.

[7]http://forum.zentyal.org
[8]http://lists.zentyal.org
[9]irc.freenode.net server, #Zentyal (English) and #Zentyal-es (Spanish) channels.

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

Commercial support

The commercial support allows the user access to obtain support as a professional service. Unlike community support, the commercial support offered by Zentyal Development Team or Authorized Zentyal Partners offers several guarantees:

  • Maximum response time: depending on the service package the response time will be different.
  • Support from well-trained professionals backed by the Zentyal Development Team.
  • Additional features which add value to the product and are not available to the community.

In addition to this, commercial support ensures no time is wasted trying to find out what hardware you should purchase, what modules you should install, how to make the initial configuration, how to integrate Zentyal with existing systems, etc. These advantages are pretty clear for companies whose business relies on this software.