Customizing the System

The first rule when customizing the SME 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.

Custom template modifications

To allow customizations, and to clearly isolate user-customizations from package-installed templates, a second template tree is rooted at /etc/e-smith/templates-custom/ (note: this feature was introduced in e-smith v4.0). Templates found in this directory will override the templates in /etc/e-smith/templates/.

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.

.

mkdir -p /etc/e-smith/templates-custom/etc/smb.conf

.

cp /etc/e-smith/templates/etc/smb.conf/10globals /etc/e-smith/templates-custom/etc/smb.conf

.

/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 SME 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 SME Server 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 SME Server 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 SME Server 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 SME Server 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 SME Server 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 SME Server 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.

You will to run /sbin/e-smith/signal-event conf-userpanel for any changes to appear in the User Panel.

Packaging your customizations

The primary distinguishing feature of the Sme Server 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 SME Server management files described in the examples above.

Please refer to our SME Server interface RPM document for more information on building custom rpms.

copyright 2000 e-smith, inc. all rights reserved

Back to Documentation