How to customize the configuration files generated by Zentyal

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!

10 Responses to “How to customize the configuration files generated by Zentyal”

  1.   bryan Says:


    I’ve just tried changing the samba profile and home paths by modifying smb.conf.mas. This worked.

    When I add a new user with the web interface it creates the folder in the wrong(default) directory.

    i’ll keep looking into the issue, but any help would be awesome.


  2.   jacalvo Says:

    I’m not sure if I fully understand you, but the path for the /home directories is hardcoded and cannot be changed editing the samba template.

    Best regards.

  3.   rocky Says:

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

    This solution seem to use the customized template forever, but it causes other issue: if the module get upgrade with new option/parameters in the original template, it will not take effect forever. E.g. Samba module upgrade with new template, and the server still use the old template for samba service which might miss some new features or not working well.


  4.   jacalvo Says:

    It is not common to modify a template once a stable version is released. If you upgrade to a new major version you should of course check if the templates have changed to merge your changes.

  5.   Aldrin Says:

    I really like Zentyal since I’m a newbie systems administrator. Zentyal allows me to easily administer production systems, and almost without using command line interface.

    However, my fellow systems administrators disagree with me in using Zentyal because of how Zentyal handles the default configuration files. They like to edit directly the configuration files because it’s what they’re familiar with. They don’t want to edit the ebox stubs files because it’s going to be a new learning for them, and it’s making them uncomfortable.

    Hence, I strongly suggest to the Zentyal team to change how Zentyal handles the configuration files. Edits in the default configuration files should also reflect in Zentyal’s web interface, as applicable.

    This is how Webmin works; edits in the default configuration files reflect in its web interface. This allows both novice & advanced systems administrators to use it & still have the same output.

    However, I still prefer using Zentyal over Webmin because Webmin uses unsupported Perl packages, which may cause unexpected issues. Zentyal is my benchmark of what a GUI in Ubuntu should be.

    Unfortunately, since I work with advanced systems administrators who don’t like to use Zentyal, I have to use other GUIs available which don’t work like how Zentyal works. This allows me & my colleagues to have the same output.

    I hope that the Zentyal team will change how Zentyal edits the configuration files soon so that both novice & advanced users can conveniently use it while still producing the same results.

    Linux is thought to be only for advanced users. Zentyal can change that mindset if you listen to Linux newbies like me. If Microsoft can make servers easy to use thru their user-friendly interfaces, Zentyal can also do it.

  6.   thinksimple Says:

    Hello, I’m just testing zentyal for myselfe. On my old server I’m using greyhole. (Driveextender)
    To use it, I need to add a special “command” too each share.
    Where can I do something like this in zentyal? I didn’t find the shares I created with the zentyal gui. …

  7.   stif Says:

    Is there a command to rewrite the original configuration file when finished editing the template?
    Otherwise i have to make the changes 2 times- to the original files and for the *.cfg.mas file

  8.   khamlichikhalil Says:

    just to share my experience, I had to edit :


    which is the file for generating smb.conf at each restart of the service.

    I added 3 lines to the global section :

    unix extensions = no
    follow symlinks = yes
    wide links = yes

    to allow following symlinks on a second hard drive.

  9. Says:

    sudo cp /etc/zentyal/hooks/template.postsetconf /etc/zentyal/hooks/samba.postsetconf



    ### Hook script ###
    nt acl support = Yes
    store dos attributes = yes
    inherit permissions = yes
    nt acl support = Yes
    acl check permissions = Yes
    acl map full control = Yes

    follow symlinks = yes
    wide links = yes

    hide dot files = yes
    hide files = .cloud

    cp $FILE $FILE.backup

    awk -v INSERT=”$INSERT” -F: “/$PATTERN/{print;print INSERT;next}1” $FILE.backup > $FILE

    Enjoy it!

  10.   Dave Cline Says:

    I am testing with your community edition (downloaded and installed this week) and am trying to update snort.conf. I first modified /etc/snort/snort.conf and of course it was overwritten after a restart. I then found and followed your instructions and modified the template instead, but for some reason it looks as if the template is not being used because after a reboot or service restart snort.conf is back to its original settings.

    Any other suggestions?



Leave a Reply