ELOG - Syntax of elogd.cfg  

Global and individual logbook options for an ELOG server

The configuration file elogd.cfg contains entries which define the structure of logbooks and the behaviour of elogd. The file has a simple ASCII format. Each logbook is defined by a [<name>] section where <name> is the name of the logbook. The [global] section is used for settings common to all logbooks. Each line contains a setting name, followed by an equal sign and the value for this setting. Lines starting with ";" are treated as comments.

Here is a simple example, which define two logbooks, "Linux" and "PC":


  Global options  

The notation of the following options is such that items enclosed by "<" and ">" should be replaced by a specific string. If a value contains blanks (like a complete sentence), it should not be enclosed in quotation marks.

If a setting has a number of possible options, they are shown in the form option1|option2|..., meaning that one of the options (without any vertical bar) should be used. The following options are specific to the [global] section:


  Groups of logbooks  

If installations have very many logbooks, it can be hard to navigate between them. To make things more structured, it is possible to build a hierarchy of logbooks. A logbook group can contain any number of logbooks as well as other logbook groups. The hierarchy is defined with the the option

Group <group name> = <Logbook1>, <Logbook2>, <other group>

in the [global] section of the configuration file.

To define following logbook hierarchy:

one would use following statements:

The logbook tabs would then look like this:

Where the selected group or logbook becomes blue. The lower groups/logbooks change according to the selected upper group. Please note that a logbook can be contained in more than one group, but then it should not be the first logbook in those groups. The colors of the tabs and the title bar can be specified in the CSS file.


  Individual logbook options  

For each logbook, there is a section with the logbook name in square brackets, so that each logbook can have different options. If an option is not present in a logbook section, then the system tries to locate that option in the [global] section. Thus if the following options are placed in the [global] section, they are defaults for all logbooks. If they are present in the [global] and in the logbook section, the logbook option is used.

Here are the available options, by broad categories:


  General options  

  Attributes  

  Conditional attributes  

When entering data into a elog form, it might be helpful to change the options of the attributes depending on the value of other attributes. Let's assume you have a logbook containing entries for different computers with different operating systems. Your elogd.cfg file starts like that:

Attributes = PC Name, Operating System, Version
Options Operating System = Linux, Windows

For the operating system version, you would like a list, but this list has to be different for Linux and Windows. This can be achieved with conditional attributes. Simply write following configuration:

Attributes = PC Name, Operating System, Version
Options Operating System = Linux{1}, Windows{2}
{1} Options Version = 2.2, 2.4, 2.6
{2} Options Version = ME, 2k, NT, XP

If you enter a new entry into that logbook, the drop-down list for Version changes automatically depending on the Operating System. Note that you have to enable Java Script for this to work. Without Java Script, a separate button appears in the line of the Operating System which has to be pressed to make the Version list change.

The number {1} and {2} in the configuration file are called conditions. Depending on these conditions, certain other lines can be activated. So if the Operating System Linux is selected, condition {1} is true, which selects the line starting with {1} to select the options 2.2, 2.4, 2.6.

This technique offers various other possibilities, since any configuration option can be made conditional by adding a {<n>} in front of that line where <n> is an arbitrary number. One often used possibility is the definition of forms. Depending on an attribute, the configuration option Prset text = ... can be used to copy some pre-defined forms into the message body, which can then be filled out. Consider following example:

Attributes = Author, Type
Options Type = Network check{1}, System check{2}

{1} Preset text = network.txt
{2} Preset text = system.txt

This causes two text files network.txt and system.txt to be copied into the message body when a new entry is made. The file network.txt could look like:

Routers checked:  [ ]
DHCP checked:     [ ]
Comment: ...

This works like a pre-defined form, the user puts X's between the "[ ]" when that item has been checked. Other possibilities are pre-defined shift sheets in environments where elog is uses as a shift logbook. The shift sheet could contain the names of the shift crew, some check-list for standard tasks etc.

Another use of conditional attributes is in conjunction with the option Message comment. Depending on some attribute values, different message comment can be displayed to tell the user what to enter exactly in the message body for that attribute value.


  Access control  

Reading and writing into logbooks can be constrained using two different access methods, either with global passwords for read, write and admin (config, delete), or with user- level passwords. Both methods can be combined on the same server using different logbooks. For these two schemes to work properly, cookies have to be turned on in your browser. Please consult your browser documentation about how to do that.

These optional password statements define passwords for reading and writing to the logbook, to delete entries in the logbook and to configure a logbook via the Config menu. The passwords are stored in an encoded form. To change them, use elogd directly with the -r , -w and -a flags. To set the write password of logbook "linux" to " test", enter:

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 admin passwords are stored in cookies on the browser side and expire after the browser session. This time can be changed with the statement Write Password Expiration = x or Admin Password Expiration = x, where x is the expiration time in hours. It should be noted that on some systems the daylight savings time is calculated incorrectly, which can cause time offsets of one hour between a server PC and a client PC. In this case one hour must be added to the expiration time. If the expiration is set to "0", which is the default, the passwords are kept for the current browser session only. When the browser is restarted, the password must be re-entered.

An alternative to the read/write/admin passwords is the user level access with a password file. This file contains user names and passwords in following format:

The passwords are encoded. New users can either be created by hitting Register as new user on the login page if Self register = 1 in the configuration file, or by the admin user in the Config page by pressing New user. When a user is logged it, the entry for this user can be modified via the Config command.

To start a new password file, follow these steps:

The presence of a password file requires all users to "log in" using their name and password, except when a guest login is allowed via the "Guest menu commands" option. An additional advantage of this method is that the user name can be used as an attribute value for creating logbook entries. For example, the following line could be added to the configuration file to fill in the Author and the Email attributes with the current user name and email:

Thus the author name is not user-input anymore, ensuring the entry always contains the actual user name. For a full listing of substitutions, see the "Subst <attrib>" option.

The user name and password are stored as cookies on the user side. The expiration is controlled by the Remember me checkbox during the login. If unchecked, the cookies expire after the current browser session. If checked, they expire after 31 days by default, which can be changed with the Login expiration option, giving the expiration time in hours. Setting this to 24 for example, makes the password expire after one day. If presistent cookies are not desired, the Login expiration option can be set to zero, in which case the Remember me checkbox is not displayed.

The Admin user = <user list> is a list of one or more user names, which have admin rights. They see a button Change elogd.cfg on the config page by which they can edit elogd.cfg through the web. They can also modify other users on the Config page, change their passwords or remove them. In addition, the admin user(s) can delete or edit entries from other users if Restrict edit = 1.

The Login user = <user list> is a list of users who can log in to a specific logbook. This option can be used with a global password file. If a Password file is present under the [global] section, the registered users in that password file can log in to all logbooks. It might be required that only certain users can log in to certain logbooks. This can be achieved with the Login user option, places in each individual logbook section in the configuration file. Only those users listed in this statement can log in to the logbook where the statement is defined. This method has the advantage over the option of definining individual password files for individual logbooks that only one central password file exists. So if a user changes her/his password, this becomes then valid for all logbooks. If there would be individual logbook password files, one would have to change the password in all logbooks individually.

With this option it is possible for new users to self-register an user account. At the login page, a link is displayed "Register as a new user" which leads the user to a configuration page where one can enter the account name, full name and email address. A flag allows for automatic email notification on new entries on the logbook. These settings can later be changed with the Config menu command.

Setting this option to 0 disables self registration. With option 1, users can silently register, while setting it to 2 causes elogd to send an email notification to the admin user(s). The option 3 is used to only send an email notification to tha admin users(s), which then can validate the account and commit it by hitting the URL given in the email notification.

Commands can be restricted to certain login names (separated by commas). For each command in the list defined with the "Menu commands" option, a list of user names can be specified, which are allowed to execute that command. If the allow option is not present, all users may execute that command by default.

Used to deny a certain command to a list of users. This can be used to deny a guest user to enter new messages or modify a message.

These two settings can be used to restrict the access to the logbook to certain computers. It is similar to the UNIX hosts.allow and hosts.deny files. The list can consist of individual host names or IP numbers, subnet masks like 123.213. (note the trailing '.') or .mit.edu, or the word All. The following rules are applied:

These rules are applied before any password is checked. To debug problems, start elogd with the "-v" flag, in which case the rule checking is printed on the screen.

The global option Logfile = <filename> can be specified to log all user login/logout activities plus all successful user connections.

If any of the password statements are in the [global] area of the configuration files, they are used for all logbooks. If one logs in at one logbook, access is automaticlly granted to all logbooks. If the password statements are in the individual logbook sections, one has to log in to each logbook separately.


  EMail notification  

To send email automatically when new entries are created in a logbook, a SMTP host = entry must be present in the [global] section of the configuration file. To submit an email based on an attribute value, use the statement Email <attribute> <value> = <list>. Whenever an entry is submitted where attribute is equal to value, an email notification is sent to the email addresses in list. Several mail addresses may be supplied, separated by commas. The mail addresses can contain attributes via the "$" substitution. If a logbook contains for example an attribute name which contains email names, then one can put $name@domain to form a valid email address.

Multiple Email xxx statements may occur in a configuration file. If either the attribute or the value contains one or more blanks the string must be enclosed with quotation marks, as in:

The statement Email All = <list> sends an email notification independent of the type and category. The Use Email Subject = <string> statement specifies which text is used as the email subject. The text can contain $<attribute> statements which are substituted with the current value of that attribute. For a full list of possible substitutions, see the "Subst <attribute>" option. The Use Email Heading = <string> specifies the text for the email heading line. Default is "A new entry has been submitted/updated on [host]".

The option Use Email From = <string> is used for the "From:" field in the email. Please note that more and more email servers do not accept invalid "From:" addresses, in order to reduce spam mail. So it might be necessary to use this option to supply a "real" email address.

If the flag Omit Email To is set to 1, the To: field in the email is left empty instead set to the real email address of the recipients. This can be useful if one recipient should not see the email addresses of the other recipients.

The flag Suppress Email to users can be set to "1" if email should only be sent to the recipients of the Email <attribute> <value> = <list> statements but not to the users who have registerd for automatic email notification.


  Flags  


  Themes  

Themes are layout and color schemes which determine the look and feel of a logbook (sometimes called "skins"). A theme consists of a set of images, which are used for the title banner and browse buttons, and a Cascading Style Scheet (CSS), which defines the colors, fonts and spacing of the ELOG pages.

Each theme resides in a separate subdirectory and is specified with the theme = <dir> option in the configuration file. Each theme can contain several CSSs, which can be selected with the CSS = <filename> option.

A default theme is contained in the distribution. If new themes are developed by users, they can be sent back to the author, to be included in future releases.

To change colors and fonts, the source of a ELOG page can be examined. All elements use CSS classes which are specified in the class="<name>" statements. These classes can be found in the .../themes/default/default.css file and changed accordingly. For a description of all options, please consult for example the W3C consortium.

If the CSS file is edited, most browsers require a "reload" to refresh the modified file. The elogd daemon does not have to be restarted after a change in the DSS file.

These two images display the same logbook entry using different themes: