Development and advanced configuration¶
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::Users::User;
EBox::init();
my $parent = EBox::Users::User->defaultContainer();
open (my $USERS, 'users.csv');
while (my $line = <$USERS>) {
chomp ($line);
my ($username, $givenname, $surname, $password) = split(',', $line);
EBox::Users::User->create(
uid => $username,
parent => $parent,
givenname => $givenname,
surname => $surname,
password => $password
);
}
close ($USERS);
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.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 ./bulkusers
This 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.
Stubs¶
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/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
For 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" {
192.168.200.0/24;
192.168.201.0/24;
};
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
Hooks¶
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:
#!/bin/bash
iptables -t nat -I premodules -s 192.168.200.0/24
-p tcp -m tcp --dport 80 -j ACCEPT
after that, you will give execution permissions to the file and restart the service:
sudo chmod +x firewall.postservice
sudo service zentyal firewall restart
These options have great potential and allow highly customizable Zentyal operations.
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.
You can follow the development tutorial [3] to get started with some code examples.
| [2] | http://en.wikipedia.org/wiki/Model_View_Controller. |
| [3] | http://trac.zentyal.org/wiki/Documentation/Community/Document/Development/Tutorial |
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.
Commercial Editions Release Policy¶
Commercial Editions release cycle will be extended to 24 months and solely shipped with the most recent version of Ubuntu server LTS available during the development phase. The schedule has nevertheless been chosen on purpose and will always supply the latest version of Ubuntu Server LTS (Long-Term Support) with Zentyal. With this change, partners and end customers will benefit from an extended product lifetime close to 4 years and a half instead of 3 years support as of today.
Commercial editions will benefit from security updates and bug fixing through Q/A PPA repositories. Furthermore software updates and additions will be provided within Service Packs and delivered through this same PPA. This is one of the major updates of this release strategy: Zentyal intends to provide better quality and stabilized softwares to its paying customers, reducing the overall risk of high or critical issues one’s user may encounter. This achievement will be reached through a new software inclusion process to be detailed in feature addition section.
Community Edition Release Cycle¶
Community Edition release cycle will be shorten to 3 months and always shipped with the most recent version of Ubuntu standard release available prior the beginning of the development phase. The general release cycle of Community edition is linked to commercial one. First of all, community edition is now de facto the laboratory where new experimentations and features are first being deployed. It is next processed as part of extensive beta testing cycles and finally get stabilized. It is only when a feature is stabilized in the community edition that it can be back ported to commercial one. Secondly, community edition will gradually upgrade to new Ubuntu standard releases whenever available, aiming at offering an overall better consistency and stability to paying customer upon new commercial release. This methodology helps reducing paths to inconsistencies across different LTS versions (new software version or operating system internals updates) and provide longer and better quality assurance testing and updates. The upgrade path from one Ubuntu release to the next one is shorten, reducing the effort required to bridge the gap.
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 wiki 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.
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 [5], although mailing lists [6] and IRC channels [7] are also available.
| [5] | http://forum.zentyal.org |
| [6] | http://lists.zentyal.org |
| [7] | 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).
Configuration Keys¶
Zentyal allows you to configure most of the functionality through the web interface, but you can also configure advanced aspects of some services using the files in /etc/zentyal.
Basic instructions to modify these .conf files are explained at the beggining of each file
Captive Portal:
/etc/zentyal/captiveportal.conf
# Uncomment the following line to enable
# secondary LDAP configuration:
#captive_secondary_ldap = yes
COMMON
/etc/zentyal/zentyal.conf
# user [required]. The user under which Zentyal will run.
# It should have enough sudo privileges to perform all needed tasks.
user = ebox
#
# egroup [required]. The group under which Zentyal will run.
egroup = ebox
#
# debug mode [required]. yes|no
# Note: In order to take effect, after changing this you need to execute:
# /etc/init.d/zentyal apache restart
debug = yes
#
# Dump exceptions on interface
# This is useful for developers and is only enabled during beta period
#dump_exceptions = yes
Zentyal core:
/etc/zentyal/core.conf
# Redis server port
# If you change this value, you must manually restart the redis server
# in two steps:
# $ /etc/init.d/zentyal webadmin restart # write down the new configuration
# $ restart ebox.redis # restart the daemon
redis_port = 6380
#
# Ignore system updates in Dashboard widget
#widget_ignore_updates = yes
#
#Custom prefix for rebranding
#custom_prefix = zentyal
#
# Zentyal desktop services
# For changes in this configuration to take effect you must run:
# $ /etc/init.d/zentyal webadmin restart # write down the new configuration
desktop_services_enabled = yes
desktop_services_port = 6895
DNS:
/etc/zentyal/dns.conf
# Internal networks allowed to do recursive queries
# to eBox DNS caching server. Localnetworks are already
# allowed and this settings is intended to allow networks
# reachable through static routes.
# Example: intnets = 192.168.99.0/24,192.168.98.0/24
intnets =
#
# This key control the automatic reverse zone generation
# Set to 'no' to disable it
generate_reverse_zones = yes
#
# This key defines whether you want to sort the results based on the querying IP
# Uncomment it to enable it
# sortlist = yes
Backup:
/etc/zentyal/backup.conf
# Enable ebackup menu (yes or no)
ebackup_menu_enabled = yes
#
# Volume size in Mb (default: 25)
# If you are backing up to the local file system: choose 600 or
# greater in order to have less files
volume_size = 25
#
# temporal directory (default: /tmp)
temp_dir = /tmp
#
# archive directory (default: /var/cache/zentyal/duplicity)
# if you change this after the first run duplicity will have to recreate
# it again from the repository. The old one will not be automatically deleted.
archive_dir = /var/cache/zentyal/duplicity
#
# Retrying configuration
# This set of values are set when the uploading is done and some
# retries are required to complete the backup
# It follows a geometric progression:
# timeout_n = initial_value * scale_factor ^ (n-1)
# For instance, initial_value = 60s, scale_factor = 2, n_tries = 4
# The backup will be tried 4 times after 60s, 120s, 240s before giving up
# This value is set in seconds
initial_value=60
scale_factor=2
n_tries=4
#
# duplicity timeout
# default is 5 minutes, but you can uncomment this and set a different value in seconds
#duplicity_timeout = 300
#
# scheduled backup priority
# it should be a positive integer, range 0-19
# 0 is normal priority, a higher number is _less_ priority
ebackup_scheduled_priority=10
Firewall:
/etc/zentyal/firewall.conf
# Limit of logged packets per minute.
iptables_log_limit = 50
#
# Burst
iptables_log_burst = 10
#
# Logs all the drops
iptables_log_drops = yes
#
# Extra iptables modules to load
# Each module should be sperated by a comma, you can include module parameters
iptables_modules = nf_conntrack_ftp, nf_nat_ftp, nf_conntrack_h323, nf_nat_h323, nf_conntrack_pptp, nf_nat_pptp, nf_conntrack_sip, nf_nat_sip
#
# Enable source NAT, if your router does NAT you can disable it
nat_enabled = yes
#
# Uncomment the following to show the Rules added by Zentyal services
#show_service_rules = yes
IPS:
/etc/zentyal/ips.conf
# Set the IPS inline firewall rules position
# It is set 'behind' (default), then only accepted input or forwarded traffic
# will be analysed.
# It is set 'front', all input and forwarded traffic will be analysed. Although,
# this second option is more secure, it is high CPU consuming in those
# networks with high network traffic.
# If you modify this setting, then you must run the following commands
# to take effect (Order is important).
# $ sudo service zentyal ips restart
# $ sudo service zentyal firewall restart
# (Disable and enable IPS module is safer to avoid be locked out)
# ips_fw_position = front|behind
Network:
/etc/zentyal/network.conf
# interfaces to ignore in the interface
# (default: sit,tun,tap,lo,irda,ppp,virbr,vboxnet, vnet)
ifaces_to_ignore = sit,tun,tap,lo,irda,ppp,virbr,vboxnet,vnet
#
# If you want to define a custom mtu for any interface
# you can use mtu_<interface> = <MTU>. Example:
#mtu_eth0 = 1400
OpenVPN:
/etc/zentyal/openvpn.conf
# insecure_rip_conf [required]. If set to yes it will enable backwards
# compatibility with eBox openVPN which used an insecure ripd configuration.
# Do not enable it unless you are sure of what you are doing
insecure_rip_conf = no
#
# Use mssfix to fix MTU discovery problems in some networks with UDP connections
# It applies to all VPN clients
# Enable it only if you are sure what you're doing
# mss_fix = 1300
Zentyal Remote:
/etc/zentyal/remoteservices.conf
# Public DNS server
ebox_services_nameserver = ns.cloud.zentyal.com
#
# Public API
rs_api = api.cloud.zentyal.com
#
# Verify Cloud servers
# Values: yes | no
rs_verify_servers = yes
#
# If set to a 'yes' value, the Zentyal QA updates have priority and
# other packages sources have the lowest priority and they will not
# be used.
# If you change this value, you must run the following command:
# sudo /usr/share/zentyal-software/rewrite-conf
# (Default: yes)
qa_updates_exclusive_source = yes
#
# If set to a 'yes' value if the Zentyal QA updates are used, they will
# be automatic to ensure you have always a system updated from a
# trusted source.
# (Default: yes)
qa_updates_always_automatic = yes
#
# If set to a 'yes' value, the monitoring stats will be sent using the VPN
# This method is more secure, but tends to have service interruptions
# If you change this value, run /etc/init.d/zentyal monitor restart to get
# these changes taken
# (Default: no)
monitoring_inside_vpn = no
Samba:
/etc/zentyal/samba.conf
# -- s4sync settings --
s4sync_debug = yes
#
# -- File server --
# Choose the file server to use. The new 'ntvfs' included
# in samba4 or the old 's3fs' from samba3. Printers and
# vfs plugins such recycle bin, audit or antivirus will not
# work if you choose 'ntvfs'.
# values: ntvfs | s3fs
samba_fs = s3fs
#
# -- Recycle Bin settings --
# Name of the recycle bin directory
# If a full path like /tmp/foo is entered,
# the same Recycle Bin will be used for all the shares
repository = RecycleBin
#
# Permissions of the recycle bin directory
directory_mode = 0700
#
# Keep directory structure
keeptree = Yes
#
# Keep copies if a file is deleted more than once
versions = Yes
# Specifies whether a file's access date should be updated
# when the file is moved to the repository.
#touch = Yes
#
# Files that are smaller than the number of bytes
# specified by this parameter will not be put into
# the repository.
#minsize = 0
#
# Files that are larger than the number of bytes
# specified by this parameter will not be put into
# the Recycle Bin. (0 = disabled)
maxsize = 0
#
# List of files that should not be stored when deleted,
# but deleted in the regular way.
#exclude = *.tmp|*.temp
#
# When files from these directories are deleted,
# they are not put into the recycle bin but are deleted
# in the regular way.
excludedir = /tmp|/var/tmp
#
# Specifies a list of paths
# (wildcards such as * and ? are supported)
# for which no versioning should be used.
# Only useful when versions is enabled.
#noversions = *.foo|*.bar
#
# -- End of Recycle Bin settings --
#
# -- antivirus settings --
#
# Whether sockets, devices and fifo's (all not scanned for viruses) should be visible to the user
show_special_files = True
#
# Whether files that are not visible (.scanned: files, .failed: files and .virus: files)
# should be deleted if the user tries to remove the directory. If false, the user will
# get the "directory is not empty" error.
rm_hidden_files_on_rmdir = True
#
# If false, all non-scanned files are visible in directory listings. If such files are found in a
# directory listing the scanning daemon is notified that scanning is required. Access to non-scanned
# files is still denied (see allow_nonscanned_files).
hide_nonscanned_files = False
#
# If non-scanned files are hidden (if scannedonly:hide_nonscanned_files = True), a fake 0 byte file
# is shown. The filename is the original filename with the message as suffix.
scanning_message = is being scanned for viruses
#
# If a non-scanned file is opened, the vfs module will wait recheck_tries_open times for
# recheck_time_open milliseconds for the scanning daemon to create a .scanned: file. For
# small files that are scanned by the daemon within the time (tries * time) the behavior
# will be just like on-access scanning.
recheck_time_open = 50
#
# See recheck_time_open.
recheck_tries_open = 100
#
# If a non-scanned file is in a directory listing the vfs module notifies the daemon (once
# for all files that need scanning in that directory), and waits recheck_tries_readdir times
# for recheck_time_readdir milliseconds. Only used when hide_nonscanned_files is false.
recheck_time_readdir = 50
#
# See recheck_time_readdir.
recheck_tries_readdir = 20
#
# Allow access to non-scanned files. The daemon is notified, however, and special files such
# as .scanned: files. .virus: files and .failed: files are not listed.
allow_nonscanned_files = False
#
# Number of threads used to scan files
scanning_threads = 4
#
# -- End of antivirus settings --
#
# Listen on external interfaces
listen_external = no
#
# Show in the UI the textbox to choose the site where
# the server should be added when joining a domain
show_site_box = no
#
# Uncomment this if you want to set ACLs manually and avoid
# Zentyal to overwrite them
#unmanaged_acls = yes
#
# Uncomment this if you want to sync also users with a disabled account
#sync_disabled_users = yes
#
# Disable full audit logging
# Allowed values = [yes|no]
# Default value = no
# If you want to disable full audit, then uncomment next option
#disable_fullaudit = yes
#
# This is a temporary workaround for these Samba 4 bugs:
# https://bugzilla.samba.org/show_bug.cgi?id=9866
# https://bugzilla.samba.org/show_bug.cgi?id=9867
# Uncomment this if you have guest shares enabled and want to join
# Windows Vista computers to the domain. Please note that completely
# anonymous share access will not work if you don't provide any valid
# domain credentials, but at least you will be able to join.
#join_vista_with_guest_shares = yes
#
# Uncomment this if you want to skip setting the home directory of the
# users while saving changes
#unmanaged_home_directory = yes
/etc/zentyal/s4sync-groups.ignore List of Samba Groups that won't be imported into LDAP
/etc/zentyal/sids-to-hide.regex List of SID's (in regular expressions) that will be hidden
Proxy:
/etc/zentyal/squid.conf
# cache_mem [required]. Amount of memory to be used by squid (in MB)
cache_mem = 128
#
# maximum_object_size [required]. Maximum object size to be cached (in MB)
maximum_object_size = 300
#
# max_fd if this value set the maximum number of file descriptors wil be
# increased if needed at squid's start. If not set it will not be changed.
#max_fd= 167140
#
group = proxy
#
## Performance tuning ##
# do not change if you really know what are you doing
# DansGuardian parameters
maxchildren = 120
minchildren = 8
minsparechildren = 4
preforkchildren = 6
maxsparechildren = 32
maxagechildren = 500
#
# load url lists from categorized lists, since they use a url_regex ACL type
# you can disable them in low-memory systems
load_url_lists = yes
#
# TAG: Authentication mode
# key: auth_mode
# This key controls the authentication mode for squid. When set to internal,
# squid autheticate against the Zentyal internal LDAP, when set to external_ad,
# squid authenticate users against an external Active Directory.
# values:
# - internal
# - external_ad (only for enterprise edition)
auth_mode = internal
#
# key: auth_ad_skip_system_groups
# When using external active directory auth dont allow ACLs
# with groups that has the attribute 'isSystemCriticalObject' set (almost all built-in)
auth_ad_skip_system_groups = no
#
# key: auth_ad_acl_ttl
# TTL in seconds for ACL cached results.
auth_ad_acl_ttl = 3600
Traffic Shaping:
/etc/zentyal/trafficshaping.conf - configuration file for zentyal-trafficshaping
# R2Q value for guaranteed valid values range. The values are
# calculated as follows:
#
# Maximum: 60000 * r2q * 8 / 1000
# Minimum: MTU * r2q * 8 / 1000
#
# More info at: http://www.docum.org/docum.org/faq/cache/31.html
r2q = 5
User Corner:
/etc/zentyal/usercorner.conf - configuration file for zentyal-usercorner
# user corner redis server port
redis_port_usercorner = 6381
Users:
/etc/zentyal/users.conf
# supported paswords formats: sha1, md5, lm, nt, digest (base64) and realm (hex)
# whether to create user homes or not
mk_home = yes
#
# default mode for home directory (umask mode)
dir_umask = 0077
#
# enable quota support
enable_quota = yes
#
# synchronization frequency with LDAP slaves
slave_time = 5
Zarafa:
/etc/zentyal/zarafa.conf
# where to store mail attachments: database | files
zarafa_attachment_storage = files
#
# path where to store attachments if set to files
zarafa_attachment_path = /var/lib/zarafa
#
# allow users send mail from other address different than their: no | yes
zarafa_always_send_delegates = no
#
# use zarafa-indexer
zarafa_indexer = no
#
# manage zarafa-licensed (needs zarafa-licensed package installed)
zarafa_licensed = no
#
# enable hosted zarafa
# note: this is not compatible with sso
zarafa_enable_hosted_zarafa = no