This section is an overview of the concepts in the SME Server system. Understanding these concepts will help you get a 'feel' for how SME Server works.

It is not necessary to know these in order to use SME Server

Core Concepts

See the next section (Architecture overview) to understand more about how these items work with one another.

Master configuration file

The most important element of all is the master configuration file, stored in /home/e-smith/configuration. This file describes how the system should operate; what kind of Internet access to use, how email should be handled, and so on.

The configuration file is an ASCII file containing a list of Name=Value mappings, one per line. Here is a subset of it: 

AccessType=dedicated
ExternalDHCP=off
ExternalNetmask=255.255.255.0
ExternalIP=192.168.65.17
GatewayIP=192.168.65.1
SystemMode=servergateway
LocalNetmask=255.255.255.0
LocalIP=192.168.1.1
DomainName=mycompany.xxx
SystemName=e-smith
EmailRetrieval=standard
SambaWorkgroup=e-smith
SambaServerName=e-smith-server
POPServerMode=private
TelnetServerMode=off
PasswordSet=no


The other important configuration file is /home/e-smith/accounts, which is in a similar format, and specifies all of the accounts on the system. We classify accounts into three types.

System accounts: These are accounts such as root, bin, admin, etc.

User accounts: These are accounts created for individual users at the local organization. Each account has a POP mailbox and an area for storing files.

Ibay accounts: These accounts correspond to ibays defined in the system. User accounts are created for each ibay so that people can access the files section of the ibay via FTP to that account.

User interfaces

The user interfaces to the e-smith system (the web-based manager and the console interface) perform their work by modifying the master configuration file to describe the new system configuration, then regenerating the various Unix configuration files by signalling an event (more on this in the next section).

Console interface

The console interface is a single bash shell script called /sbin/e-smith/console. It uses the whiptail program to display the configuration screens. Whiptail was written at Red Hat Software as a replacement for the old dialog package. It is nice and fast, but is poorly documented. (The best way to learn whiptail is to read the documentation for the old dialog package; whiptail is reasonably compatible.)

The e-smith software modifies the /etc/inittab file during installation, so that the first two virtual terminals (Ctrl-Alt-F1 and Ctrl-Alt-F2) run //sbin/e-smith/console instead of the usual /sbin/mingetty which displays the usual login prompt. The relevant part of //etc/inittab is: 

1:12345:respawn:/sbin/e-smith/console tty1
2:2345:respawn:/sbin/e-smith/console tty2
3:2345:respawn:/sbin/mingetty tty3
4:2345:respawn:/sbin/mingetty tty4
5:2345:respawn:/sbin/mingetty tty5
6:2345:respawn:/sbin/mingetty tty6


Web-based manager interface

The web-based manager is a set of CGI scripts stored in the /etc/e-smith/web directory. This directory is organized to support multiple web-based user interfaces (called panels) with slightly different features and permissions. The e-smith server and gateway normally comes with two panels: the manager panel (which requires an admin password and allows most system parameters to be configured) and the password panel (which does not require a password and allows users to change their own password).

The web directory contains three subdirectories. The first subdirectory, common, contains any static files (such as images) which are used by multiple panels.

The second subdirectory, functions, contains all of the screen definitions for all panels. Each screen definition is a single CGI script which displays the screen and also handles the CGI form submission. The CGI scripts must be setuid if they require root privileges, since they will be run by the web server (which runs as user www). In order to avoid making this a giant security hole, the permissions on the parent directory containing the CGI scripts are set such that only the www user can pass through.

The third directory, panels contains the panel definitions. There is one subdirectory for each panel. Each panel must have html and cgi-bin subdirectories, as well as a file called access.incl which is automatically inserted into the Apache access control file in the appropriate place to define permissions for that particular panel. The cgi-bin subdirectory should contain only symbolic links to the actual CGI scripts in the functions directory, and the html directory should contain the main index.html file for the panel, as well as any required navigation links.

Keeping the CGI scripts for all panels in a shared directory makes it much easier to create auxiliary panels with slightly different options and permissions. You can just copy the entire panel directory, then customize the access permissions and navigation links. For example, it would be very straightforward to create a password-protected panel which only allowed the creation and deletion of user accounts. Then that task could be delegated to another worker.

Actions and events

Whenever the user interface modifies the master configuration files, it must signal an event to regenerate the various server application configuration files according to the new configuration.

Each event is associated with a list of actions that should be performed when that event occurs, and each action in turn causes a particular set of configuration files to be regenerated from the templates.

For example, the console-save event performs the following actions:

If we examine one action in detail, for example the conf-security action, we will see that it regenerates the Unix configuration files related to system security:

Note that any particular config file is managed by at most one action. You don't want multiple action generating the same file.

The actions are programs stored in the directory /etc/e-smith/events/actions. To create a new action called myaction you simply create a program to perform the action and save it as /etc/e-smith/events/actions/myaction. Actions can be written in any programming language, but Perl code is preferred.

Each event is defined as a subdirectory of /etc/e-smith/events containing symbolic links to the appropriate actions (this system is loosely modelled after the /etc/rc.d mechanism for starting servers). For example, if you examine the console-save directory: 

# cd /etc/e-smith/events/console-save
# ls -l
total 0
S30conf-modules -> ../actions/conf-modules
S35conf-ethernet -> ../actions/conf-ethernet
S40conf-dialup -> ../actions/conf-dialup
S45conf-networking -> ../actions/conf-networking
S50conf-security -> ../actions/conf-security
S55conf-servers -> ../actions/conf-servers
S60conf-startup -> ../actions/conf-startup
S65conf-other -> ../actions/conf-other
S80rebuild-ldap -> ../actions/rebuild-ldap

The symbolic links are given prefixes such as S30, S35, etc. to specify the order in which the actions should be executed (similar to the /etc/rc.d mechanism).

You can change the actions performed by an event by changing the links in the event's directory. You can create a new event by creating another subdirectory of /etc/e-smith/events.

The program /sbin/e-smith/signal-event takes an event name as an argument, and executes all the actions in that event, directing all output to the system log. It works by listing the symbolic links in the event directory and executing them in sequence. So for example, the command:

/sbin/e-smith/signal-event console-save

will perform all the actions associated with the console-save event. (This is exactly what the console user interface does when you select save.)

Here is a list of some of the standard actions available with SME Server:

The following numbers have been assigned to the standard actions provided in the SME Server. These numbers are used in the symbolic links by convention. 

S05 init-files
S10 init-accounts
S20 delete-user
S20 delete-ibay
S25 create-user
S25 create-ibay
S30 conf-modules
S35 conf-ethernet
S40 conf-dialup
S45 conf-networking
S50 conf-security
S55 conf-servers
S60 conf-startup
S65 conf-other
S80 rebuild-ldap
S85 update-dns

Here is a list of some of the standard event definitions in SME Server:

Events with arguments

So far, we have described the following general principle throughout the e-smith system: Changes are made by altering the configuration files, then signalling events. The actions triggered by each event tend to regenerate entire configuration files, taking into account the latest configuration information.

However, some changes are best made incrementally. For example, consider the user-create event. One of its actions must be to update the LDAP directory, which it could do by deleting all of the users and recreating them based on the updated /home/e-smith/accounts file. However, this is inefficient. It would be better to simply add the new user incrementally.

But how is the action code to know which user was just added? The answer is: the new username is passed as an argument to the user-create event. This way the action programs triggered by the user-create event have a choice. They can either ignore the username argument and regenerate their output based on the updated list of accounts, or they can pay attention to the username argument, retrieve the rest of the information about the new user from the /home/e-smith/accounts file, and perform the incremental work to add the user.

Here is a list of some events which require an argument:

Templates

If you study the Perl code for the standard e-smith actions, you will see that it performs various system configuration tasks such as deleting files, changing permissions, creating user accounts, and so on. You will also find commands such as the following: esmith::util::processTemplate (\%conf, "/etc/resolv.conf");

This call to the processTemplate function reads the template file /etc/e-smith/templates/etc/resolv.conf, fills in the parameters based on the /home/e-smith/configuration file, then writes the output file /etc/resolv.conf. (This template mechanism is a standard Perl extension called Text::Template.)

Templates are copied literally to the output file, except for any portions in curly braces. Those portions are executed as Perl code and then substituted into the output. Here is an exerpt from the /etc/resolv.conf template:
search { $!DomainName }
nameserver 127.0.0.1

If the configuration file defined the domain name as e-smith.net, then the output file will read: search e-smith.net nameserver 127.0.0.1

Of course, the template does not have to contain only simple variable substitutions; large chunks of Perl code can be placed inside the braces.

To include curly braces literally in the output, they must be escaped with backslash characters.

Associated Concepts

Packaging and installation

The Red Hat kickstart feature is used to automate the e-smith installation.

The Red Hat comps file has been altered to define only the Base category, containing the exact list of packages to include in the e-smith server and gateway system.

The SME Server RPM contains all of the SME Server management code, including the templates to configure all the other applications.

The kickstart post-install script sets up the console user interface. Here is the complete post-install script:

# install updated driver modules
/sbin/e-smith/apply-patches

# set up initial configuration file
/sbin/e-smith/reset-config

# set up initial services and inittab
/sbin/e-smith/signal-event post-install

# add comment to /etc/motd
echo "Welcome to the e-smith server and gateway." > /etc/motd

Note that the e-smith post-install event is signalled. That event instantiates the /etc/inittab template, which in turn arranges for the /sbin/e-smith/console program to run on the first two virtual consoles. That is how the e-smith server and gateway arranges to boot into the user interface after installation.

ibays

From a programmer's view, each ibay is a directory which is shared by a number of different server applications (FTP, Apache, Samba, Appleshare). If you add new servers to the system, you must decide if it makes sense for the new servers to present a view of the ibays, and if so, write your configuration template carefully to take account of the ibays. (Review the templates for Apache, Samba, etc. for examples.)

copyright 2000 e-smith, inc. all rights reserved

Back to Documentation