The first rule when customizing the e-smith server and gateway is this: If you want to change a
configuration file, check whether there is a template for it in the /etc/e-smith/templates
directory. If there is, make the change via the template mechanism! Otherwise your changes will
be overwritten next time the templates are instantiated.
Modifications made in templates-custom will be preserved during backup
and restore.
Do not modify existing templates in /etc/e-smith/templates/ as your changes
will be overwritten when packages are upgraded.
To customize an existing template, copy that template to the
/etc/e-smith/templates-custom/ directory, and make any necessary changes there. This provides a convenient backup mechanism:
if you want to revert to the original template,
simply rename the /etc/e-smith/templates-custom/ directory.
For example, here's how to make changes to the smb.conf file.
Expand the template:
/sbin/e-smith/expand-template /etc/smb.conf
When you've finished, the new changes will appear in the /etc/smb.conf file and
can be modified from the /etc/e-smith/templates-custom/ directory.
The design of the e-smith server and gateway makes it easy to extend. Templates can be altered
to generate slightly different configuration files. Actions can be altered or created. Events can be
altered to call different actions or call actions in a different sequence. New events can easily
be defined. And new user interfaces can be created simply by modifying the
/home/e-smith/configuration file as needed and then calling signal-event to reconfigure the system.
NOTE: Your custom templates should be checked after any upgrades to the
e-smith software as your changes may be inconsistent with later releases.
Example 1: Adding a new server
As a simple example, let us say that you want to add a new server to the system, and the server has
a configuration file called /etc/newserver.conf. Let us assume that this server does not
require any new parameters to be added to the master configuration file. This means that the e-smith
user interfaces will not need to be modified. However, whenever changes are made to the master
configuration file using the user interfaces, the new server will have to be reconfigured. (For
example, if the local network address is changed, the new server configuration file may need to be
regenerated to reflect the change.)
Step 1: Install the server software normally, as if the e-smith software were not
present.
Step 2: Write the configuration template file
/etc/e-smith/templates/etc/newserver.conf and parameterize it so that the domain, IP address,
and other parameters are inserted where appropriate into the output. (Study the documentation for
the Perl Text::Template mechanism to learn how to write templates.)
Step 3: Create a new action that will regenerate the template. For example, you might
define the file /etc/e-smith/events/actions/conf-newserver to have the following contents:
#!/usr/bin/perl -w
package esmith;
use strict;
use Errno;
use esmith::config;
use esmith::util;
my %conf;
tie %conf, 'esmith::config';
esmith::util::processTemplate (\%conf, "/etc/newserver.conf");
esmith::util::backgroundCommand (0, "/etc/rc.d/init.d/newserver restart");
exit (0);
Step 4: Create links in the appropriate event directories to your new action. For example,
if the configuration file depends on something that is settable in the e-smith web-based manager,
then you'll want to regenerate the configuration file whenever something is changed in the
manager. So you'll need a link in the /etc/e-smith/events/manager-misc directory such as:
S98conf-newserver -> ../actions/conf-newserver
This link means that whenever something is changed in the e-smith manager, the new conf-newserver
action will be executed, which will regenerate the configuration file and restart the server. This
will ensure that the new server always complies with the current system settings. (Event links like
this should be created for each event that might require the server configuration file to be updated.)
Once these steps have been performed, the new server is fully integrated into the e-smith
system. Assuming that the new server contains init scripts (these are the files in /etc/rc.d used to
start servers) it will be started automatically whenever the system is rebooted. And whenever a
parameter is changed in the user interface, the conf-newserver action will be executed to
reconfigure the server.
Note that in this example, integrating the server into the e-smith framework did not require
modifying any existing files. Only a few new files were required: the template, the action, and the
event symlinks. These files could easily have been added to the server's RPM, so that simply
installing the RPM would cause the new server to be managed by e-smith automatically!
Example 2: Adding a new parameter
Sometimes it is necessary to add a new parameter to the system. Adding a parameter means that the
system has conceptually become more complicated, since there is a new option for the user to choose.
For example, the new parameter SMTPSmartHost was recently added to allow outgoing mail to be
optionally routed through an ISP's mail server. Let us review how this parameter was added. To keep
things simple, in this example we will not make the parameter settable via the user interface.
The first step is to alter the configuration templates (in /etc/e-smith/templates) to take account
of the new parameter. Since the master configuration file will initially not contain the parameter,
the templates must behave correctly if the parameter is missing. For example, the action program
might contain this code:
if ($conf{'SMTPSmartHost'} && ($conf{'SMTPSmartHost'} ne 'off'))
{
esmith::util::processTemplate (\%conf, "/var/qmail/control/smtproutes");
}
else
{
unlink ("/var/qmail/control/smtproutes");
}
Notice that if the parameter is missing or set to off, the smtproutes file is deleted, to
enable standard delivery. But if the parameter is defined, the smtproutes file is generated from the
template (and the template uses the SMTPSmartHost parameter appropriately).
That is all that needs to be done to introduce the parameter! To enable this new function, you must
do manually what the user interface would normally do:
/sbin/e-smith/config set SMTPSmartHost 111.222.33.44
Then trigger the action by manually signalling the appropriate event, i.e.:
/sbin/e-smith/signal-event console-save
This will cause the smtproutes file to be created correctly.
Example 3: Extending the user interface
The screens for the various manager web pages are Perl CGI scripts defined in the directory
/etc/e-smith/web/functions (this is the new location; in e-smith 3.0 without the latest patches it
was in /home/e-smith/web-functions).
If you wish to make a new parameter (such as SMTPSmartHost) configurable using the e-smith
manager, you can add the parameter to an existing web page or you can create a new web page. The
easiest way to create a new web page is to copy one of the existing pages and modify it. In either
case, the updated CGI script must contain code that sets the new parameter and signals the
appropriate event whenever the form is submitted. Study the existing web pages for examples.
To integrate the new web page into the e-smith-manager, you must first create a link in the
/etc/e-smith/web/panels/manager/cgi-bin directory to the your new CGI script in /etc/e-smith/web/functions.
Second, edit the headers at the top of the script.
# heading : Configuration
# description : Your New Server
# navigation : 2000 2200
The heading: entry is the header as seen in the navigation panel. If this header doesn't exist, a new one will be created. The description: entry is the name of the link as it will appear in the navigation panel underneath the heading. The two numbers following the navigation: entry are used to determine the positioning of the header entries and the headers themselves.
Example 4: Combinations
If you combine examples two and three, you can create a new e-smith manager web page that lets you
set the SMTPSmartHost parameter. Whenever you submit the form, the SMTPSmartHost parameter is
modified in the master configuration file, and the appropriate event is signalled - which deletes or
regenerates the smtproutes file as needed.
If you combine examples one, two and three, you can add a new server to the system, along with a set
of parameters to control the server, and a user interface screen to easily set the parameters.
Packaging your customizations
We have sometimes been asked to provide a CVS server to allow enhancements to be added to the
e-smith code more easily. This is commonly done in the open-source world, and allows for a very
rapid pace of development. However, although we are major fans of the open-source development model,
our software is different than most open source projects in two ways:
First: From day one e-smith has been a for-profit business venture based on open-source
software. For example, although our software is free, we make firm service guarantees to paying
customers who use our software. Therefore if someone contributes code to our product which turns out
to have a bug in it, we personally are on the hook for it. This seems to be a fundamental tradeoff
in the open source world - if you are more permissive about accepting code, you get more bugs at any
given point in time, but your overall development is more rapid. If you are less permissive, your
pace is slower but quality is more easily controllable.
Second: The primary distinguishing feature of our product is simplicity. If too many features end up
in our software too quickly, we will quickly disappear into the crowd of standard Linux
distributions. There are already plenty of powerful web-based configuration tools for Linux; ours is
the only one focused on elegance and simplicity.
So we are trying for a middle ground in which we do not allow arbitrary modifications to the e-smith
code base. Instead, we recommend packaging customizations as "e-smith module RPM" files (something
like the way Apache or Perl modules can be made into RPMS).
The e-smith architecture is almost perfect for this arrangement. For example, to create an e-smith
IMAP module, you would package the IMAP server in an RPM, along with the additional e-smith
management files described in the examples above.
Please refer to our e-smith-interface_rpm document for more information on building custom rpms.
copyright 2000 e-smith, inc. all rights reserved.