eBox developers guide

This guide is written for developers interested in writing new modules with new features for eBox, and for those who need to change or extend the base eBox framework.

eBox is written in perl and is mostly object-oriented. It is assumed that readers know how to write object oriented programs in perl. Some features of the language or the libraries used in eBox may be discussed, but no attempt has been made to document those aspects throughly.

Some experience writing object oriented applications and using design patterns in any language should be useful, but you should be fine just with the basic concepts of object oriented programming.

An effort has been made to provide examples for all aspects of eBox development explained in this guide. Most of them come straight from existing and working modules. Furthermore, a complete module is developed step by step in Chapter 8. It's a real module so that chapter should cover all the parts of a complete and working module.

eBox is a platform for the development and deployment of security and work-group related services on a local network. It is configured through a web interface that integrates all services in a consistent and easy to use way. Its goal is to be usable by non-experts.

eBox is meant to be installed on a dedicated machine, all configuration tasks are performed through the eBox web interface. This means that the configuration of the underlying services is one-way: eBox modules generate configuration files, overwriting system files in some cases (although that tends to be avoided if possible) and manual changes to those files are not detected by eBox. This simplifies the implementation and usage of the package but has the disadvantage that developers need to be careful if they use their own system for testing purposes.

eBox design is modular, new modules providing new services and features can be developed independently from its core package. eBox simplifies the deployment of new modules and the updates of existing ones with a software management module, which is also independent from the eBox base package.

The system is based on Linux and has been developed on top of Debian, no support is provided for other Linux distributions as there are some "debianisms" in some of the modules. Porting to other Linux distributions should be quite easy, and porting to other Unix like operating systems such as OpenBSD would take a little more work but it should still be doable, and worth it.

eBox is based on a few software packages, which are used for several purposes:

The base eBox package provides a development framework for new modules. By using this framework modules automatically get features like configuration backups and reversion of changes in the configuration before they are saved. The features available to module developers will be explained in detail in later chapters.

A few conventions are used throughout this guide regarding several concepts:

Booleans. Whenever we need to talk about a boolean value passed to a method or returned by it, we will refer to a true value as true and to a false value as undef or false.

Perl modules and eBox modules. There may be some confusion in some parts of the guide about the term module as the term may refer to an eBox module or a perl module. An eBox module is the complete set of classes (and perl modules) and other files that provide a self-contained functionality for eBox and that may be installed or uninstalled independently from the rest of eBox. A perl module is basically a perl source file.

Whenever there is no possibility of confusion, we'll just write module, otherwise we'll write explicitly perl module since this meaning will be the one used less frequently.

The typical eBox module handles the configuration of a daemon, possibly integrated with other eBox modules. The developer decides in what ways should the user be able to configure the daemon, this ways do not necessarily map directly to the daemon configuration options on a one-to-one relationship. The developer may pick a sane default value for most of the options and hide them from the user, showing him just the ones that he feels are important. Even further, an option changed by the user through the web interface may cause configuration changes in several real configuration options or even on several eBox modules. The main goal is to have an user interface as simple, easy to use, and integrated as possible, while providing the user with a rich set of features.

However, there may be modules that do not handle the configuration of a network service. An example is the 'sysinfo' module in the base system, it just gathers system information to be shown in the Summary page and provides a few menu entries for features that do not belong to any module in particular. The module parent class defines several abstract methods that real modules are free to leave unimplemented. Thus, a module may just provide info in the Summary, add new menu items, handle a network service or all of the above.

The normal, and most interesting, case is the module described in the first paragraph. Such a module has three parts.

This separation between the GUI and the backend opens the possibility for other means of changing the configuration. One such means is through perl scripts, these is useful when making packages for a distribution, the package maintainer can write a simple script to import the current system configuration into eBox, or set up some default values. Another use of the API is for other modules, the firewall module is the most used case, almost all modules need tell the firewall to open some port for them. In the future a wrapper may be written around these APIs to publish them through web-services, this would make eBox configurable programmatically over the network.

Besides these three parts, the module has some other minor parts, like its piece of the summary page in the web interface, menu entries, dependency declarations, backups of configuration pieces not stored in GConf, etc.

That's all there is to it, creating a module is as simple as following these steps:

The size and complexity of a module depends directly on the complexity of the service involved and the amount of configuration items exposed to the user. The necessary work to make a small eBox module is minimal, take the DNSCache module as an example, its CGIs add up to 49 lines of code and the module itself is 134 lines long.

The directory structure of an eBox module may look quite complex for a newcomer. A usual eBox module directory should look like this:

AUTHORS     configure.ac  INSTALL     Makefile.am  README   stubs/
autogen.sh  COPYING       NEWS        schemas/     tools/   ChangeLog
debian/     m4/           po/         src/         www/     migration/
		

The more important directories are src/, schemas/, www/, stubs/ and migration/.

The src/ directory contains the source code for the module. Inside this directory two directories can be found: EBox and templates. The EBox directory contains the Perl source code files, including a CGI subdirectory with the web frontend for the module. The templates directory is used to store the Mason templates, which will be used to generate the HTML output.

The schemas/ directory contains gconf schemas, used to define the configuration schemas for modules, and optionally provide default values for some options.

The www/ directory contains images and stylesheets that will be used in the web frontend.

The stubs/ is used to store Mason templates to generate configuration files for the module services.

The migration/ stores the migration perl scripts to upgrade from an eBox module version to a newer one.

Bear Section 1.4 in mind, a new way to develop eBox modules have been developed. It relies on Model-View-Controller design pattern, which an architectural pattern used in large software projects to decouple highly data (model) and user interface (view) so that developer can change the data architecture wihout changing the user interface and vice versa. A new component is added, the controller, which manages data access and business logic acting as an intermediate between them.

Thus with our new architecture the eBox MVC conception will be the following:

In Chapter 7, there is a large explanation about how it works internally. Below we are only going to introduce the main components which an eBox developer requires to know to build up an eBox MVC's module.

A basic MVC based module should have, at least, these three main parts:

sub _table
{
    my @tableHead = 
        ( 

            new EBox::Types::Text
                            (
                                'fieldName' => 'name',
                                'printableName' => __('Name'),
                                'size' => '12',
                                'unique' => 1,
                                'editable' => 1
                             ),
            new EBox::Types::HasMany
                            (
                                'fieldName' => 'members',
                                'printableName' => __('Members'),
                                'foreignModel' => 'MemberTable',
                                'view' => '/ebox/Object/View/MemberTable',
                                'backView' => '/ebox/Object/View/MemberTable',
                                'size' => '1',
                             )

          );

    my $dataTable = 
        { 
            'tableName' => 'ObjectTable',
            'printableTableName' => __('Objects'),
            'automaticRemove' => 1,
            'modelDomain' => 'Objects',
            'defaultActions' => ['add', 'del', 'editField' ],
            'tableDescription' => \@tableHead,
            'class' => 'dataTable',
            'help' => __('Objects'),
            'printableRowName' => __('object'),
        };

    return $dataTable;
}
        

sub _table
{
    my @tableHead = 
        ( 

            new EBox::Types::Text
                            (
                                'fieldName' => 'name',
                                'printableName' => __('Name'),
                                'size' => '12',
                                'unique' => 1,
                                'editable' => 1
                             ),
            new EBox::Types::IPAddr
                            (
                                'fieldName' => 'ipaddr',
                                'printableName' => __('IP Address'),
                                'editable'      => 1,
                            ),
            new EBox::Types::MACAddr
                            (
                                'fieldName' => 'macaddr',
                                'printableName' => __('MAC Address'),
                                'editable'      => 1,
                                'optional' => 1
                            ),


          );

    my $dataTable = 
        { 
            'tableName' => 'MemberTable',
            'printableTableName' => __('Members'),
            'automaticRemove' => 1,
            'defaultActions' => ['add', 'del', 'editField' ],
            'modelDomain'    => 'Objects',
            'tableDescription' => \@tableHead,
            'class' => 'dataTable',
            'help' => __('Objects'),
            'printableRowName' => __('member'),
        };

    return $dataTable;
}
        

sub _table
  {

      my @tableDesc =
        (
         new EBox::Types::Text(
                               fieldName     => 'server',
                               printableName => __('Jabber server name'),
                               size          => 12,
                               editable      => 1,
                              ),
         new EBox::Types::Int(
                              fieldName     => 'port',
                              printableName => __('Port'),
                              size          => 6,
                              editable      => 1,
                              defaultValue  => 5222,
                             ),
         new EBox::Types::Text(
                               fieldName     => 'user',
                               printableName => __('Jabber user name'),
                               size          => 12,
                               editable      => 1,
                              ),
         new EBox::Types::Password(
                                   fieldName     => 'password',
                                   printableName => __('User password'),
                                   size          => 12,
                                   editable      => 1,
                                   minLength     => 4,
                                   maxLength     => 25,
                                  ),
         new EBox::Types::Boolean(
                                  fieldName      => 'subscribe',
                                  printableName  => __('Subscribe'),
                                  editable       => 1,
                                 ),
         new EBox::Types::Text(
                               fieldName     => 'adminJID',
                               printableName => __('Administrator Jabber Identifier'),
                               size          => 12,
                               editable      => 1,
                              ),
        );

      my $dataForm = {
                      tableName          => 'JabberDispatcherForm',
                      printableTableName => __('Configure Jabber dispatcher'),
                      modelDomain        => 'Events',
                      tableDescription   => \@tableDesc,
                      class              => 'dataForm',
                      help               => __('In order to configure the Jabber event dispatcher ' .
                                               'is required to be registered at the chosen Jabber ' .
                                               'server or check subscribe to do register. The administrator ' .
                                               'identifier should follow the pattern: user@domain[/resource]'),
                     };

      return $dataForm;

  }
          

sub _description
  {

      my $description =
        {
         components      => [
                             'EnableForm',
                             'ConfigurationComposite',
                            ],
         layout          => 'top-bottom',
         name            => 'GeneralComposite',
         printableName   => __('Events'),
         compositeDomain => 'Events',
         help            => __('Events module may help you to make eBox ' .
                               'inform you about events that happen at eBox ' .
                               'in some different ways'),
        };

      return $description;

  }
        

sub models {
       my ($self) = @_;

       return [
               $self->configureLogModel(),
               $self->forcePurgeModel(),
              ];
}

sub composites
  {

      my ($self) = @_;

      return [
              $self->_configureLogComposite(),
             ];

  }
        

[
 {
  'order' => undef,
  'plainValueHash' => {
                       'members' => {
                                     ...
                                    },
                       'name' => 'RRHH',
                       'id' => 'x6666'
                      },
  'valueHash' => {
                  'members' => bless( {
                                       ...
                                      }, 'EBox::Types::HasMany' ),
                  'name' => bless( {
                                    'unique' => 1,
                                    'value' => 'RRHH',
                                    'printableName' => 'Name',
                                    'model' => $VAR1->[0]{'valueHash'}{'members'}{'model'},
                                    'HTMLSetter' => '/ajax/setter/textSetter.mas',
                                    'optional' => 0,
                                    'size' => '12',
                                    'row' => $VAR1->[0],
                                    'editable' => 1,
                                    'type' => 'text',
                                    'HTMLViewer' => '/ajax/viewer/textViewer.mas',
                                    'fieldName' => 'name'
                                    }, 'EBox::Types::Text' )
                 },
  'values' => [
               $VAR1->[0]{'valueHash'}{'name'},
               $VAR1->[0]{'valueHash'}{'members'}
              ],
  'id' => 'x6666',
  'printableValueHash' => {
                           'members' => {
                                         'model' => 'MemberTable',
                                         'values' => [
                                                      {
                                                      'macaddr' => undef,
                                                      'name' => 'Claudia',
                                                      'id' => 'memb44',
                                                      'ipaddr' => '192.168.1.92/32'
                                                      }
                                                     ],
                                         'directory' => 'objectTable/keys/x6666/members'
                                        },
                           'name' => 'RRHH',
                           'id' => 'x6666'
                         },
  'readOnly' => 0
  },
];

        

{
 'members' => {
               'model' => 'MemberTable',
               'values' => [
                            {
                             'macaddr' => undef,
                             'name' => 'Claudia',
                             'id' => 'memb44',
                             'ipaddr' => '192.168.1.92/32'
                            }
                           ],
               'directory' => 'objectTable/keys/x6666/members'
              },
 'name' => 'RRHH',
 'id' => 'x6666'
}
        

The EBox::Global class offers various module management functions. The most commonly used functions are those regarding module instantiation. EBox::Global works as a module factory, you get an instance of it using the getInstance static method and then you can use that instance to create modules. The factory comes in two flavors, a read-only flavor and a read-write one.

Calling getInstance without arguments will yield a read-write factory, which creates modules that let you make calls which change the configuration. A very important detail of read-write modules is that they return their latest configuration information, even if it has not been saved (which means that it could be revoked later by the user). This idea is important, configuration info reported by a read-write module should not be treated as final, unless that module has no changes waiting to be saved. You can see if a module has unsaved changes by calling the modIsChanged method in the EBox::Global class.

The idea behind the read-write modules behavior is to make it easy to build a configuration front-end. For example, if the user creates a new network object in the objects module, the new object will show up instantly in the firewall configuration, so he can create new firewall rules that use it. After all the desired changes have been made, the user saves the configuration. If he decides to cancel the changes he just made, both the new object and the firewall rules will be deleted.

There is one situation when you don't want to get information that has not been saved yet. That's when you are generating the configuration file for a daemon, setting up firewall rules, setting the address for a network interface, or any other activity that needs the real, final configuration info. This situation happens in system scripts (the boot script, cron jobs, etc). In these cases you need what we call read-only modules, they only report saved information and they do not allow method calls that change the configuration of the module. To obtain read-only modules you create EBox::Global instance setting its readonly parameter to true. Module instances returned by a factory created in this way will be read-only ones. This script shows how to get an instance of the squid module and tell it to restart itself:

#!/usr/bin/perl

use strict;
use warnings;

use EBox;
use EBox::Global;
use Error qw(:try);

EBox::init();

my $global = EBox::Global->getInstance(1);
my $squid = $global->modInstance('squid');

try {
	$squid->restartService();
} catch EBox::Exceptions::Base with {
	print STDERR "Squid module failed to restart.\n";
};

There are two functions that make it easy to perform two common tasks: getting an instance of every module and getting and instance of every module that implements some abstract class. These are modInstances and modInstancesOfType. Using them is straight forward:

my $global = EBox::Global->getInstance(1);

# restart all modules
foreach my $mod (@{$global->modInstances()}) {
	$mod->restartService();
}

# restart only modules that implement the NetworkObserver class
foreach my $mod (@{$global->modInstancesOfType('EBox::NetworkObserver')}) {
	$mod->restartService();
}

Restarting all the modules is even easier than that, EBox::Global provides the restartAllModules just for that. It's one of the methods that perform an operation on all the installed modules:

All error handling in eBox is implemented with java-style exceptions. These are provided by the perl module Error, you can check the perl documentation for that module for a detailed description on how to use exceptions in perl. eBox exceptions are defined in the EBox::Exceptions namespace.

eBox provides a hierarchy of exceptions from which you can choose the most appropriate for each situation. All eBox exceptions inherit from one of these two exceptions:

The difference between these two kinds is what the user will see when an uncaught exceptions occurs. The user interface framework will show the message contained in the exception unaltered if the exception is an external one. You should use external exceptions for user induced errors, like a syntax error in an IP address given by the user interface to the module backend.

If the exception is internal it will log the error and assume something is wrong internally in eBox (a bug) or in the system in general. When an internal exception is caught by the GUI framework the user will see a generic error message, recommending him to check the system logs or seek technical support. Any exception, internal or external, may be used internally for other purposes, as long as it is caught before it goes all the way up to the GUI framework.

The internal exceptions developed are:

The external exceptions developed are:

If you can't find an exception for certain error condition, you have two options: create a new exception class, inheriting from either EBox::Exceptions::External or EBox::Exceptions::Internal, or just use one those two classes as generic exceptions:

if ($foo_condition) {
	throw EBox::Exceptions::Internal('Something happened!');
}

As you can see, throwing exceptions follows a syntax very similar to Java's. Catching them is very similar too:

use Error qw(:try);

sub foo
{
	my $bar = shift;

	try {
		$bar->doSomething();
	} catch EBox::Exceptions::Base with {
		# do nothing, just ignore the error
	};
}

You can do whatever you like inside the “catch” clause. You may also write several “catch” clauses if you need to do different things for different exception types. “otherwise” and “finally” clauses are also allowed, for a detailed explanation about them just run perldoc Error. A very important detail is not to forget the semicolon after the last clause (the “catch” in the example), failing to do so may produce very weird results, this is due to the black magic that is used in the implementation of the try-catch idiom.

It is very important that every function exposed by each module validates its input data correctly. All of the arguments need to be checked, if this wasn't done a module could save syntactically wrong values in its configuration, and the underlying service would behave in an unpredictable way with the configuration file generated by the module. This also helps find bugs in the GUI front-end, and any other code that uses the module.

The EBox::Validate perl module provides a bunch of functions to validate different types of data. All of this functions work the same way, their first argument is the value that's going to be checked. They return true if the value is correct, undef if it's not:

use EBox::Validate qw(:all);

my $ip = '192.168.0.1';

unless (checkIP($ip))
	print STDERR "$ip is invalid.\n";
}

The usual thing to do if an argument is incorrect is to throw an exception. And most of the time the incorrect value will be an user-supplied one. For this reasons, all the functions in EBox::Validate provide an easy mechanism for throwing EBox::External exceptions. All you have to do is pass one more argument to them, with a name or description for the value you are trying to check. If you pass that argument and the validation fails, an exception will be thrown with a message indicating the name of the wrong field:

checkIP($ip, 'IP address');

If you don't want an exception to be thrown, or if you want to throw a different kind of exception, just do not pass the last argument and handle the error yourself.

eBox uses gettext, the GNU project's internationalization (i18n) platform. It makes it easy for translators to translate the eBox user interface into their own language.

This section describes i18n from the point of view of both the developer (what steps must be taken to build a translatable module) and the translator (how to translate eBox into a new language).

print __("Hello world");
			

print __("Edit ") . $group . __(" members"); # wrong
			

print __x("Edit {group} members", group => $group); # right
			

my $options = [__n('Foo'), __n('Bar'), __n('Foobaz') ]; # As many as you want
print __($options[$index]);
			  

# translated string
msgid "Name"
msgstr "Nombre"

# fuzzy string
#, fuzzy
msgid "Interfaces"
msgstr "Interface"

# untranslated string
msgid "External"
msgstr ""
			

msgid "Edit {group} members"
			

msgstr "Editar miembros de {group}"
			

All eBox modules inherit from the EBox::Module class, this class defines abstract methods that modules may override to implement certain functionality. These methods are called by the framework when they are needed.

Besides those abstract methods, the class implements a few methods, providing some basic functionality. These methods often follow the template method design pattern, they perform some operation but delegate some part of it on some abstract method that may be implemented by child classes.

Finally, there are a few methods that implement some common operations that get used in most of the modules, these are meant to be called by children classes when they need them. They are located in the EBox::Module class just for convenience.

sub _create
{
	my $class = shift;
	my $self = $class->SUPER::_create(name => 'dhcp',
					domain => 'ebox-dhcp',
					@_);
	bless ($self, $class);
	return $self;
}

The apache server under which eBox runs, and any Perl script that uses the eBox API run under a dedicated user id, the user is typically called “ebox”. eBox modules need to execute certain commands and write certain files with root privileges, this is done using sudo

You can invoke any command using the root() function within the EBox::Sudo Perl module. If the command fails, root() throws an EBox::Exceptions::Sudo::Command exception, so make sure you catch it if it is OK for the command to fail or if you want to inform the user in a different way. Anyway, you can use the output, error and exitValue exception methods to gather more information about the command failure. In the rare cases when the sudo program itself fails the exception raised is one of the EBox::Exceptions::Sudo::Wrapper kind and the last methods are not available.

try {
  EBox::Sudo::root("/usr/bin/eject -t");
}
catch EBox::Exceptions::Sudo::Wrapper with {
  throw EBox::Exceptions::Internal("sudo program failed");
}
catch EBox::Exceptions::Sudo::Command with {
  my ($ex) = @_;
  EBox::debug("/usr/bin/eject failed. Stderr was " . (join "\n", @{ $ex->error() })) ;
  throw EBox::Exceptions::External("Cannot close CD-ROM tray. Please close it manually" );
}

EBox::Sudo also provides wrappers for frequent used commands executed with root privileges. stat provides a statistic wrapper, useful to get file system information for any file. If you need a more concise file information you can use fileTest to check files for simples queries like /usr/bin/test does.

eBox uses GConf to store its configuration, the development framework provides a wrapper around the original perl bindings. GConf gives us an easy API for storing and retrieving typed configuration values organized hierarchically. It also lets us define limited schemas for certain configuration keys, setting their type and default values.

The development framework defines a wrapper around the GConf API that provides some extra features. The wrapper is implemented as child class for EBox::Module, so all modules that want to use GConf inherit from EBox::GConfModule. Its children automatically get these features:

This is a list of the most important methods in EBox::GConfModule:

Let's see some examples from the above functions.

 $self->set_string("printers/x4235/name", "fooprinter"); 

$self->set_list('foo/foolist', 'string', ['foo', 'bar']);

my $id = $self->get_unique_id('p', 'printers');
$self->set_string("printers/$id/name", $name);
$self->set_bool("printers/$id/configured", undef);
		

The need to keep certain information ordered is fairly common across eBox modules. It is also common to provide reordering functions. An example of this are firewall rules, which need to be applied in a given order, and the user has to be able to change their order. The EBox::Order class solves just this problem.

The idea is to give a directory to each item you want to keep ordered. Following the firewall example, we could have a rules/ directory and, below it, one directory per rule. Each rule would get a unique identifier, and that would be its directory name below rules/. A rule with id r3561 would be stored in rules/r3561, and below that directory we would store keys with each one of the rule's parameters. This is the most natural way of organizing items such as firewall rules, and it is with this organization that EBox::Order is designed to work.

The ordering mechanism adds one field to the items being ordered. Not surprisingly it is called order. To use the ordering API you have to create an EBox::Order instance. Its constructor takes to arguments: the instance of the module that owns the items being ordered, and the base directory where the items are stored.

EBox::Order implements these operations:

sub _fwdRulesOrder
{
	my $self = shift;
	return new EBox::Order($self, "fwdrules");
}

sub _fwdRuleNumber # (rule)
{
	my ($self, $rule) = @_;
	return $self->get_int("fwdrules/$rule/order");
}

my $order = $self->_lastFwdRule() + 1;

$self->set_string("fwdrules/$id/name", $id);
$self->set_string("fwdrules/$id/action", $action);
$self->set_bool("fwdrules/$id/active", 1);
$self->set_int("fwdrules/$id/order", $order);

sub _lastFwdRule
{
	my $self = shift;
	my $order = $self->_fwdRulesOrder();
	defined($order) or return 0;
	return $order->highest;
}

sub FwdRuleUp # (rule)
{
	my ($self, $rule) = @_;
	my $order = $self->_fwdRulesOrder();
	defined($order) or return;
	my $num = $self->_fwdRuleNumber($rule);
	if ($num == 0) {
		return;
	}
	my $prev = $order->prevn($num);
	$order->swap($num, $prev);
}

Besides exposing an API that allows reading and changing the configuration of a given service, a module's backend is in charge of making that service work. Typically, the service will be some sort of daemon that offers some functionality across the network after reading a configuration file. So your module needs to generate the configuration file and start/stop/restart the daemon at the right times.

Stubdir = @STUBSPATH@/dns-cache

nobase_Stub_DATA = named.conf.mas named.conf.options.mas \
	named.conf.local.mas

EXTRA_DIST = $(nobase_Stub_DATA)

MAINTAINERCLEANFILES = Makefile.in

my $self = shift;
my @array = ();
my @servers = $self->servers;
my $synch = 'no';
my $active = 'no';

($self->synchronized) and $synch = 'yes';
($self->service) and $active = 'yes';

push(@array, 'active'   => $active);
push(@array, 'synchronized'  => $synch);
push(@array, 'servers'  => \@servers);

$self->writeConfFile(NTPCONFFILE, "ntp/ntp.conf.mas", \@array);

				

<%args>
	$active
	$synchronized
	@servers
</%args>	
# /etc/ntp.conf, configuration for ntpd
# Generated by EBox

driftfile /var/lib/ntp/ntp.drift
statsdir /var/log/ntpstats/

% if ($synchronized eq 'yes') {
%	if ($servers[0]) {
server <% $servers[0] %>
%	}
%	if ($servers[1]) {
server <% $servers[1] %>
%	}
%	if ($servers[2]) {
server <% $servers[2] %>
%	}
% }
% if ($active eq 'yes') {
server 127.127.1.0
% }
fudge 127.127.1.0 stratum 13

restrict default kod notrap nomodify nopeer noquery

restrict 127.0.0.1 nomodify

				

sub _regenConfig
{
	my $self = shift;
	$self->_setBindConf;
	$self->_doDaemon();
}

sub _doDaemon
{
	my $self = shift;

	if ($self->service and $self->pidFileRunning(PIDFILE)) {
		$self->_daemon('reload');
	} elsif ($self->service) {
		$self->_daemon('start');
	} elsif ($self->pidFileRunning(PIDFILE)) {
		$self->_daemon('stop');
	}
}

sub _daemon # (action)
{
	my ($self, $action) = @_;
	my $command = BIND9INIT . " " . $action . " 2>&1";

	if ( $action eq 'start') {
		root($command);
	} elsif ( $action eq 'stop') {
		root($command);
	} elsif ( $action eq 'reload') {
		root($command);
	} else {
		throw EBox::Exceptions::Internal(
			"Bad argument: $action");
	}
}

sub _stopService
{
	my $self = shift;

	if ($self->pidFileRunning(PIDFILE)) {
		$self->_daemon('stop');
	}
}

As we pointed out earlier, all changes made on the keys stored in gconf are automatically backed up the first time a write or delete operation is carried on. Consequently, all these changes could be restored automatically if the user wishes to dismiss or restore them from a file.This is actually true as long as you use the methods provided by EBox::GConfModule to do so.

If your module has at least some part independent from GConf, it must override methods dumpConfig and restoreConfig.

Additionally, apart from module configuration if you want to add some other data concerned to the module which comprise user files, log content and so on; it must implement the methods extendedBackup and extendedRestore. Remember all these information will just save and restore whether user requests it explicitly. Let's show how with an example:

sub dumpConfig
{
  my ($self, $dir) = @_;
 
  $self->{ldap}->dumpLdapData($dir);
}


sub restoreConfig
{
  my ($self, $dir) = @_;

  $self->{ldap}->loadLdapData($dir);
}

ebox-logs module is intended to administer eBox logs. We wish to have the chance to back up its contents. As module configuration does not include these data, we are going to use extendedBackup and extendedRestore. Remember that this kind of data is only stored if user chooses it.

sub extendedBackup
{
  my ($self, %params) = @_;
  my $dir    = $params{dir};
  
  my $dbengine = EBox::DBEngineFactory::DBEngine();
  my $dumpFile = "$dir/eboxlogs.dump";

  $dbengine->dumpDB($dumpFile);
}


sub extendedRestore
{
  my ($self, %params) = @_;
  my $dir    = $params{dir};

  my $dbengine = EBox::DBEngineFactory::DBEngine();
  my $dumpFile = "$dir/eboxlogs.dump";

  $dbengine->restoreDB($dumpFile);
}

		  

eBox can log every change made through its administrative interface, which is useful to know when something was changed or who changed it. Every eBox module should report every log message to give a comprehensive administrative logging support.

In order to do so, you must include a new package from eBox core EBox::LogAdmin in your module.

use EBox::LogAdmin qw ( :all );

A new module attribute named title is used, you must add it to the create call. For instance:

my $self = $class->SUPER::_create(name => 'objects',
                    title => __n('Objects'),
                    domain => 'ebox-objects',
                    @_);

Furthermore, a hash is needed in the constructor with the actions your module will report with a nicely formatted message. Following the same example in EBox::Objects module:

$self->{'actions'} = {};
$self->{'actions'}->{'addObject'} = __n('Added object {object}');
$self->{'actions'}->{'addToObject'} =
        __n('Added {name} ({ip}/{mask} [{mac}]) to object {object}');
$self->{'actions'}->{'removeObject'} = __n('Removed object {object}');

	    

For each action you want to log, which should be everything that can be done from web interface, you should follow these steps: