ELOG - Syntax of elogd.cfg

[back to Administrator's Guide]

* Server : [Global] - Logbooks : [General] [Logbook groups] [Attributes] [Conditional Attributes] [E-mail] [Access Control] [Flags] [Themes] [Mirroring] *

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.

Top groups

Sometimes groups of logbooks should be completely separate. Imagine two groups of logbooks, one for the engineering department and one for the administration department. These groups should have different administrators, and the logbook tabs at the top of the screen should not show the logbooks from the other department. Prior to ELOG version 2.4.1, one had to run two elogd servers in parallel, listening under different ports. Since 2.4.1, one can achieve the same behaviour using Top groups. The configuration could look like this:

Note that there can be a [global] section for each top level group of logbooks. The rule is that a configuration setting in an individual logbook section overrides a setting in the [global <top group>] setting, which by itsel overrides a setting in the [global] section. This way one can define settings for all top level groups (such as the SMTP host) in the [global] section, and define different password files and administrators in the individual top level group sections.

If top groups are used, the root of the elogd server is not accessible any more. Presume that elogd is accessible normally under http://your.host:8080/, this URL becomes invalid for top groups, to avoid the case that one group can "see" the logbooks of the other groups. Instead, one has to append the top group name to the URL, such as http://your.host:8080/engineering or http://your.host:8080/administration. If someone does not know the top group name, one cannot see the list of logbooks there, so the groups become completely independent of each other. If this feature is not wanted, it can be disabled by setting Show top groups = 1.
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:

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:

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 Preset text = ... can be used to copy some pre-defined forms into the message body, which can then be filled out. Consider following example:

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:

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 comments can be displayed to tell the user what to enter exactly in the message body for that attribute value.

Show Attributes Edit = <list>
When using conditional attributes, it might be necessary to omit certain attributes under certain conditions, to make the input mask shorter and maybe change the order of the attributes. With this option, a subset of all attributes can be specified which get displayed on the single entry page in the same order as they are specified here. This option mainly makes sense when used with conditions, such as:

The above statements cause the atrribute Version to be only visible when "Windows" is selected, and Distribution to be only visible when "Linux" is selected. If "Windows" is selected, the PC name is shown before the version.

Multiple conditions

It is possible to define conditions in more than one options list. The only requiremnt is that conditions are uniquie, meaning that a condition in one option list cannot be used in another list. This can easily be avoided by using numbers for one condition and letters for the other condition, like in the following example:

It is possible to specify an OR of several conditions like in the case {b,c}. This is also possible over several conditions, like {1,a} would mean "The PC has Linux or is in the Main Building". To specify a AND between conditions, a "&" is used. The condition

specifies for example the condition "Linux AND Main Building". If several lines with condition combinations are true, the upper one is used.

Conditions in the list display

Conditional attributes are usually only used for change items in the entry form. It might however be desirable to have conditional attibutes also working in the list display (the page where several entries are shown on a single page). The value of one attribute can then for example change which other attributes gets displayed via the list display option. To enable the evaluation of conditional attributes for the list display, on uses the option

It should be noted that this option can cause a significant performance degradation if many conditional attributes are defines, so it should only be turned on when it is really needed.

Access control

Note: Starting with version 2.9.0, the password level access using the options Read password, Write password and Admin password is not supported any more. Please use the user level access as described below.

Password file

Access control is done on a user level with a password file. When a user logs in, a session ID is created and placed as a "cookie" in the browser. Using this cookie, the user can workin on the logbook until the cookie expires. For this it is necessary that cookies are enabled in the browser.

Following options can be used to control the behavior:

This file contains user names and passwords in XML format, such as

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. The password file resides in the same directory as the logbooks. 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 the admin users(s), which then can validate the account and commit it by hitting the URL given in the email notification. Setting this to 4 causes and email notification to be sent to the user, which then can validate the account herself/himself proving to have a working email account.

Enables or disabled the ability for users to change their password. If disabled, the "Forgot password? link in the login page is ommitted as well. The admin user(s) can always change passwords.

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.

Kerberos authentication

Starting from version 2.9.0, site authentication has been implemented in elog using the Kerberos authentication scheme. This widely used system is also used in MS Windows Domain Controllers, and can be used for site logins, meaning that the same credentials can be used on all computers of a site.

To use that authetication, Kerberos has to be installed on the server running the elogd daemon. Please read the Kerberos documentation how to do this or talk to your site administrator. There are packages for Linux, Windows and Mac OSX. If you compile the elogd program yourself, make sure to have the flag HAVE_KRB5> defined in the compilation process. To configure elogd to use Kerberos, use following options:

where <method(s)> can be File or Kerberos or both such as in Kerberos, File. If the authentication option contains Kerberos, the user credentials are authenticated using the default Kerberos Realm. This is typically obtained from the file c:\windows\krb5.ini (Windows) or /etc/krb5.conf (Linux). If another than the default realm should be used, this can be overwritten with the Kerberos Realm option.

When Kerberos authentication is used, the password file is still used to store additional user information such as the full name and the email address, but the authentication is done via the Kerberos server.

If both authentications Kerberos, File are enabled, the credentials are first authenticated via the Kerberos server, and - if not successful - via the password file. This allows combined elog installations with centralized and local elog accounts. If the Kerberos authentication was successful, the password in the password file is overwritten with the encrypted Kerberos password. This allows the system to work even if the Kerberos server is temporarily not accessible.

If the password is changed via the "Change Password" button on the config page, the system tries to change the password in the Kerberos database. On some installation it has been found that this does not work, in which case you have to change your password by other means (such as via the Windows login if you use a Windows Domain).

Beside the Kerberos authentication, elogd version 3.0 and higher can be configured to accept a authentication done by the webserver.

You can also combine it with other authentication methods as shown for Kerberos.

Elogd is then accepting the username set in the Request-Header "X-Forwarded-User" as already logged in.
To make this work, you need to configure the webserver correctly, as describe in the adminguide.

LDAP authentication

LDAP (lightweight Directory Access Protocol) has been implemented by vykozlov in a separate branch at https://github.com/vykozlov/elog-ldap. The code has been merged into this distribution on an as-is basis. Following info has copied from the link above:

To use LDAP authentication, do the following:

Please note that it is not possible to change a password in the LDAP database from within ELOG.

PAM authentication

PAM (Pluggable authentication modules) support has been implemented by Jan Christoph Terasa as a separate branch at https://bitbucket.org/ritt/elog/branch/pam.

To use PAM in elogd, do the following:

Please note that it is not possible to change the PAM password within ELOG. Instead, please use the available methods on the system

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 on [host]". The option Use Email Heading Edit = <string> works the same way for updated (edited) entries.

The option Use Email From = <string> is used for the "From:" field in the email. Since more and more email servers do not accept invalid "From:" addresses in order to reduce spam mail, it might be important that a "real" email address is used in the "From:" field. If Use Email From is present, it is always used. If not, the email address of the currently logged in user is used for the "From:" field. If no user is logged in, or the current user has not specified a email address in the password database, the setting of the option Default Email From is used for the "From:" field. Only if this option is not specified, a generic address ELOG@<hostname> is used, which might be rejected by the SMTP server however.

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.

If one wants to send only some attributes but not all in an email notification, one can use the option Email attributes = <list>, where a subset of the attributes can be specified as well as their order.

The option Use Email URL = <URL> can be used to set the URL of the ELOG logbook used in email notifications. This can be useful if no URL = ... statement is used form some reason.

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 CSS file.

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

Mirroring

Sometimes it can be useful to have the same ELOG logbook on two different computers. This might be the case if you travel with your laptop, but want to keep the logbooks from your desktop computer on the laptop. The problem is that if you add an entry on your laptop, the logbooks on the laptop and the desktop get out of sync. Merging only the ELOG database files does not help, since two entries could be made at the same day on the laptop and the desktop, which would lead to a conflict in that day's database file.

To solve this problem, mirroring was introduced from Version 2.5.0 on. This technology allows to synchronize one ELOG server with a number of other servers on a per-entry basis. No additional software is needed, only two elogd daemons talking to each other. The synchronization can be executed manually or periodically. If entries are changed/added/deleted on both sides, they get merged properly during synchronization. In order to minimize network traffic, each ELOG server calculates a MD5 checksum for each message, which gets exchanged during synchronization. Only when the MD5 checksum differs, entries are transferred.

To set-up mirroring, install two elogd servers on two machines (for testing purpose that also works on one machine with two elogd servers running on different ports). This can be done in two ways:

  1. Automatic configuration

    A complete elog server can be transferred to a secondary server using the clone command. Assume the existing server resides at http://master.your.domain/, and you want to mirror this server to a new location at http://slave.your.domain/. You do that by installing the elog package at the slave machine, and then executing on the slave: 

    elogd -C http://master.your.domain
    or 
    elogd -C https://master.your.domain
    for a remote server running under the SSL protocol. Note that you have to put "Allow clone = 1" temporarily into the elogd.cfg file of your existing server to allow cloning. This opens a password-free access to your existing server, so remove it immediately after you finished cloning.

    This command tells elogd to retrieve the configuration file, and optionally all logbook entries and password files from the master machine. Note that both servers must be version 2.5.4 or later. In case of trouble, you can turn on verbose messaging: 

    elogd -v -C http://master.your.domain

    which could give some hints. If a logbook on the master server uses restricted access, you have to specify the admin user name and password. After everything has been transferred, you can start elogd in the normal way.

  2. Manual configuration

    First, copy the elogd.cfg file from the master to the slave server. Make sure that the files are identical (except the port setting if you run two servers on the same machine). Then, add the following configuration options. They should be put into the [global] section of the cofiguration file:

If the statement Mirror server is present in the configuration file, a new menu option "Synchronize" appears on the elog page. Clicking on this menu options starts the synchronization:



On the left side one sees the entry ID's. Entries which are equal locally and remotely are not displayed. Here are the rules for synchronization:

By starting the synchronization on one elogd server, this server becomes the client and the other one becomes the server. This means that the local server actively compares the local and the remote messages, and updates one or the other if necessary. The other (remote) server does not need to have any mirror option in its configuration file, since the local server simulates a web browser to send and retrieve messages to the remote server. It is however allowed that the remote server also contains some mirror settings in the configuration file, this way the synchronization can be started from both servers.

Content by Stefan Ritt, Web pages by Fred Pacquier