ELOG Electronic Logbook Home Page

by Stefan Ritt

Current version: 1.0.3

Introduction

ELOG is an electronic logbook with a Web interface. It runs under MS Windows and UNIX and is under the GNU Public License.

The logbook functionality is implemented by a single daemon elogd program which is written in C. It uses structured ASCII files to store logbook pages, which can be retrieved through any web browser. Logbook entries can either be entered with a command line program or through the Web interface. Since only forms and tables are used, no Java or Javascript are necessary, which makes the logbook display very fast.

One the left upper panel one can see a typicl logbook page displayd by Netscape Navigator. Each logbook page can contain up to three attachments in a similar way to emails. This makes it possible to store images or text files and retrieve them easily. One can for example attach an example configuration file which can later be copied to the local machine with the "Save As..." function of the Web browser.
Several logbooks can be served though a single elogd daemon. Each logbook can use classes for message types and message categories. The logbook can then be queried using these classes. The right pane on the left image shows a query for all messages of type "Problem fixed". Of course it is also possible to use full-text search.
While logbook entries are usually displayed one entry per page, they can also be listed consecutively as shown in the bottom page. This makes it easily possible to produce a printout of a logbook.
Logbook pages can be edited or deleted. This feature can be turned off in the configuration file so that a logbook entries cannot be changed after it has been submitted.
An additional feature is the automatic generation of a notification email messages based on a certain type or category of a logbook entry.

The features of ELOG make it useful for several applications:

Personal Logbooks. Personal notes can be witten into ELOG and can then be retrieved from anywhere with a Web browser. This makes it handy for PC supporters who have to go around in companies or laboratories and don't want to carry their paper logbook with them. The same holds true for people traveling around a lot. The logbook database consists of plain ASCII files which can copied easily between different computers to have local access, for example on a notebook with no network connection.
Shared Logbooks. Logbooks can be shard by several people, for reading and optionlly for writing. This way collaborations can share and exchange information similar to a news group. This is supported by the Reply command in ELOG with which one can create "Threads" of messages. Users can be notified by email when new entries are added to the logbook. Compared to a news server, the installation of ELOG is much simpler.
Shift Logbooks. If the Allow delete and Allow edit flags are off in ELOG, one cannot modify a message once it's entered. This can be useful for shift logbooks for example in accelerator control rooms where each message becomes a "document" with a time and author stamp. ELOG was orginally developed as a shift logbook for the PiBeta and Muegamma particle experiments at PSI.
File collections. Since files can be attached to ELOG messages, the system can be used to store and retrieve files. This can be used to store UNIX configuration files, which need to be accessible by several people over the web, or to store images. Since ELOG features an elaborate query facility, messages can be searched for by specifying several categories.
Problem collections. The notebook can be used by a a system administrator for example to collect user problems and distribute fixes. If someone adds a problem, an email is automatically sent to the the administrator.

Installation

Currently ELOG has only been tested under Windows NT and Linux, but it might also run on other UNIXes.

ELOG is part of the MIDAS data acquisition system, but it can also be downloaded separately.

UNIX installation

Expand the TAR file with tar -xzvf elog-x.x.tar.gz. This creates a subdirectory elog-x.x where x.x is the version number. In that directory execute make, which creates the executables elogd and

elog

. These executables can then be copied to a convenient place like /usr/local/bin or ~/bin. The daemon elogd can be started manually with

elogd -p 8080

where the -p flag specifies the port. Without the -p flag, the server uses the standard WWW port 80. Note that ports below 1024 can only be uses if elogd is started a root, or the "sticky bit" is set on the executable.

If the program complains with something like "cannot bind to port...", it could be that the network is not started on the Linux box. This can be checked with the /sbin/ifconfig program, which must show that eth0 is up and running.

To start the daemon automatically, it can be run from the /etc/rc.d/init.d system. Please consult your distribution to find out how to do that. I use a script which I put under /etc/rc.d/init.d. Then I call

chkconfig --add elogd

which works fine under RedHat 6.x.

NT installation

Download and execute the elogxxx.exe file which expands to the two source files and the executables (do not omit the

exe

extension, it's necessary!). The daemon elogd.exe can be started directly. Under Windows, the ports below 1024 can be used without restriction. So if no web server is running on the same PC the ELOG daemon listens under the standard Web port 80.

Under Windows NT/2000, elogd can be started also as a service. To do so, one needs the programs srvany.exe and instsrv.exe from the Windows Resource Kit. If you don't have the Resource Kit, these programs can probably be downloaded from various places like this.. Then follow these steps:

Copy SRVANY.EXE to %window%\system32\.
Use INSTSRV to install SRVANY.EXE as a service named "elogd":
```
INSTSRV ELogd %windir%\system32\srvany.exe
```
Run REGEDIT and find "My Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\elogd".
Under the Elogd registry key, create a new key called Parameters via Edit/New/Key.
Under the new key Parameters, create the following three STRING values:
- Application set to "c:\elog\elogd.exe" (or wherever you installed the elogd program)
- AppDirectory set to "c:\elog" (or wherever you installed the elogd.cfg file)
- AppParameters set to "-p 8080" (or any other port which you would like to use, put an empty string for port 80)
Under NT4, open the Services entry in the control panel, under Windows 2000 right-click on "My Computer", click to "Manage", select "Services and Applications", expand it and select "Services". On the right panel, double-click "ELogd". Then start the service manually and change the startup type to "Automatic". This way the elogd program gets started automatically on every reboot.

Test the service by accessing your logbook via your browser.

Configuration

An ELOG daemon can server multile logbooks. Logbooks are defined in the elogd.cfg file. If this file is not in the current directory where elogd is started, it can be specified via the command line parameter -c . Under UNIX, you would typically start the daemon with

elogd -p 8080 -c /usr/local/elog/elogd.cfg -D

where the -D flag tells elogd to start as a daemon in the background (does not work under NT). Once the configuration file is changed, the daemon has to be restarted.

The configuration file elogd.cfg has a simple ASCII format, here is an example:


[Linux]
Comment = General linux tips and tricks
Write Password=aGl4X21pZA==
Data dir = /usr/local/elog/linux
Types = Routine, Software Installation, Problem Fixed, Configuration, Tips & Tri
cks, Info, Other
Categories = General, Hardware, Software, Network, Applications, Shell, Account,
 Packages, Daemons, Other
Authors = you, me, nobody

[PC]
Comment = PC general informatoin
Data dir = /usr/local/elog/pc
Types = Routine, Common Problems, Problem Fixed, BIOS Configuration, Other
Categories = General, Hardware, Software, Network, Other
SMTP host = mailsend.your.domaine
Email Common Problems = name@address, othername@otheraddress

Each logbook is defined by a [<name>] section where <name> is the name of the logbook. Each logbook has a separate directory where the logbook entries are stored, which is controlled by the Data dir statement. Note that the directories must exist and must be writable by the elogd program.

The Types and Categories define the classes of messages which can be entered and queried in a logbook. An optional Authors list can be supplied so everybody can select her/his name from a drop-down list. The optional Write password and Read Password statements contain the password in an encoded form. To change them, one can use elogd directly with the -r and -w flags. To set the write password of logbook "linux" to "test", on would enter:

elogd -w test -l linux

To send emails automatically on new logbook entries, a SMTP host = entry has to be present in the configuration file. The host name you can get from your email program or your local system administrator. To submit an email based on a type or category, one needs the line:

Email <name> = mail address

in the configuration file where name is one of the type or category names. Several mail addresses might be supplied, separated by commas. Multiple Email xxx statements might be present in a configuration file. The statement Email All = sends an email notification independent of the type and category.

Following additional flags are avaliable in the configuration file:

Allow delete = 0/1 If this flag is 1, messages can be deleted. Default is 0.
Allow edit = 0/1 If this flag is 1, messages can be edited. Default is 1.
Summary on last = 0/1 If this flag is 1, the buttons "Last day" and "Last 10" produce summary listings instead displaying full messages.
Summary lines = x This specifies the number of text lines displayed in a summary page. Zero displays no text at all. The default is 3.

Secure connections via stunnel

Although the elogd progream does not support secure connections over SSL directly, it is possible to use it together with stunnel to do so. Four steps are necessary:

Put the section:
```
[Global]
URL = https://your.host.name
```
into the elogd.cfg file. This makes elogd to use https: instead of http: for all links inside a logbook.
Start elogd. If another Web server is running on port 80, use a different port.
Install the stunnel program if not already done and start it with:
```
stunnel -d 443 -r your.host.name:80
```
Substitute the port 80 if you started elgod on another port. This causes stunnel to receive requests on the https port 443 and forwards them to the elogd port.
Connect to your logbook with a browser which supports SSL via:
```
https://your.host.name/
```

The URL entry in elogd.cfg can also be used to access elogd through a SSH tunnel. To do so, open an SSH tunnel like:

ssh -L 1234:your.server.name:8080 your.server.name

This opens a secure tunnel from your local host, port 1234, to the server host where the elogd daemon is running on port 8080. Then start elogd -p 8080 with the entry URL = http://localhost:1234 in the configuration file. Now you can access http://localhost:1234 from your browser and reach elogd in a secure way.

Submitting pages via the Web

New logbook entries are submitted by pressing the New button in the ELOG display page. This opens a form where one can enter the author, type, category, subject, text and optional attachments.

It is possible to submit the text as HTML text, so one can put HTML formatting tags inside the text. Note that one then needs the tag <P> tag to start a new paragraph.

Attachments can be submitted similar to email attachments. Enter the file name or push the Browse button to select a local file. This file gets submitted into the logbook. If it is a picture (GIF or JPEG), it gets displayed in the logbook page. Otherwise only a link to the file inside the logbook is shown. By clicking at that link, the original file can be downloaded to the local hard disk again. This feature can be used to store things like Linux configuration files, which can then be retrieved easily without any copy and paste.

It is possible to pre-populate the author, type, category and subject field. This can be useful if always the same author for example submits entries from one PC. In this case, she/he needs a bookmark of the form:

http://your.host/your_logbook/?cmd=New&pauthor=joe&ptype=Info

If this bookmark is executed, the author field gets automatically pre-populated with "joe" and the type "Info" gets selected. The same is possible using pcategory and psubject. So one can define a set of bookmarks for certain types of logbook entries.

Submitting pages via `elog`

In addition of submitting logbook entries through the Web interface, a standalone program elog can be used. The parameters are:

elog -h hostname [-p port] [-l logbook] [-w password] -a author -t type
     -c category -b subject -f attachment -m textfile | text

If some of the parameters are not supplied, they are asked for interactively. The message text can be entered directly. If the EDITOR environment variable is set, the specified editor is used. Alternatively, the message text can be submitted from a file with the -m flag.

The elog program makes it possible to submit logbook entries automatically by the system or from scripts. In some shift logbooks this feature is used to enter alarm messages automatically into the logbook.

How it works

The concept of ELOG is very simple. The elogd daemon contains an integrated full Web server which does not serve files like standard Web servers, but reads logbook entries from its database and formats them into HTML. Since only forms and tables are used, no Java or Javascript is necessary. The system does not use any images on purpose to reduce the amount of data to be transferred. Since the ELOG daemon contains a Web server, no additional server like Apache is required.

The database ELOG save messages is a plain ASCII format. One file is created for each day in the form YYMMDD.log where YY is the year, MM the montdh and DD the day. The only non-ASCII character is a form-feed at the end of each message. If one sends a log file directly to a printer, each message is therefore printed on a separate page. Note that the log files should not be edited manually, since this could invalidate the internal database structure (each header contains the message length in bytes which then would become wrong).

If attachment are submitted, they are saved as separate files with the name YYMMDD_HHMMSS_name where in addition to the date the time is specified and name is the original file name of the attachment. To copy the database to another computer, only the *.log files and the attachment files need to be copied. To copy for example all files form March 2001, one can select them with 0103??.log and 0103??_*.


Visits to this page since 23 May 2001:





Stefan Ritt, May 23rd, 2001