Up   Diese Seite auf Deutsch.

Installation and Administration of SeL

Installation and configuration of SeL

Obtaining SeL
To obtain a copy of the current SeL distribution please send an eMail to the author:
matthias@hrz.uni-kassel.de (Andreas Matthias) 

PGP-Information:
----------------
Type Bits/KeyID    Date       User ID
pub  1024/802DBD35 1998/07/15 Andreas Matthias 
            Key fingerprint = DE 54 40 E0 19 F7 A4 F3  39 DA AB 22 0B 33 04 79
The distribution file will be signed with this key.
Supported platforms
SeL runs on all Unix platforms, for which a GNU-C development environment and an Apache-WWW-Server is availabe. Beyond GCC the source complitaion also requires flex and bison. SeL will probably not run with other versions of lex and yacc.

Under development, SeL was tested on AIX, Linux and FreeBSD.

Someone said, SeL somewhere already runs on NT but we don't support that directly. It shouldn't be too much of a problem to compile it on windows, though...

Extracting the archive
Change to a temporary directory:

cd /tmp
mkdir sesame
cd sesame
gtar xvfz sel-*.tgz

A new directory "sel-VERSION" is created, whereas VERSION is the actual version number. This new directory contains all files of the package.

Configuration
Manul configuration is required in three places:
  1. The file config.h
  2. The Makefile
  3. The file sel.conf
The file config.h Here you configure a couple of things which have to be declared before compilation:

#define SAFE_FILE_PREFIX_COUNT 3
#ifdef DECLARE_PREFIX_VARS
char *safe_file_prefix[SAFE_FILE_PREFIX_COUNT]= {
  "/home/WWW/docs/", 
  "/home/WWW/homepages/",
  "/etc/motd"
};

Here "secure" paths have to be declared. All files that may be included to a SeL file at runtime have to reside somewhere below these paths. Typically, this is a WWW server's DOCUMENT_ROOT path. SAFE_FILE_PREFIX_COUNT is used to declare the number of secure paths. It is important to adjust this number to the number of path entries.

#define INCLUDE_PATH_COUNT 3
#ifdef DECLARE_PREFIX_VARS
char *include_path[INCLUDE_PATH_COUNT]= {
  "/home/WWW/docs/", 
  "/home/WWW/homepages/",
  "./"
};

Paths declared here will be default search paths for libraries and masterfiles. They will be searched when library inclusions using "lib" do not contain full paths. It may be useful to enter the WWW server's DOCUMENT_ROOT path here.

If (as shown in the example above) "./" is declared in this list, SeL will look up the path of the running SeL file. 

#define CONFIG_FILE "/home/hrz/matthias/design2/latest/sel.conf"

The complete path (including file name) of the SeL configuration file. An example configuration file is included in the distribution directory as sel.conf.sample. If SeL executions seem to hang, this path is probably wrong.

#define MAX_SOURCE_SIZE 512*1024

The maximum size (in bytes) of files which may be included using "$_include()". This can remain the default value of 512k.

#define MAX_OVERRIDES 128

The maximum number of override directives for dynamic libraries. This value slightly effects the performance of SeL. Therefore, it is a good idea to keep it to a minimum. For more information please refer to masterfile override funktion configuration below.

#define MAX_LIBPATH 1024

The maximum length (in characters) for absolute library paths. Normally, the default value (1024) should be enough.

The Makefile. In the Makefile only little has to be configured. The most important entry here is the path to the Flex library "libfl.a" which is to be declared in the Masterfile's top part.

# Set this to your libs directory (where libfl.a is located)
LIBDIR = /usr/aix4-PD/lib

If on the installation machine the Flex library resides in a location which is searched by the linker anyway (e.g. /lib, /usr/lib, /usr/local/lib) this line can be commented out.

The following only has to be adjusted, when compiling results errors complaining about a missing file "libgen.h". 
MISSING_DIRNAME = -DMISSING_DIRNAME
DIRNAMEOBJ	= dirname.o

These two lines are commented out. In case of the compile error mentioned above, they have to be activated (remove comment characters "#" at line starts). This might typically be necessary on old Linux installations as well as on FreeBSD.

The file sel.conf Here the masterfile override function is configured. This is explained below. For a first test installaton, this file can remain unchanged.

Compilation
Flex, Bison, GNU-Make, and the GNU-C compiler are required. A different make and different ANSI-C compilers might work as well, whereas it is not likely that different Lex-/Yacc flavours will run. 

cd /tmp/sel-VERSION
make

The result looks like this:

gmake ghkf
gmake[1]: Entering directory `/tmp/sel-04-test2'
bison -y -d -tv ghkf.y
cc       -g -c y.tab.c -DDECLARE_PREFIX_VARS
flex  ghkf.l
cc       -g -c lex.yy.c
cc       -g -c stack.c
cc -o ghkf y.tab.o lex.yy.o stack.o  -L/usr/aix4-PD/lib -lfl
strip ghkf
gmake[1]: Leaving directory `/tmp/sel-04-test2'

  • In older SeL versions a path declaration for the C preprocessor was required. Since SeL version 0.4 and later the preprocessor is not required anymore.
  • In older SeL versions "sel" was a shell script calling the interpreter. Since SeL version 0.5 this is no longer the case: now there is only one SeL executable called "sel" (previously called "ghkf").
Testing the program
Run SeL with a test file:

./sel <filename>

whereas filename is the name of one of the test*.sel files contained in the SeL distribution. Please read the output and decide yourself whether everything looks okay.

Congratulations! The SeL interpreter now runs on your box.

Connecting to a WWW server
For the following steps you need write access to the Apache configuration file and the Apache directories, as well as permission to start the httpd process.

These steps should be taken by someone with experience in WWW server configuration.

Creating a Content Handler directory. The SeL interpreter has to be installed as an Apache Content Handler. For this reason, it has to be installed to a directory known to Apache as a CGI directory.

Early SeL versions created a security problem when installed in a CGI directory. Since SeL version 0.4 this bug is fixed.

For the following discussion we assume the Apache server is installed under /usr/local/httpd and /usr/local/httpd/cgi-bin is the CGI directory.

Frist, we create a new directory for SeL and then copy the previoulsly created program to this new directory. The name of the binary should be changed to "sel.cgi" as some Apache installtions require a ".cgi" extension.

mkdir /usr/local/httpd/cgi-bin/sel
cd /tmp/sel-VERSION
cp sel /usr/local/httpd/cgi-bin/sel/sel.cgi

Creating a CGI Handler Wrapper.

Older SeL versions required the additional creation of a file sel.cgi. In SeL version 0.4 the script sel was used. Since SeL 0.5 sel is a regular binary executable. The auxillary program splitlines has become unnecessary as its functionality is now integrated in the SeL interpreter.

Activating the handler. First, you have to think up the file extension your server will use to identify SeL files. We suggest ".sel" or ".ghk" but you may use any other extension which will not collide with already defined ones on your server. At the University of Kassel for example the extension ".ghk" is in use.

Now change to the Apache configuration directory (in our example /usr/local/httpd/conf/) and edit the file srm.conf or your equivalent (recent Apache installations use httpd.conf). Insert the following lines:

AddHandler sel .sel
AddHandler sel .SEL
Action sel /cgi-bin/sel/sel.cgi

(".SEL" is required for DOS/Windows users, who sometines use wrong FTP client configurations.) Please replace the extension ".sel" in this Addhandler entry with your preferred one.

Now end the httpd process (if it's running) and (re-) start it.

Creating a masterfile
Below a simple masterfile for user defined entries AUTHOR, TITLE, DATE and CONTENT is shown. AUTHOR consists of three declarations: AUTHOR.NAME, AUTHOR.ADDR and AUTHOR.EMAIL (name, snailmail address and email address. Please note, that it might be more useful to divide a snailmail address into its atoms, especially when SeL is interfaced to a database).

fwd TITLE CONTENT AUTHOR.NAME AUTHOR.ADDR AUTHOR.MAIL DATE;

!PAGE( void )
	<SQD>
		<HEAD>
		<TITLE>
	</SQD>
	$TITLE
	<SQD>
		</TITLE>
		</HEAD>
		<BODY BGCOLOR="#ffffa0">
		<H2>
	</SQD>
	$TITLE
	<SQD>
		</H2>
	</SQD>
	$CONTENT
	<SQD>
		<P><HR>
		<TABLE WIDTH="100%" BORDER=0>
		<TR><TD>
	</SQD>
	$AUTHOR.NAME
	<SQD>
		<P>
	</SQD>
	$AUTHOR.ADDR
	<SQD>
		<P>mailto:
	</SQD>
	$AUTHOR.MAIL
	<SQD>
		<P></TD><TD>
	</SQD>
	$DATE
	<SQD>
		</TD></TR></TABLE></BODY>
	</SQD>
	;

$PAGE().

Here is a simple SeL file, using the masterfile shown above:

lib "simple.mas";

=TITLE "Testseite";
=CONTENT <SQD>
	<IMG SRC="http://www.uni-kassel.de/campus.gif"><P>
	Eine Testseite.
	<PRE>
	Test 
	</PRE>
	</SQD>
;

=AUTHOR.NAME "Andreas Matthias";
=AUTHOR.ADDR "Moenchebergstr. 13<BR>Kassel";
=AUTHOR.MAIL "matthias@hrz.uni-kassel.de";
=DATE "1999-11-16";

The example files above are contained in the distribution as contrib/simple.mas bzw. sontrib/simple.sel.

Configuring the masterfile override function

It is an obvios advantage of SeSAMe that it allows readers to pick masterfiles which suit their needs. Nevertheless, for this purpose these masterfiles have to be released by the host's WWW administrator. This is done in sel.conf. The location of sel.conf was specified before compilation.

The file sel.conf has the following general syntax:

COMMAND parameter1 parameter2 ...

In case of the master override function the command is "OVERRIDE" and its parameters are:

  1. the URL extension readers may use to activate an alternative masterfile
  2. the masterfile which is replaced
  3. the masterfile activated by this extension
For example:

OVERRIDE style=plain ghk.mas plain.mas

(as sel.conf.sample this file is part of the SeL distribution). The example shown above has the following effect: When a reader requests a URL extended by "style=plain" all references to "ghk.mas" are replaced by references to "plain.mas". If more than one alternative masterfile is offered, "sel.conf" can contain several OVERRIDE lines: 
OVERRIDE style=plain ghk.mas plain.mas
OVERRIDE style=frames ghk.mas frames.mas
OVERRIDE style=french ghk.mas frenchlayout.mas

This overwrites the "lib" entries in requested SeL files. In the exapmle above, a request could look like this:

http://www.uni-kassel.de?style=plain

Of course, this can be offered as a clickable link whithin documents (ideally, in any of the alternative masterfiles).

Sometimes you may want to invoke a particular masterfile regardless of the masterfile that is active when a masterfile override pattern is encountered. This can be achieved with the wildcard symbol "*":

OVERRIDE style=plain * plain.mas

To allow readers to return from override mode, an additional OVERRIDE pattern has to be configured, which switches all other overrides off. This is done as shown below:

OVERRIDE style=ghk none none

Again, the pattern used to switch off the masterfile OVERRIDE function stands at first postition. Instead of masterfiles' names, at second and third position goes the keyword "none". Unlike any othe OVERRIDE declaration this pattern does not stay persistent until the naxt explicit style change of a session. It canbe used to return to the default style (which is delivered without any URL style extensions). The interpreter will delete it from requested URLs).

It is a good idea to include a link of this patten in all alternative masterfiles to allow readers to return to the default design.

Frequently asked questions
Known bugs
Last modified: Mon Apr 23 16:51:47 MES 2001