ELOG Electronic Logbook Home Page

Introduction

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 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 searched using these classes. The right pane on the left image shows a search for all messages of type "Configuration", and the lower pane shows the search result. It is also possible to use full-text search in the subject of message body. While logbook entries are usually displayed one entry per page, they can also be listed consecutively which makes it easily possible to produce a paper 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

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

UNIX installation

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.

Solaris

gcc -L/usr/lib/ -ldl -lresolv -lm -ldl -lnsl -lsocket elogd.c -o elogd

NT installation

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:

1. Copy SRVANY.EXE to %window%\system32\.
2. Use INSTSRV to install SRVANY.EXE as a service named "elogd":

   INSTSRV ELogd %windir%\system32\srvany.exe

3. Run REGEDIT and find "My Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\elogd".
4. Under the Elogd registry key, create a new key called Parameters via Edit/New/Key.
5. 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)
6. 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.

It was reported that the above mentioned srvany can only be run if the cygwin1.dll from the CygWin project is installed.

Configuration

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.

To test the daemon, connect to your host via

http://your.host:8080/

If port 80 is used, the port can be omitted in the URL. If several logbooks are defined on a host, they can be specified in teh URL like

http://your.host/<logbook>

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

[Linux]
Theme = default
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

Following options are possible in the configuration file:

• Theme
  A theme determines which layout and colors are used for a logbook, similar to skins in other programs. The theme option points to a subdirectory under the directory of the configuration file, which contains all files for that theme. The format of these files is described under the Themes section.

• Comment
  The comment is displayed on the logbook selection list. The selection list is displayed if more than one logbook is defined on a host and no logbook is explicitly specified in the URL.

• Data dir
  Each logbook has a separate directory where the logbook entries are stored, which is controlled by the this statement. Note that the directories must exist and must be writable by the elogd program.

• Types
  
• Categories
  These statements define the classes of messages which can be entered and queried in a logbook.

• Authors
  An optional authors list can be supplied so everybody can select her/his name from a drop-down list.

• Read password
  
• Write password
  
• Delete password
  
• Write password expiration
  
• Delete password expiration
  The optional password statements contain passwords for reading and writing to the logbook and to delete entries in the lobgook. The passwords are stored in an encoded form. To change them, one can use elogd directly with the -r , -w and -dflags. To set the write password of logbook "linux" to "test", on would enter:
  elogd -w test -l linux

  The read password is queried by the browser with a pop-up window and usually stays active for the entire browser session. The write and delete passwords are stored in cookies on the browser side and have an expiration time of 24h. After that time, the passwords have to be re-submitted. This time can be changed with the statement Write Password Expriation = x or Delte Password Expriation = x, where x is the expiration time in hours. It should be noted that on some systems the daylight saving time is calculated incorrectly, which can cause time offsets of one our between a server PC and a client PC. In this case one hour has to be added to the expiration time.

• SMPT host
  
• Email <name> = list
  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 statement Email <name> = list 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.

• 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 default = 0/1
  If this flag is 1, the buttons "Last day" and "Last 10" produce summary listings instead displaying full messages. In the "Query" page, the "Summary only" check box is checked by default.

• 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.

• Suppress default = 0/1
  This specifies the default state of the "Suppress Email notification" button on the new message entry from. For installations where normally a Email notification is not necessary, the default can be set to 1. Only if an urgent message is entered, the users can then uncheck the suppress box.

Themes

Most of the options in the theme.cfg are self-explanatory, the colors are coded as #RRGGBB, where RR is a 8-bit hexadecimal value for the red part, GG for the green and BB for the blue part, repectively. Since theme configuration files are re-read at each access, the elogd daemon does not have to be restarted after a change in the theme configuration file.

Following two images display the same logbook page using different themes:

Secure connections

1. Start elogd. If another Web server is running on port 80, use a different port.

2. 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.

3. Connect to your logbook with a browser which supports SSL via:

   https://your.host.name/

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

Submitting pages via the Web

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

Submitting pages via elog

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

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 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: