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:

    [global]
    Group Linux PCs = Red Hat, Debian, Mandrake
    Group Windows PCs = 98, ME, NT, XP, CE
    Group CE = 1.0, 2.0
    
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 theme 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  
  • Attributes = <list>
    Define a number of attributes for the logbook. A maximum of 20 attributes can be defined. Typical values are "Author", "Subject" or "Type".

  • Options <attribute> = <list>
    Usually, an text field is used for an attribute, where the user can fill in text of up to 100 characters. If instead a drop-down box with preset items is better for a given attribute, these items can be defined with this statement. Up to 100 items can be defined, separated by commas. To add an option including a comma, encose it in quotations marks like

    Options town = San Francisco, "Paris, Texas", "Paris, France"
    

  • ROptions <attribute> = <list>
    Same as Options above, but using radio buttons instead of a drop-down box.

  • MOptions <attribute> = <list>
    This list allows for "Multiple Options", meaning that an attribute can have several values simultaneously. When entering an entry with MOptions, each value from the list is represented by a checkbox. Unlike with normal options, multiple checkboxes can be checked for an entry. The attribue value then becomes

    <value1> | <value2> | ...
    
    In the "find" page only one of these values can be specified, which is then treated as a substring in the search filter.

  • IOptions <attribute> = <list>
    This list specifies a set of icons for an attribute. Some icons are contained in the themes/default/icons directory which can be used here like

    Attributes = Author, Icon, Subject...
    IOptions Icon = icon1.gif, icon2.gif, icon3.gif, ...
    
    New icons are welcome and should be sent back to the author to be incorporated in the next version.

  • Options <attribute> = boolean
    If an attribute is marked "boolean" this way, a checkbox is displayed for this attribute.

  • Preset <attribute> = <string>
    This option uses a preset string for an attribute. The string can contain subsitutions like the ones described under the "Subst <attribute>" command. One possible application is to use the login name for the author field like:

    Preset Author = $long_name
    
    If the attribute should be locked at the Web submission, use the "Locked Attributes = ..." option. If a preset value is given for an attribute which has an options list, the preset value is selected in the drop down box by default.

  • Preset text = <string> or <file>
    This preset value is used for the main body text. It can be a string or a file, which must be present in the resource directory. Alternatively, an absolute path can be used if the file name starts with a "/" (Unix) or "\" or "x:" (Windows).

  • Locked Attributes = <list>
    The attributes specified here cannot be modified when a new entry is submitted. This makes only sense for preset attributes.

  • Fixed Attributes Edit = <list>
    The attributes specified here cannot be modified when an existing entry is modified via the Edit button. This feature can be useful to preserve the original author of the message, when using the Preset Author = $long_name option as described above.

  • Fixed Attributes Reply = <list>
    The attributes specified here cannot be modified when an existing entry is replied on via the Reply button. This feature can be useful to preserve the original subject of a message for example.

  • Required Attributes = <list>
    The attributes specified here are required when a new entry is submitted. The attribute names are marked with * on the entry form.

  • Page title = <string>
    The string specified here is used for the title of the web page. It is also used by most browsers for bookmark names. The string can contain substitutions as described unter the "Subst <attribute>" option.

  • Display search = <list>
    Specified the display and order of items in a search result page. In addition to all attributes, one can specify here "#" for the message ID, "Logbook" and "Date". The restriction to certain attributes can be helpful if many attributes are defined in a logbook, which usually makes the table too big to fit in the browser. The default is
    Display search = #, Date, <all attributs>
    
    Which displays the message number, date, and all attributes. The display of the message body is controlled by the Display mode and Summary lines options.

  • Thread display = <string>
    Optional way to specify the line contents in the threaded search result. Following substitutions are possible:

    • $<attribute>: The value of the attribute
    • $logbook: The name of the current logbook
    • $entry date: The message date, formatted via "Date format"
    • $message id: The message ID

    A typical example would be
    Thread display = $subject, posted by $author on $entry date

  • Thread icon = <attribute>
    If a logbook uses some icons for an attribute, these icons can be displayed in the search result page instead of the default icons defined in the themes.cfg file.

  • Subst <attribute> = <string>
    When submitting logbook entries, attribute values can be substituted by some text. This text can contain arbitrary fixed text and following values:

    • $<attribute>: The entered value of the attribute itself
    • $host: The host name where elogd is running
    • $remote_host: The host name of the host from with the entry was submitted
    • $short_name: The login name (if password file is present)
    • $long_name: The full name from the password file for the current user
    • $user_email: The email address from the password file for the current user
    • $logbook: The name of the current logbook
    • $date: The current date, formatted via "Date format"

    Following example use this feature to add the remote host name to the author:
    Subst Author = $author from $remote_host

  • Remove on reply = <list>
    This option clears one or more (separated by commata) attribute values from a logbook entry when creating a reply to that entry. This can make sense for example for the author, since the author of a reply can be different from the original author.

  • Subst on reply <attribute > = <string>
    Substitution of attributes for replies. This option can be used to replace the current subject with a "Re: <old subject>":
    Subst on reply subject = Re: $subject

  • Quick filter = <list>
    Specifies list of comma separated attributes for which a drop-down filter is displayed in the search result page. By selecting a value from that drop-down box, only entries with that value are displayed. In addition to all attributes defined in the Attributes = list, the attribute Date can be listed here to display a date filter. Using that filter, the last day, week, month and so on can be displayed.


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

  • Read password = <encoded password>
  • Write password = <encoded password>
  • Admin password = <encoded password>
  • Write password expiration = <hours>
  • Admin password expiration = <hours>

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:

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

  • Password file = <file>
  • Login expiration = <hours>
  • Admin user = <user list>

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:

    <login name1>:<password1>:<full name1>:<email1><notify1>
    <login name2>:<password2>:<full name2>:<email2><notify2>
    <login name3>:<password3>:<full name3>:<email3><notify3>
    ...

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:

  • Set Self register = 1 in the configuration file
  • Connect to the logbook. You will be presented the login page. If you have a Guest menu commands entry, you have to click on "Login" to get that screen.
  • Click on "Register as new user"
  • Enter your login information and save it
  • Add Admin user = <user> into the configuration file, using your login name from above
  • If you now enter the "Config" page, you can add other users
  • Remove the self registration option if you like
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:

    Attributes = Author, Email, ...
    Options Author = $long_name from $remote_host
    Options Email = $user_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. They expire after the current browser session 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.

The Admin user = <user list> is a list of one or more user names, which have admin rights. The can execute the Admin command to directly edit elogd.cfg through the web and modify other users via the Config command.

  • Self register = 0|1|2|3
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.

  • Allow <command> = <user list>

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.

  • Deny <command> = <user list>

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.

  • Hosts allow = <list>
  • Hosts deny = <list>

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:

  • Access will be granted when a host matches a pattern in "hosts allow".
  • Otherwise, access will be denied when a host matches a pattern in "hosts deny".
  • Otherwise, access will be granted.

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  
  • Email <attribute> <value> = <list>
  • Use Email Subject = <string>
  • Use Email From = <string>
  • Omit Email To = 0|1
  • Suppress Email to users = 0|1

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:

    Email type "Normal routine" = ...

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 option Use Email From = <string> is used for the "from" field in the email. 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  
  • Show text = 0|1
    This flag controls if logbook entries contain a body text. If an installation only requires attributes, this flag can be set to 0. Default is 1.

  • Show attachments = 0|1
    This flag controls the display of attachments such as images on normal logbook pages. For logbooks with large images, this flag can be turned off, so that attachments are only displayed when they are clicked on. Default is 1.

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

  • Reverse sort = 0|1
    If this flag is 1, all listing pages (the default page view, the result of a search query and the result of the "Last day" and "Last 10" queries) is sorted in reverse order (newest entry down to oldest). The checkbox Sort in reverse order on the search form gets checked by default, too. Sorting in reverse order can make sense if there are many pages of entries, but the ones entered last should be displayed on the first page. Default is 0.

  • Search all logbooks = 0|1
    If this flag is 1, the search form displays the button "Search all logbooks". The default is 1. It might be necessary to turn this option off for public logbooks if there are also protected logbooks. Otherwise the search result would also display entries from the protected logbooks.

  • Enable browsing = 0|1
    If this flag is 1, browsing (hitting the next/previous button) is enabled. For some rare occasions it might be necessary to disable browsing. Default is 1.

  • Filtered browsing = 0|1
    If this flag is 1, browsing (hitting the next/previous button) can be filtered by individual attributes. If the checkbox next to an attribute is checked, only messages with the same attribute value are displayed. Default is 1.

  • HTML default = 0|1|2|3
    This specifies the default state of the "Submit as HTML text" button on the new message entry from. For installations where entries are normally submitted as HTML, the default can be set to 1. If this value is set to 2 or 3, the check box is not displayed and only text submissions ore HTML submissions are possible, respectively. The default is 0.

  • Suppress default = 0|1|2
    This specifies the default state of the "Suppress Email notification" button on the new message entry form. For installations where normally an email notification is not necessary, the default can be set to 1. If an important entry is entered, users can then uncheck the suppress box. If this value is set to 2 , the suppress box is not displayed at all, so that an email notification is always produced. The default is 0.

  • Resubmit default = 0|1|2
    This specifies the default state of the "Resubmit as new entry" button on the edit message entry from. If this button is checked, the current message is removed from its current position in the database and submitted as a new message. This can for example be useful for applications where users want to see which records have been updated recently. If this value is set to 2, the resubmit box is not displayed at all. The default is 0.

  • Display Email recipients = 0|1
    If this flag is 1, the email recipients are displayed when a logbook entry is entered which produces an email notification. Setting this flag to 0 suppresses this display, in case users need not see that email is being sent and to whom. The default is 1.

  • Email message body = 0|1
    If this flag is 1, the email notification send by elog contains the full message body in addition to the attributes. The default is 0.

  • Suppress Email on edit = 0|1
    If this flag is 1, no email notifications are sent for edited messages, only for new messages. The default is 0.

  • Back to main = 0|1
    If this flag is 1, the "Back" button takes you back to the logbook selection page instead to the last entry of the current logbook. The default is 0.

  • Logout to main = 0|1
    If this flag is 1, the "Logout" operation takes you back to the logbook selection page instead to the login page. The default is 0.

  • Restrict edit = 0|1
    If this flag is 1, users can only edit their own messages. The system checks automatically if the currently logged in user matches the user supplied in an author attribute via the "Preset xxxx" option. The default is 0.

  • Expand default = 0|1|2|3
    This setting determines how messages are displayed in threaded mode. Following options are possible:
    • 0: Only message heads are displayed, no replies. A "+" indicates which message has one or more replies.
    • 1: Messages and replies are displayed, but no message body.
    • 2: Messages and replies are displayed together with the first few lines of the message body. The number of lines is controlled by the Summary lines option.
    • 3: Messages and replies are displayed together with the full message body.
    The default is 1.

  • Line as link = 0|1
    If this flag is 1, the full line is used as a link to each message in the search result page. Otherwise, only the icon at the beginning of each line is used as the link, which can be hard to hit for small icons. The default is 0.

  • Table align = left|center|right
    Determines the text alignment inside the table of a search result for summary or full mode. For threaded display, text is always aligned left. Default is center.


  Themes  

Themes are layout and color schemes which determine the look and feel of a logbook. Each theme resides in a separate subdirectory and is specified with the theme = <dir> option in the configuration file. The directory contains the file theme.cfg and a few images, which are used for the title banner and the browse buttons. 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.

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.

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