eBox developers guide

Esta guía está escrita para desarrolladores interesados en programar nuevos módulos con nuevas funcionalidades para eBox, y para aquellos que necesitan cambiar o extender la framework base eBox.

eBox está escrita en perl y está mayoritariamente orientada a objetos. Se asume que los lectores saben realizar programas orientados a objetos en perl. Muchas de las características del lenguaje o de las librerias usadas en eBox han sido comentadas pero no es nuestra intención el explicarlas profundamente.

Experiencia escribiendo aplicaciones orientadas a objetos y el uso de patrones de diseño en cualquier lenguaje te será de ayuda, pero deberías tener una buena base de los conceptos básicos de la programación orientada a objetos.

Nos hemos esforzado en esta guía en ofrecer ejemplos de todos los aspectos del desarrollo de eBox. Muchos de ellos vienen directamente de módulos existentes y funcionales. Además, en Capítulo 7 se desarrolla paso a paso un módulo completo. Es un módulo real asi que el capítulo debería cubrir todos los aspectos de un módulo completo.

eBox es una plataforma para el desarrollo y despliegue de servicios relacionados con la seguridad y trabajo en grupo para una red local. Es configurable a través de un interfaz web que integra todos los servicios de una manera consistente y fácil de usar. El objetivo es que pueda ser usada por personas no expertas.

eBox está orientada a instalarse sobre una máquina dedicada, todas las tareas de configuración son realizadas a traés de la interface web de eBox. Esto significa que la configuración de los servicios subyacentes es unidireccional: los módulos eBox generan ficheros de configuración, en algunos casos sobreescriben ficheros del sistema (aunque esto tiende a ser evitado en la medida de lo posible) y cambios a mano sobre esos ficheros no son detectados por eBox. Esto simplifica la implementación y uso del paquete pero tiene la desventaja de que los desarrolladores deben tener cuidado si usan su propio sistema para pruebas.

El diseño de eBox es modular, los nuevos módulos que proporcionan nuevos servicios y funcionalidades pueden ser desarrollados independientemente del paquete base. eBox simplifica el despliegue de nuevos módulos y la actualización de los ya existentes mediante un módulo de gestón de software, el cual es también a su vez independiente del paquete base eBox.

El sistema está basado en Linux y ha sido desarrollado sobre Debian, como hay algún "debianismo" sobre algún módulo, no se ofrece soporte sobre otras distribuciones Linux. Portar eBox a otras distribuciones Linux debería ser sencillo sobre otros sistemas operativos Unix como OpenBSD puede tomar un poco mas de trabajo pero debería seguir siendo factible.

eBox está basada en unos pocos paquetes de software, los cuales son usados para diferentes propósitos:

El paquete base de eBox ofrece una framework de desarrollo para nuevos módulos. Usando esta framework los módulos obtienen automáticamente características como backups de configuración y el descarte de los cambios efectuados en la configuración antes de se guardados. Todas las características disponibles para los desarrolladores de módulos serán explicados en detalle en los próximos capítulos.

Vamos a usar unas pocas convenciones a lo largo de esta guía sobre varios conceptos:

Booleanos. Cuando necesitemos hablar sobre un valor booleano pasado a un método o retornado por el, nos referiremos al valor true como true y al valor false como undef or false.

Módulos perl y módulos eBox. Puede haber cierta confusión en ciertas partes de la guía sobre el término module, puede referirse a un módulo eBox o a un módulo perl. Un módulo eBox es un set completo de clases (y módulos perl) y otros ficheros que ofrecen funcionalidades por si mismos para eBox y pueden ser instalados o desinstalados independientemente del resto de eBox. Un módulo perl es básicamente un fichero fuente perl.

Cuando no hay posibilidad de confusión, simplemente escribiremos módulo, de otro modo escribiremos explícitamente módulo perl ya que este término será el menos usado.

Un módulo eBox típico maneja la configuración de un demonio, pudiendo integrarse también con otros módulos de eBox. El desarrollador será quien decida la forma en la que el usuario podrá configurar el demonio, que no será necesariamente una relación directa entre las del módulo y las que admita el demonio. El desarrollador podrá elegir el valor, por defecto, más adecuado para la mayoría de las opciones y esconderlas de cara al usuario, mostrándole sólo las que se consideren realmente importantes. De igual forma, el cambio de una opción por parte del usuario mediante el interfaz web, puede causar cambios de configuración en varios parámetros de configuración del demonio, o en varios módulos de eBox. El principal objetivo es mantener un interfaz de usuario sencillo, facil de usar e integrado lo más posible, mientras se ofrece un conjunto de parámetros de configuración lo más rico posible.

Sin embargo, puede haber módulos que no manejen la configuración de un servicio de red. Un ejemplo de un módulo de este tipo es el módulo de "sysinfo" del sistema base, se encarga de recoger la información del sistema a ser mostrada en la página de Resumen y ofrece unas entradas de menú para características que no pertenecen a ningún módulo en particular. La clase padre del módulo define varios métodos abstractos que los módulos reales pueden dejar sin implementar, así un módulo puede simplemente mantener información en la página de Resumen, añadir nuevas entradas de menú, manejar un servicio de red o todo lo anterior.

El caso normal, y mas interesante, es el del módulo descrito en el primer parrafo. Este módulo tiene tres partes.

Esta separación de la GUI y el backend abre la posibilidad de de cambiar la configuración por otras vías. Una de estas otras vías es a través de scripts, esto es muy útil cuando se realizan paquetes para una distribución, el mantenedor del paquete puede escribir un script sencillo para importar la configuración actual del sistema a eBox, o establecer unos valores por defecto. Otro uso de la API la puede realizar otro módulo diferente, por ejemplo el módulo del firewall es uno de los casos mas habituales de este uso, casi todos los módulos necesitan "decirle" al firewall que abra algunos puertos para ellos. En el futuro puede que se desarrolle un wrapper sobre estas APIs para publicarlas a través de web-services, esto podría hacer a la configuración de eBox programable sobre la red.

Tenemos una API que ofrece ciertas características configurables de un servicio, y una GUI que permite al usuario manipular la configuración. La tercera parte del módulo es normalmente mas pequeña, traduce toda la informacón acerca de la configuracón almacenada en gconf en reglas para el firewall, ficheros de configuración y comandos que hacen que el servicio de red se comporte como el usuario espera. También se encarga del lanzamiento, parada y relanzamiento del servicio cuando sea necesario.

Además de estas tres partes, el módulo tiene otras funcionalidades menores, como su parte de información en la página de Resumen de la interfaz web, las entradas de menú, la declaración de dependencias, backups de las partes de la configuración no almacenadas en gconf, etc...

Esto es todo lo que hay, crear un módulo es tan simple como seguir los siguientes pasos:

El tamaño y complejidad de un módulo depende directamente de la complejidad del servicio involucrado y de la cantidad de parámetros configurables sobre el servicio que ofrecemos al usuario. El trabajo necesario para hacer un módulo eBox pequeño es mínimo, tomando como ejemplo el módulo DNSCache, sus CGIs tienen 49 lineas de código y el módulo en sí 134.

La estructura de directorios de un módulo eBox puede parecer un poco compleja a primera vista. Un módulo eBox normal debería tener el siguiente aspecto:

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

Los directorios más importantes son src/, schemas/, www/ y stubs/.

El directorio src/ contiene el código fuente del módulo. Dentro de él encontramos dos subdirectorios: EBox y templates. En el directorio EBox se encuentran los ficheros fuente Perl, incluyendo el subdirectorio CGI con la interfaz web del módulo. El directorio templates se utiliza para almacenar las plantillas Mason, que serán utilizadas para generar la salida HTML.

El directorio schemas/ contiene esquemas gconf, utilizados para definir las opciones de configuración de los módulos y opcionalmente proporcionar valores por defecto para algunas de ellas.

El directorio www/ contiene imágenes y hojas de estilo CSS que son utilizadas por la interfaz web.

En stubs/ se almacenan las plantillas Mason utilizadas para generar los ficheros de configuración para los servicios del módulo.

La clase EBox::Global ofrece varias funciones para la administración de módulos. Las funciones utilizadas más comúnmente son las que hacen referencia a la instanciación de módulos. EBox::Global funciona como una factoría de módulos, obtienes una instancia suya usando la función estática getInstance y después usar esa instancia para crear módulos. La factoría puede tener dos formas, una de sólo lectura y otra de lectura-escritura.

Llamar a getInstance sin argumentos producirá una factoría de lectura-escritura, la cual crea módulos que le permiten hacer llamadas para cambiar la configuración. Un detalle muy importante de los módulos lectura-escritura es que devuelven la información de su última configuración, incluso si no se ha guardado todavía (lo que significa que podría ser revocada más tarde por el usuario). Esta idea es importante, ya que la configuración que nos ofrece el módulo lectura-escritura no debe ser tratada como definitiva, a no ser que el módulo no tenga cambios esperando a ser guardados. Puede ver si un módulo tiene cambios sin guardar llamando a la función modIsChanged en la clase EBox::Global.

La idea subyacente en el comportamiento de los módulos lectura-escritura es tener un front-end para construir una configuración. Por ejemplo, si el usuario crea un nuevo objeto de red en el módulo objetos, el nuevo objeto mostrará instantáneamente la configuración del firewall y se podrá crear nuevas reglas del firewall que lo usen. Después de realizar todos los cambios deseados, el usuario guarda la configuración. Si decide cancelar los cambios que acaba de hacer, tanto el nuevo objeto como las reglas del firewall serán borradas.

Hay una situación en la que no desea recoger la información que no ha sido guardada todavía. Ésta es cuando se está generando el fichero de configuración de un demonio, configurando las reglas del firewall, configurando la dirección de un interfaz de red, o cualquier otra actividad que necesita la configuración real y definitiva. Esta situación se encuentra en los scripts del sistema (el script de arranque, trabajos de cron, etc). En estos casos necesita lo que se denominan módulos de sólo-lectura, que sólo ofrecen la información almacenada y no permiten hacer llamadas a funciones que cambiarían la configuración del módulo. Para obtener módulos de sólo-lectura necesita crear una instancia de EBox::Global configurando su parámetro readonly como true. Las instancias del módulo devueltas por una factoría creada de esta forma serán de sólo-lectura. Este script muestra como obtener una instancia del módulo squid y le pide que se reinicie:

#!/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 "El módulo Squid falló al reiniciarse.\n";
};

Hay dos funciones que hacen más sencillo realizar dos tareas muy comunes: obtener una instancia de cada módulo y obtener una instancia de cada módulo que implemente alguna clase abstracta. Éstas son modInstances y modInstancesOfType. Usarlas es muy sencillo:

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

# se reinician todos los módulos
foreach my $mod (@{$global->modInstances()}) {
	$mod->restartService();
}

# se reinician todos los módulos que implementen la clase NetworkObserver
foreach my $mod (@{$global->modInstancesOfType('EBox::NetworkObserver')}) {
	$mod->restartService();
}

Reiniciar todos los módulos es todavía más sencillo que eso. EBox::Global nos provee de la función restartAllModules justamente para eso. Éste es uno de los métodos que realiza una operación en todos los módulos instalados:

El manejo de todos los errores en eBox está implementado con excepciones del estilo de Java. Éstas están provistas por el módulo de perl Error. Puede leer la documentación de perl para ese módulo para obtener una descripción detallada de cómo utilizar las excepciones en perl. Las excepciones de eBox están definidas en el espacio de nombres EBox::Exceptions.

eBox provee una jerarquía de excepciones de la cual puede elegir la más apropiada para cada situación. Todas las excepciones de eBox heredan de una de estas dos:

La diferencia entre estos dos tipos es que el usuario verá cuando una excepción no ha sido capturada. La plataforma del interfaz de usuario mostrará el mensaje contenido en la excepción sin alterarlo si la excepción es una de tipo externo. Debería usar excepciones externas para los errores introducidos por el usuario, como un error de sintaxis en una dirección IP dada por el interfaz de usuario al backend del módulo.

Si la excepción es interna se registrará el error y se asumirá que algo falló internamente en eBox (un bug) o en el sistema en general. Cuando una excepción interna se captura por GUI el usuario verá un mensaje de error genérico. Cualquier excepción, interna o externa, puede ser utilizada internamente para otros propósitos, siempre que sea capturada antes de que recorra todo el camino hasta la GUI.

Si no puede encontrar una excepción para ciertas condiciones de error, tiene dos opciones: crear una nueva clase de excepción, heredándola de EBox::Exceptions::External o EBox::Exceptions::Internal, o usar únicamente una de estas dos clases como excepciones genéricas:

if ($foo_condition) {
	throw EBox::Exceptions::Internal('Algo ha pasado!!');
}

Como puede ver, lanzar excepciones sigue una sintaxis muy similar a Java. Capturarlas también es muy similar:

use Error qw(:try);

sub foo
{
	my $bar = shift;

	try {
		$bar->doSomething();
	} catch EBox::Exceptions::Base with {
		# no hace nada, sólo se ignora el error
	};
}

Puede hacer lo que quiera dentro de la sección “catch”. Puede escribir varias secciones “catch” si necesita hacer diferentes cosas para diferentes tipos de excepción. Las secciones “otherwise” y “finally” también están permitidas. Para una explicación detallada sobre éstas, únicamente ejecute perldoc Error. Un detalle muy importante es no olvidar el punto y coma después de la última sección (el “catch” en el ejemplo). No hacerlo puede producir resultados inesperados, esto se debe a la magia negra que es utilizada en la implementación del try-catch en perl.

Es muy importante que cada funcionalidad ofrecida por cada módulo valide sus datos de entrada correctamente. Todos los argumentos necesitan ser comprobados. Si esto no se hace, un módulo podría guardar valores sintácticamente incorrectos en su configuración, y el servicio subyacente se comportaría de una forma impredecible con el fichero de configuración generado por el módulo. La validación de datos también ayuda a encontrar errores en la GUI, y cualquier otro código que utilice el módulo.

El módulo de perl EBox::Validate provee de una serie de funciones para validar diferentes tipos de datos. Todas estas funciones funcionan de la misma manera, su primer argumento es el valor que se va a comprobar. Devuelven true si el valor es correcto, undef si no lo es:

use EBox::Validate qw(:all);

my $ip = '192.168.0.1';

unless (checkIP($ip))
	print STDERR "$ip no es válida.\n";
}

Lo que hay que hacer normalmente si un argumento es incorrecto es lanzar una excepción. Y la mayor parte del tiempo el valor incorrecto será uno suministrado por el usuario. Por esta razón, todas las funciones en EBox::Validate nos suministran un mecanismo sencillo para lanzar excepciones del tipo EBox::External. Todo lo que es necesario hacer es pasarles un argumento más, con un nombre o descripción para el valor que está intentando comprobar. Si pasa ese argumento y la validación falla, se lanzará una excepción con un mensaje indicando el nombre del campo incorrecto:

checkIP($ip, 'dirección IP ');

Si no quiere que se lance una excepción, o si quiere que se lance un tipo distinto, no pase el último argumento y gestione el error dentro de su código.

eBox utiliza “gettext”, la plataforma de internacionalización (i18n) del proyecto GNU, para permitir a los colaboradores traducir fácilmente el interfaz gráfico de eBox a su propio idioma.

Esta sección describe la i18n de eBox tanto desde el punto de vista del desarrollador (reglas que deben seguirse para desarrollar un módulo traducible) como del traductor (cómo realizar una traducción de eBox a su idioma).

print __("Hello world");
			

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

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

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

# cadena traducida
msgid "Name"
msgstr "Nombre"

# cadena borrosa
#, fuzzy
msgid "Interfaces"
msgstr "Interface"

#cadena sin traducir
msgid "External"
msgstr ""
			

msgid "Edit {group} members"
			

msgstr "Editar miembros de {group}"
			

Todos los módulos de eBox heredan de la clase EBox::Module. Esta clase define funciones abstractas que los módulos sobreescribirán para implementar una cierta funcionalidad. Estas funciones son llamados por la plataforma cuando son necesarios.

Además de estas funciones abstractas, la clase implementa unos pocas funciones con algunas funcionalidades básicas. Estas últimas, siguen normalmente el método que define una plantilla de un patrón de diseño, es decir, realizan algunas operaciones pero delegan parte de ellas en alguna función abstracta que deberá ser implementada por la clase hija.

Finalmente, hay unas pocas funciones que implementan algunas operaciones comunes que son utilizadas por la mayoría de los módulos, están escritas para que sean llamadas por las clases hijas cuando se les necesita. Están situadas en la clase EBox::Module únicamente por conveniencia.

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

El servidor apache bajo el que funciona eBox y cualquier otro script de perl que utilice el API de eBox, utilizan un id de usuario dedicado. El usuario es normalmente llamado “ebox”. Los módulos de eBox necesitan ejecutar ciertos comandos y escribir ciertos ficheros con privilegios de root, esto se hace usando sudo.

Se puede llamar a cualquier comando utilizando la función root() en el paquete perl EBox::Sudo. Si el comando falla, root() lanza una excepción de tipo EBox::Exceptions::Sudo::Command, asegúrese de que sea capturada si es correcto que el comando falle o si desea informar al usuario de una forma distinta. En cualquier caso se pueden usar los métodos output, error y exitValue para obtener más información sobre el fallo de comando. En los raros casos en lo que el propio programa sudo falla la excepción levantada es del tipo EBox::Exceptions::Sudo::Wrapper y los últimos métodos no estarán disponibles.

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 provee funciones de interfaz con comandos frecuentemente ejecutados con privilegios de superusuario. stat propociona interfaz con el programa stat, resulta util para obtener informacion sobre cualquier archivo. Si necesitas una infromacion mas concisa sobre el archivo puedes usar fileTest para realizar comprobaciones simples sobre archivos, como hace el programa /usr/bin/test.

eBox utiliza GConf para almacenar su configuración. La plataforma de desarrollo ofrece un recubrimiento sobre los bindings originales de perl. GConf ofrece una sencilla API para almacenar y consultar configuración con valores clasificados por tipos y organizada jerárquicamente. También nos permite definir esquemas limitados para algunas claves de configuración, configurando sus tipos y valores por defecto.

La plataforma de desarrollo define un recubrimiento sobre el API de GConf más algunas funcionalidades añadidas. El recubrimiento es implementado como una clase hija de Ebox::Module, así que todos los módulos que quieren usar GConf heredan de EBox::GConfModule. Sus hijos automáticamente adquieren estas características:

Esta es la lista de las funciones más importantes en EBox::GConfModule:

Veamos algunos ejemplos de las funciones anteriormente descritas.

 $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);
		

La necesidad de mantener cierta información ordenada es muy normal en los módulos eBox. También es común ofrecer funciones de reordenación. Un ejemplo claro son las reglas del firewall, las cuales necesitan ser aplicadas en un cierto orden, y el usuario ha de poderles cambiar su orden. La clase EBox::Order resuelve justamente este problema.

La idea es dar un directorio a cada objeto que se quiere mantener ordenado. Siguiendo con el ejemplo del firewall, podríamos tener el directorio rules/ y, por debajo, un directorio por regla. Cada regla tendría un identificador único, y eso sería el nombre de su directorio bajo rules/. Una regla con el id r3561 se almacenaría en rules/r3561, y debajo de ese directorio se almacenarían las claves con cada uno de los parámetros de la regla. Ésta es la forma más natural de organizar elementos como reglas de firewall, y es con una organización de este tipo para lo que está diseñado EBox::Order para trabajar.

El mecanismo de ordenación añade un campo a los objetos para ser ordenados. Lógicamente, se le ha denominado order. Para usar el API de ordenación ha de crear una instancia de EBox::Order. Su constructor toma como argumentos: la instancia del módulo al que pertenecen los objetos que van a ser ordenados y el directorio base donde los objetos serán almacenados.

EBox::Order implementa estas operaciones:

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);
}

Además de tener un API que permite leer y cambiar la configuración de un servicio dado, el backend de un módulo está a cargo de hacer que el servicio funcione. Típicamente, el servicio será algún tipo de demonio que ofrezca algunas funcionalidades a través de la red después de leer su fichero de configuración. Por tanto, el módulo creado necesitará generar el fichero de configuración y parar/arrancar/reiniciar el demonio las veces que sea necesario.

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');
	}
}

Como señalábamos con anterioridad, todos los cambios hechos en las claves almacenadas en gconf son automáticamente guardados la primera vez que se efectúa una operación de escritura o borrado. En consecuencia, todos esos cambios pueden ser recuperados automáticamente si el usuario desea descartar o recuperarlos de un fichero. Por supuesto esto ocurre siempre que se usen las funciones provistas a tal efecto por EBox::GConfModule.

Si su módulo tiene parte o la totalidad de su configuración independiente de GConf, deberá implementar los métodos dumpConfig y restoreConfig.

Adicionalmente, si aparte de la configuración desea copiar otros tipo de datos asociados al módulo que no forman parte de su configuración, como por ejemplo ficheros de usuarios, deberá también implementar los métodos extendedBackup y extendedRestore. Recuerde que este tipo de información sólo será guardada y restaurada si el usuario lo solicita explícitamente.

El módulo usersandgroups almacena su configuración (usuarios, grupos, contraseñas, ..) en el servidor de LDAP. Por este motivo deberemos guardar y recuperar posteriormente la información guardada en openldap para poder realizar copias de seguridad de este módulo correctamente. Veamos como podemos hacerlo:

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


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

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

El módulo ebox-logs es el encargado de la administración de los registros de eBox. Deseamos tener la posibilidad de hacer copia de seguridad de sus contenidos. Como dichos contenidos no forman parte de la configuración del módulo usaremos extendedBackup y extendedRestore. Los datos no pertenecientes a la configuración sólo se almacenarán en la copia de seguridad si el usuario así lo elige.

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 puede registrar cada cambio realizado a través de interfaz administrativo, lo que es útil para saber cuando se ha cambiado o quién lo ha hecho. Cada módulo eBox debería dar parte de cada mensaje de registro para dar un soporte completo al registro administrativo.

Para conseguirlo, debes incluir un nuevo paquete del núcleo eBox EBox::LogAdmin en tu módulo.

use EBox::LogAdmin qw ( :all );

Se usa un nuevo atributo del módulo, title, debes añadirlo a la llamada de creación del módulo. Por ejemplo:

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

Además, se necesita una tabla hash en el constructor con las actiones que tu módulo reportará con una formato de mensaje bonito. Siguiendo el mismo ejemplo en el módulo EBox::Objects:

$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}');

	    

Para cada acción que quieras registrar, que debería ser todas que puedan hacerse desde el interfaz web, deberás seguir estos pasos:

Hay tres razones diferentes por las cuales tu módulo puede necesitar interactuar con otros módulos:

El módulo objects mantiene una lista de objetos de red creada por el usuario. Estos objetos pueden contener cualquier número de direcciones IP y bloques CIDR.

Su interfaz es muy simple. La clase EBox::ObjectObserver tiene dos funciones abstractas que deben ser implementadas por los módulos que hacen uso del módulo objects:

Como ejemplo, aquí está la implementación de ambas funciones en el módulo firewall:

sub usesObject # (object) 
{
	my ($self, $object) = @_;
	defined($object) or return undef;
	($object ne "") or return undef;
	return $self->dir_exists("objects/$object");
}

sub freeObject # (object) 
{
	my ($self, $object) = @_;
	defined($object) or return;
	($object ne "") or return;
	$self->delete_dir("objects/$object");
}

El caso de network es más complejo. Hay varios cambios potenciales en la configuración de la red que otros módulos podrían necesitar conocer. EBox::NetworkObserver tiene cuatro funciones que el módulo network llama cuando se hacen distintos tipos de cambios, y dos funciones que avisan a los módulos para que eliminen las referencias a ciertos interfaces de red de sus configuraciones:

Ejemplo 4.2 muestra la implementación de las funciones EBox::NetworkObserver en el módulo firewall.

sub ifaceMethodChanged # (iface, oldmethod, newmethod)
{
	 my ($self, $iface, $oldm, $newm) = @_;

	 ($newm eq 'static') and return undef;
	 ($newm eq 'dhcp') and return undef;

	 return $self->usesIface($iface);
}

sub vifaceDelete # (iface, viface)
{
	 my ($self, $iface, $viface) = @_;
	 return $self->usesIface("$iface:$viface");
}

sub usesIface # (iface)
{
	 my ($self, $iface) = @_;
	 my @reds = $self->all_dirs("redirections");
	 foreach (@reds) {
		  if ($self->get_string("$_/iface") eq $iface) {
			   return 1;
		  }
	 }
	 return undef;
}

sub freeIface # (iface)
{
	 my ($self, $iface) = @_;
	 $self->removePortRedirectionOnIface($iface);
}

sub freeViface # (iface, viface)
{
	 my ($self, $iface, $viface) = @_;
	 $self->removePortRedirectionOnIface("$iface:$viface");
}

Los módulos firewall necesitan permitir que otros módulos inserten reglas NAT y de filtrado a medida. Tiene un API limitado que permite a los módulos modificar las reglas de filtrado. Por ejemplo, si un módulo necesita conectar a servidores HTTP de internet, llamaría a addOutputRule y el firewall abriría los puertos necesarios.

Sin embargo, este mecanismo no es muy flexible desde que hay módulos con necesidades muy específicas. El módulo squid necesita configurar varias reglas NAT y de filtrado para su funcionar transparentemente.

La clase EBox::FirewallObserver fue creada para estos casos más complejos. Cuando el firewall se reinicia pide a todos los módulos que heredan de EBox::FirewallObserver para ver si necesitan insertar sus propias reglas. Los módulos pueden insertar cualquier regla que quieran, con la sintaxis de iptables. La única cosa que no pueden controlar es donde exactamente son colocadas esas reglas. Los módulos de firewall tienen varios enganches a través de las distintas cadenas y tablas donde ponen estas reglas a medida.

EBox::FirewallObserver define dos funciones:

firewallHelper debería devolver undef (el comportamiento por defecto) o un objeto de tipo EBox::FirewallHelper. Esta clase define varias funciones que deberían devolver reglas que el firewall insertaría en cada uno de los enganches definidos para este propósito.

La sintaxis de las reglas provistas por los módulos es simple: sólo utilizan la misma sintaxis que se usaría en la línea de comandos de iptables, pero excluyendo la cadena, tabla y el comando iptables al principio:

Estas son las funciones definidas en EBox::FirewallHelper, cada uno de ellos para cada tipo distinto de reglas, todos ellos devuelven una referencia a un array que contienen las reglas:

Si necesita más información sobre como iptables y Netfilter trabajan, consulte el Howto de NAT y el Howto de Packet filtering en el sitio web de Netfilter.Ejemplo 4.3 muestra la implementación de la función output en EBox::FirewallHelper definida en el módulo squid.

sub output
{
        my $self = shift;
        my $sq = EBox::Global->modInstance('squid');
        my @rules = ();
        push(@rules, "-m state --state NEW -p tcp --dport 80 -j ACCEPT");
        push(@rules, "-m state --state NEW -p tcp --dport 443 -j ACCEPT");
        return \@rules;
}

usesPort acepta tres argumentos: protocol, port y network interface. Esta función se usa para preguntar a los módulos si utilizan un puerto tcp o udp concreto. Le permite al firewall conocer si es una buena idea permitir o no la creación de la redirección de un puerto. Devuelve true si el módulo utiliza el puerto dado y undef en otro caso.

Supongamos que estamos implementando un módulo mail con soporte para dominios virtuales, y queremos permitir a otros módulos saber cuando se borra un dominio virtual. Podríamos definir una clase abstracta llamada EBox::MailObserver, como esta:

package EBox::MailObserver;

use strict;
use warnings;

sub new
{
	my $class = shift;
	my $self = {};
	bless($self, $class);
	return $self;
}

# Cuando un dominio virtual se borra, se llama a este método.
sub virtualDomainDeleted # (domainName)
{}

Cuando ocurre un evento importante, el módulo mail llamaría a la función virtualDomainDeleted en todos los módulos que hubiesen extendido la clase EBox::MailObserver:

sub removeVirtualDomain # (domainName)
{
	my ($self, $domain) = @_;

	#
	# do stuff
	#

	my $global = EBox::Global->getInstance();
	my @modules = @{$global->modInstancesOfType('EBox::MailObserver')};
	foreach my $mod (@modules) {
		$mod->virtualDomainDeleted($domain);
	}
}

El interfaz de administración de eBox está basado en web, utilizando mod_perl por encima de apache. La información es recogida desde los backends de los distintos módulos por scripts CGI y es mostrada a través del sistema de plantillas mason.

La separación por barras de las URLs están asociados con nombres de clases de perl. La URL Network/Index es traducida al nombre de la clase EBox::CGI::Network::Index. De hecho, la raíz del espacio de nombres es /ebox/, por lo que la URL actual sería /ebox/Network/Index, pero esa parte es automáticamente manejada por la plataforma. Así que si se necesita escribir un CGI para mostrar algún dato o dejarle al usuario configurar algo, se debe escribir la clase en el espacio de nombres EBox::CGI y todas las peticiones coincidentes serán enviadas a ésta.

Hay muchas funcionalidades comunes compartidas por la mayoría de CGIs en eBox: manejo de errores, validación de datos de entrada, llamada a las plantillas de mason, muestra de mensajes y avisos, impresión del menú, etc.

Por esta razón hay una clase padre de la cual todos los CGI deberían heredar. Esta clase implementa todas aquellas funciones que que casi no intervienen con las clases hijas, esto es el por qué tantos CGI acaban siendo de unas 20 líneas de código. Toda esta funcionalidad ahora se divide en dos clases, porque hay una pequeña parte específica a la parte del cliente de eBox. Esta parte es mantenida por el cliente, y es la clase de la que se debe heredar:EBox::CGI::ClientBase.

La otra clase, EBox::CGI::Base, tiene la mayor parte del código, y reside en libebox por lo que puede ser rechazada por el lado del servidor. EBox::CGI::ClientBase hereda de EBox::CGI::Base, por lo que se puede olvidar de manera segura que son dos clases y únicamente recordar la primera.

Heredar de EBox::CGI::ClientBase mostrará una página con la barra de titulo normal y el menú, pero con el cuerpo vacío. Si se pasa el argumento title al constructor de la clase padre, se mostrará también.

package EBox::CGI::Hello::World;

use strict;
use warnings;

use base 'EBox::CGI::ClientBase';

use EBox::Gettext;

sub new 
{
	my $class = shift;
	my $self = $class->SUPER::new('title' => __('Hola Mundo!'), @_);
	bless($self, $class);
	return $self;
}

En la gran mayoría de casos, sólo será necesario implementar la función abstracta _process en las clases para conseguir el resultado deseado. Es llamada por la clase padre, la cual realiza distintas acciones dependiendo del estado del objeto después de la llamada a _process. Hay ciertos atributos en la clase que pueden cambiarse para modificar el comportamiento de la clase padre. La propia función _process normalmente haría alguna de estas dos cosas (quizá ambas):

La próxima cosa que hay que saber es como hacer que un CGI utilice una plantilla de mason para mostrar información. Es realmente sencillo. Se puede pasar únicamente un argumento template al constructor del padre, o configurar el atributo template en cualquier momento antes del return de su función _process. Este código muestra ambas aproximaciones:

# Configurando la plantilla en el constructor
sub new 
{
	my $class = shift;
	my $self = $class->SUPER::new('title' => __('Hola Mundo!'), 
					'template' => 'hello/world.mas',
					@_);
	bless($self, $class);
	return $self;
}

# Setting the template in _process
sub _process
{
	my $self = shift;
	$self->setTemplate('hello/world.mas');
}

En segundo lugar, necesitamos poder pasar alguna información a la plantilla mason. Esto se hace utilizando el atributo params. Debería ser una referencia a un array que contenga todos los parámetros y sus nombres. Esto es la función _process para la página de configuración general (la que contiene el puerto, contraseña e idioma):

sub _process
{
	my $self = shift;

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

	my @array = ();
	push(@array, 'port' => $apache->port());
	push(@array, 'lang' => EBox::locale());

	$self->{params} = \@array;
}

Eso está así para utilizar plantillas desde los CGIs. Los detalles acerca de la escritura están descritos en Sección 5.2.

Hay otro mecanismo para mostrar los datos al usuario. Puede mostrar mensajes configurando los atributos msg y error para mostrar cualquier texto que se quiera. Ambos tipos de mensajes se muestran en una caja en la parte superior de la página. Necesita tener algo de cuidado con el atributo error, siendo que serán sobreescritas si una excepción es capturada por la clase padre.

sub _writeBackupToDiscAction
{
  my ($self) = @_;
 
  my $backup = new EBox::Backup;
  my $id     = $self->param('id');
  
  $backup->writeBackupToDisc($id);

  $self->setMsg(__('Backup was written to CD/DVD disk'));
}

Leyendo los argumentos enviados en la petición HTTP es muy sencillo. La clase padre utiliza el módulo de perl CGI para acceder a esta información, y provee de un recubridor sobre esta función param, que hace algunas comprobaciones en la entrada de datos. Esta es la función _process en el CGI que cambia el puerto TCP del interfaz web:

sub _process
{
	my $self = shift;

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

	$apache->setPort($self->param('port'));
}

Es tan simple porque todas las comprobaciones sobre los datos son realizados por el backend (utilizando el módulo de perl EBox::Validate) y por la clase padre. Otra razón para conseguir la simplicidad del código de arriba es que el manejo de errores es automático.

Mientras se hacen todas esas cosas, las excepciones se pueden lanzar. A no ser que haya una buena razón para capturar una excepción (p.ej. espera el error y no quiere que se muestre como un error) probablemente será suficiente que las excepciones sean lanzadas y escribir el código como si no existieran realmente. El comportamiento estándar es que las excepciones que hereden de EBox::Exceptions::Internal causen un mensaje de error genérico, mandando al usuario a consultar los registros si necesitase ver los detalles. Las subclases de EBox::Exceptions::External son mostradas textualmente, el uso más común para estas excepciones es cuando los datos introducidos por el usuario se validan.

La última parte que necesita aprender es como redirigir las peticiones a otros CGIs. Hay pocas razones por las cuales se requiere hacer eso, por ejemplo, escribir un CGI que tome unos datos del usuario desde el navegador, cambie algo en el backend del módulo y redirija la petición al CGI que muestra los datos. El CGI mostrado en Ejemplo 5.5 no llama a ninguna plantilla de mason, únicamente cambia el puerto de apache y no hace nada más. Queremos que el usuario vea la misma página que veía antes de cambiar el puerto, con el nuevo valor. Ejemplo 5.6 muestra el constructor para ese CGI:

sub new
	my $class = shift;
	my $self = $class->SUPER::new(@_);
	bless($self, $class);
	$self->setRedirect("EBox/General");
	return $self;
}

Se puede ver que el constructor configura el atributo redirect con el valor de la URL de la página a la que queremos ser redirigidos. Eso es todo lo que hace falta hacer. A redirect se le da un valor y la clase padre hará una redirección HTTP después de que haya acabado la función _process.

Una redirección HTTP hace que el navegador lance una nueva petición HTTP, por lo que toda la información de estado de la antigua petición se pierde. Habrá casos en los que querremos mantener la información para el nuevo CGI, y para ello tenemos dos formas de hacerlo. Podría hacerse pasando los parámetros GET en la URL de la redirección, pero es mucho más sencillo hacerlo en una redirección interna, sin que pase a través del navegador.

Si necesita mantener la información, como un mensaje o una advertencia la usuario, puede utilizar el atributo chain. Funciona exactamente de la misma forma que redirect pero en vez de enviar una respuesta HTTP al navegador, la clase padre procesa la URL, instancia el CGI coincidente, copia todos los datos en él y lo ejecuta. Los mensajes y errores son copiados automáticamente, los parámetros en la petición HTTP no, ya que un error causado por uno de ellos se podría propagar al siguiente CGI.

Si necesita mantener los parámetros HTTP puede utilizar la función keepParam de la clase padre. Toma el nombre del parámetro como un argumento y lo añade a la lista de parámetros que se le copiarán al nuevo CGI si se usa el atributo chain.

Los errores son un caso especial. Cuando aparece un error, no se desea hacer redirecciones, ya que el mensaje de error se perdería. Si aparece un error y redirect tiene un valor, entonces ese valor se utiliza como si fuera chain. Sin embargo, algunas veces se desea encadenarlo a un CGI aparte si hay un error, por ejemplo si la causa del error es la ausencia de un parámetro de entrada necesario para mostrar la página. Si se da ese caso, se puede utilizar el atributo errorchain, el cual tiene una prioridad más alta que chain y redirect si hay un error.

Finalmente, el último detalle que hace falta conocer acerca de los CGIs es como hacer que funcione correctamente la internacionalización, tanto en los CGIs como en las plantillas de mason. Siendo que el módulo no tendrá el mismo dominio gettext en la plataforma eBox, la plataforma necesita conocer el dominio para poder configurarlo antes de llamar al CGI y a la plantilla. Es tan simple como pasarle como argumento al constructor del padre. El constructor "Hola mundo" en Ejemplo 5.1 sería así:

sub new 
{
	my $class = shift;
	my $self = $class->SUPER::new('title' => __('Hola mundo!'),
					'domain' => 'ebox-hello',
					@_);
	bless($self, $class);
	return $self;
}

Si el título se puede traducir, debería configurarlo de nuevo en la función _process, co