Customizing the system

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.