<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="home" title="HomePage" href="HomePage.html" />
<link rel="help" title="HowToUseWiki" href="HowToUseWiki.html" />
<link rel="copyright" title="GNU General Public License" href="http://www.gnu.org/copyleft/gpl.html#SEC1" />
<link rel="author" title="The PhpWiki Programming Team" href="http://phpwiki.org/ThePhpWikiProgrammingTeam" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Language" content="en" />
<meta name="robots" content="noindex,nofollow" />
<meta name="language" content="en" />
<meta name="document-type" content="Public" />
<meta name="document-rating" content="General" />
<meta name="generator" content="PhpWiki" />
<meta name="PHPWIKI_VERSION" content="1.3.14" />

<link rel="stylesheet" type="text/css" charset="iso-8859-1" href="phpwiki-printer.css" />
<title>PhpWiki - Key concepts</title>
</head>
<body>

<div id="header">
  
<!-- Page title -->
<h1>Key concepts</h1>
</div>
<div id="content">



<div class="wikitext"><span class="plugin" id="CommentPlugin394"></span><p class="tightenable top">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. <br /></p>
<p class="tightenable"><b>It is not necessary to know these in order to use SME Server</b><br /></p>
<h2>Core Concepts</h2>
<p class="tightenable top">See the next section (<a href="Architecture%20overview.html" class="wiki">Architecture overview</a>) to understand more about how these items work with one another.</p>
<h3>Master configuration file</h3>
<p class="tightenable">The most important element of all is the master configuration file, stored in <code>/home/e-smith/configuration</code>. This file describes how the system should operate; what kind of Internet access to use, how email should be handled, and so on.</p>
<p class="tightenable bottom">The configuration file is an ASCII file containing a list of Name=Value mappings, one per line. Here is a subset of it:
<br /> <br /></p>
<pre class="tightenable top bottom">
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</pre>
<p class="tightenable top"><br />
The other important configuration file is <code>/home/e-smith/accounts</code>, which is in a similar format, and specifies all of the accounts on the system. We classify accounts into three types.</p>
<p class="tightenable"><b>System accounts:</b> These are accounts such as root, bin, admin, etc.</p>
<p class="tightenable"><b>User accounts:</b> These are accounts created for individual users at the local organization. Each account has a POP mailbox and an area for storing files.</p>
<p class="tightenable"><b>Ibay accounts:</b> 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.</p>
<h2>User interfaces</h2>
<p class="tightenable">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 <b>signalling an event</b> (more on this in the next section).</p>
<h3>Console interface</h3>
<p class="tightenable">The console interface is a single bash shell script called <code>/sbin/e-smith/console</code>. It uses the <b>whiptail</b> program to display the configuration screens. Whiptail was written at Red Hat Software as a replacement for the old <b>dialog</b> 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.)</p>
<p class="tightenable bottom">The e-smith software modifies the <code>/etc/inittab</code> file during installation, so that the first two virtual terminals (Ctrl-Alt-F1 and Ctrl-Alt-F2) run <code>//sbin/e-smith/console</code> instead of the usual <code>/sbin/mingetty</code> which displays the usual login prompt. The relevant part of <code>//etc/inittab</code> is:
<br /> <br /></p>
<pre class="tightenable top bottom">
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</pre>
<p class="tightenable top bottom"><br /></p>
<h3>Web-based manager interface</h3>
<p class="tightenable">The web-based manager is a set of CGI scripts stored in the <code>/etc/e-smith/web</code> directory. This directory is organized to support multiple web-based user interfaces (called <b>panels</b>) with slightly different features and permissions. The e-smith server and gateway normally comes with two panels: the <b>manager panel</b> (which requires an admin password and allows most system parameters to be configured) and the <b>password panel</b> (which does not require a password and allows users to change their own password).</p>
<p class="tightenable">The web directory contains three subdirectories. The first subdirectory, <b>common</b>, contains any static files (such as images) which are used by multiple panels.</p>
<p class="tightenable">The second subdirectory, <b>functions</b>, 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 <b>www</b>). 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.</p>
<p class="tightenable">The third directory, <b>panels</b> 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.</p>
<p class="tightenable">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.</p>
<h3>Actions and events</h3>
<p class="tightenable">Whenever the user interface modifies the master configuration files, it must <b>signal an event</b> to regenerate the various server application configuration files according to the new configuration.</p>
<p class="tightenable">Each event is associated with a list of <b>actions</b> 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.</p>
<p class="tightenable">For example, the <b>console-save</b> event performs the following actions:</p>
<ul><li class="tightenable bottom">conf-modules</li>
<li class="tightenable top bottom">conf-ethernet</li>
<li class="tightenable top bottom">conf-dialup</li>
<li class="tightenable top bottom">conf-networking</li>
<li class="tightenable top bottom">conf-security</li>
<li class="tightenable top bottom">conf-servers</li>
<li class="tightenable top bottom">conf-startup</li>
<li class="tightenable top bottom">conf-other</li>
<li class="tightenable top">rebuild-ldap</li>
</ul>
<p class="tightenable">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:</p>
<ul><li class="tightenable bottom">/etc/securetty</li>
<li class="tightenable top bottom">/etc/services</li>
<li class="tightenable top bottom">/etc/shells</li>
<li class="tightenable top bottom">/etc/ftpusers</li>
<li class="tightenable top bottom">/etc/inetd.conf</li>
<li class="tightenable top bottom">/etc/hosts.deny</li>
<li class="tightenable top bottom">/etc/hosts.allow</li>
<li class="tightenable top">/etc/pam.d/passwd</li>
</ul>
<p class="tightenable">Note that any particular config file is managed by at most one action. You don't want multiple action generating the same file.</p>
<p class="tightenable">The actions are programs stored in the directory <code>/etc/e-smith/events/actions</code>. To create a new action called <b>myaction</b> you simply create a program to perform the action and save it as <code>/etc/e-smith/events/actions/myaction</code>. Actions can be written in any programming language, but Perl code is preferred.</p>
<p class="tightenable bottom">Each event is defined as a subdirectory of <code>/etc/e-smith/events</code> containing symbolic links to the appropriate actions (this system is loosely modelled after the <code>/etc/rc.d</code> mechanism for starting servers). For example, if you examine the console-save directory:
<br /> <br /></p>
<pre class="tightenable top">
# cd /etc/e-smith/events/console-save
# ls -l
total 0
S30conf-modules -&gt; ../actions/conf-modules
S35conf-ethernet -&gt; ../actions/conf-ethernet
S40conf-dialup -&gt; ../actions/conf-dialup
S45conf-networking -&gt; ../actions/conf-networking
S50conf-security -&gt; ../actions/conf-security
S55conf-servers -&gt; ../actions/conf-servers
S60conf-startup -&gt; ../actions/conf-startup
S65conf-other -&gt; ../actions/conf-other
S80rebuild-ldap -&gt; ../actions/rebuild-ldap</pre>
<p class="tightenable">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).</p>
<p class="tightenable">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 <code>/etc/e-smith/events</code>.</p>
<p class="tightenable">The program <code>/sbin/e-smith/signal-event</code> 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:</p>
<p class="tightenable"><code>/sbin/e-smith/signal-event console-save</code></p>
<p class="tightenable">will perform all the actions associated with the <b>console-save</b> event. (This is exactly what the console user interface does when you select <b>save</b>.)</p>
<p class="tightenable">Here is a list of some of the standard actions available with SME Server:</p>
<ul><li class="tightenable bottom">conf-dialup</li>
<li class="tightenable top bottom">conf-ethernet</li>
<li class="tightenable top bottom">conf-modules</li>
<li class="tightenable top bottom">conf-networking</li>
<li class="tightenable top bottom">conf-other</li>
<li class="tightenable top bottom">conf-security</li>
<li class="tightenable top bottom">conf-servers</li>
<li class="tightenable top bottom">conf-startup</li>
<li class="tightenable top bottom">create-ibay</li>
<li class="tightenable top bottom">create-user</li>
<li class="tightenable top bottom">delete-ibay</li>
<li class="tightenable top bottom">delete-user</li>
<li class="tightenable top bottom">init-accounts</li>
<li class="tightenable top bottom">init-files</li>
<li class="tightenable top bottom">rebuild-ldap</li>
<li class="tightenable top bottom">restart-servers</li>
<li class="tightenable top">update-dns</li>
</ul>
<p class="tightenable bottom">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.
<br /> <br /></p>
<pre class="tightenable top">
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</pre>
<p class="tightenable">Here is a list of some of the standard event definitions in SME Server:</p>
<ul><li class="tightenable bottom">console-save</li>
<li class="tightenable top bottom">ibay-create</li>
<li class="tightenable top bottom">ibay-delete</li>
<li class="tightenable top bottom">ip-change</li>
<li class="tightenable top bottom">manager-misc</li>
<li class="tightenable top bottom">post-install</li>
<li class="tightenable top bottom">user-create</li>
<li class="tightenable top">user-delete</li>
</ul>
<h3>Events with arguments</h3>
<p class="tightenable">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.</p>
<p class="tightenable">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 <code>/home/e-smith/accounts</code> file. However, this is inefficient. It would be better to simply add the new user incrementally.</p>
<p class="tightenable">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.</p>
<p class="tightenable">Here is a list of some events which require an argument:</p>
<ul><li class="tightenable bottom">user-create (user name)</li>
<li class="tightenable top bottom">user-delete (user name)</li>
<li class="tightenable top bottom">ibay-create (ibay name)</li>
<li class="tightenable top bottom">ibay-delete (ibay name)</li>
<li class="tightenable top">ip-change (new IP address)</li>
</ul>
<h3>Templates</h3>
<p class="tightenable">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:
<code>
<span><a href="esmith.html" class="wiki relation">esmith</a><span class="relation-symbol">::</span><a href="util%3A%3AprocessTemplate.html" class="wiki">util::processTemplate</a></span> (\%conf, &quot;/etc/resolv.conf&quot;);</code></p>
<p class="tightenable">This call to the processTemplate function reads the template file <code>/etc/e-smith/templates/etc/resolv.conf</code>, fills in the parameters based on the <code>/home/e-smith/configuration</code> file, then writes the output file <code>/etc/resolv.conf</code>. (This template mechanism is a standard Perl extension called <span><a href="Text.html" class="wiki relation">Text</a><span class="relation-symbol">::</span><a href="Template.%29.html" class="wiki">Template.)</a></span></p>
<p class="tightenable">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: <br />
<code>search { $!<u title="Empty link to: DomainName" onmouseover="window.status=&quot;Empty link to: DomainName&quot;; return true;" onmouseout="window.status='';return true;" class="wikiunknown">DomainName</u> }</code> <br />
<code>nameserver 127.0.0.1</code></p>
<p class="tightenable">If the configuration file defined the domain name as <b>e-smith.net</b>, then the output file will read:
<code>
search e-smith.net
nameserver 127.0.0.1</code></p>
<p class="tightenable">Of course, the template does not have to contain only simple variable substitutions; large chunks of Perl code can be placed inside the braces.</p>
<p class="tightenable">To include curly braces literally in the output, they must be escaped with backslash characters.</p>
<h2>Associated Concepts</h2>
<h3>Packaging and installation</h3>
<p class="tightenable">The Red Hat <b>kickstart</b> feature is used to automate the e-smith installation.</p>
<p class="tightenable">The Red Hat <b>comps</b> file has been altered to define only the <b>Base</b> category, containing the exact list of packages to include in the e-smith server and gateway system.</p>
<p class="tightenable">The <b>SME Server RPM</b> contains all of the SME Server management code, including the templates to configure all the other applications.</p>
<p class="tightenable">The kickstart post-install script sets up the console user interface. Here is the complete post-install script:</p>
<p class="tightenable"><code># install updated driver modules</code><br />
<code>/sbin/e-smith/apply-patches</code><br />
<br />
<code># set up initial configuration file</code><br />
<code>/sbin/e-smith/reset-config</code><br />
<br />
<code># set up initial services and inittab</code><br />
<code>/sbin/e-smith/signal-event post-install</code><br />
<br />
<code># add comment to /etc/motd</code><br />
<code>echo &quot;Welcome to the e-smith server and gateway.&quot; &gt; /etc/motd </code><br /></p>
<p class="tightenable">Note that the e-smith <b>post-install</b> event is signalled. That event instantiates the <code>/etc/inittab</code> template, which in turn arranges for the <code>/sbin/e-smith/console</code> 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.</p>
<h3>ibays</h3>
<p class="tightenable">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.)</p>
<hr />
<p class="tightenable top bottom">copyright 2000 e-smith, inc. all rights reserved</p>
<hr />
<p class="tightenable top bottom">Back to <a href="Documentation.html" class="wiki">Documentation</a></p>
</div>

<div id="footer">  <hr class="printer" noshade="noshade" />
<p class="editdate">Owner: &quot;RonM&quot;  Last edited on January 21, 2006 11:42 am by &quot;RonM&quot;</p>
</div>

</div>
<!-- Add your Disclaimer here -->
</body>
</html>
