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 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]
SMTP host = mailsend.your.domain

[Linux]
Theme = default
Comment = General linux tips and tricks
Attributes = Author, Type, Category, Subject
Options Type = Routine, Software Installation, Problem Fixed, Configuration, Other
Options Category = General, Hardware, Software, Network, Account, Other
Options Author = Stefan, Linus, unknown
Required Attributes = Author

[PC]
Comment = Database PC installations
Attributes = Location, OS, Owner
Options Location = Building1, Building2
Options OS = Linux, Windows ME, Windows 2000
Required Attributes = Location, Owner
Email All = name@address, othername@otheraddress
Use Mail Subject = Location

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:

Port = <port>

Specifies the TCP port under which the server is listening. Default is 80. Can be superseeded via the '-p' command line flag.

SSL = <0 | 1>

Turn on Secure Socket Layer transport. If SSL is on, one can connect via https://... to the elogd daemon. If the URL = directive is used, make sure to use https://... instead of http://... there. The ELOG distribution contains a simple self-signed certificate in the ssl subdirectory. One can replace this certificate and key with a real ceritficate to avoid browser pop-up windows warning about the self-signed certificate. The default for this option is 0.

Interface = <interface>

Specified network interface to listen at. Can be used if several network cards are in a computer, or if one wants to restrict access to the local host only, in which case one can use 127.0.0.1 as the interface.

Resource dir = <directory>

Specifies the root directory for ELOG resources like help files, themes and icons. Can be overwritten with the -s flag when starting elogd. If not specified, use the directory where the configuration file elogd.cfg resides. Changing this option requires a restart of the elogd server.

Logbook dir = <directory>

Specifies the root directory for logbooks. Can be overwritten with the -d flag when starting elogd. If not specified, use the directory where the configuration file elogd.cfg resides. Each logbook data is stored in a separate directory under this root directory specified by the Subdir option. Changing this option requires a restart of the elogd server. This directory also contains any password file and user HTML file.

Language = <name>

The language setting determines the language of the elogd output. Not affected by this setting are the configuration file options and the commands specified with the optional Menu commands and List menu commands, which have to be specified in English and are translated automatically by elogd. The attribute names are unaffected by the language setting and have to be translated manually.

If a language name is given (currently "german", "french", "spanish", "dutch", "brazilian" are supported out-of-the-box), the system searches for a file named eloglang.<name> containing string translations from English into that language. If you create a new translation file, please send it back to the author to be included in future distributions.\ \ The online help for elogd is contained in the file eloghelp_xx.html where xx are the first two letters of the language (like "en", "ge" and "fr"). For new languages, a new file of that type must be created as well.

charset = <name>

Specifies the charset of the pages produced by elogd. Can be used to switch to Russian or Asian fonts.

Logbook Tabs = [0|1]

This flag controls the display of "tabs" on top of the logbook page which allow to quickly switch between logbooks. Default is 1

Main Tab = <string>

If this option is present, an additional first tab is displayed which takes you back to the main logbook selection page. The string is used for the contents of the tab.

Main Tab URL = <string>

Normally the main tab brings one back to the logbook selection page. In case one wants to specify a different destination, such as a special web page outside of elog, one can use this statement to specify a full URL.

Welcome Title = <html code>

This optional HTML code gets displayed in the title of the logbook selection page. It can contain images via <img src="welcome.gif">. These images must be stored in the resource directory or in the theme directory.

The following line is an example Welcome Title:

Welcome title = <img src="welcome.jpg"><p><font size=5 color=white>Welcome to our Elog</font>

This displays an image and a text below.

Page title = <string>

The string specified here is used for the title of individual logbook pages. It is also used by most browsers for bookmark names. <string> can contain substitutions like \$<attribute> where <attribute> gets replaced by the attribute string from each message. The option Page title in the [global] section is used for the logbook selection page.

List page title = <string>

The same for the summary or find result page. This may include substitutions as well, although attribute substitutions make no sense here, since the summary page may contain many messages with different attributes.

Selection page = <file>

When this option is present, a user defined file is displayed instead of the logbook selection page. This file must be stored in the resource directory. Alternatively, an absolute path can be used if the file name starts with a "/" (Unix) or "" or "x:" (Windows). It can be completely customized in order to contain logos etc. As a template, the standard selection page produced by elogd can be used.

Guest Selection page = <file>

The same for installations which have a global password file. This means that the logbook selection page is also password protected. It might be however that some logbooks have guest access, in which case guest access to the selection page should be allowed as well (maybe with only a subset of the available logbooks). In that case this options can be used, to show a list of logbooks with guest access.

Protect Selection page = 0 | 1

Normally, one can see the logbook selection page without having to log in. If one wants to require a login for the selection page, this switch can be set to 1. Default is 0. It is necessary to put the Password file = ... into the [global] section of the config file for this to work.

Expand Selection page = 0 | 1'

If this option is not present or set to one, the logbook selection page is expanded (all logbooks are shown if groups of logbooks are present). If this option is zero, only the group names are displayed. If one clicks on a group, its logbooks are shown. Using this option set to zero only makes sense if one has a large number of logbooks which would not fit on a single browser window, so collapsing makes sense. Default is 1.

SMTP host = <host.domain>

This defines the SMTP host needed to send automatic email notifications. The host name you can get from your email program or your local system administrator.

SMTP username = <username>

Some SMTP server require username/passowrd authentication. This option specifies the SMTP user name, while the option SMTP password can be created or modified via the -t switch when starting elogd. This is necessary since the password is encrypted. To set your SMPT password, enter on the command line:

elogd -t <your password>

SMTP port = <port>

This defines the port under which the SMTP server is listening. The default is 25, but some newer servers use port 587.

Logfile = <file>

This option specifies a filename which logs all login/logout activities and successful user connections for logbooks with user level access. The the logging level (see below) is larger than 1, also read and write accesses can be logged.

Logging level = 1 | 2 | 3

Specifies the logging level. The higher this value, the more information is logged. Default is 2:

• 1: Log only logins and logouts
• 2: Log also write accesses
• 3: Log also read accesses

URL = <http[s]://host.domain[:port]/[subdir/]>

If one of the three cases is true:

• elogd runs with SSL enabled
• elogd runs under a proxy
• The automatic email notifications contains the wrong URL

then the URL under which elogd is running has to be specified manually with this statement. The URL has to contain the port number if not the standard port 80 is used or 433 for SSL, and it has to contain the directory if used under a proxy like

URL	Condition
URL = http://host.domain:8080/	if running on port 8080
URL = https://host.domain/	if SSL is enabled (SSL = 1)
URL = http://host.domain/subdir/	if running under a proxy

This URL is then used for any redirection. For example if one submits a new entry, the URL in the browser reads ...<logbook>/?cmd=Submit&..., containing all the attributes etc. After the submit this page gets redirected to ...<logbook>/<ID>, where <ID> is the ID of the new entry. For the redirection via the HTTP "Location:" statement, an absolute URL is required. Since elogd cannot figure out the complete URL under which it is running when accessed through an Apache proxy, this statement is necessary to tell elogd the complete URL.

Relative redirection = 0|1

Under some circumstances, absolute redirection via a complete URL may not work. If you access elogd through two different ways simulataneously, for example directly and via a stunnel connection, a single absolute URL cannot be used, because one connection starts with http://, and the other with https://. Another case is when the elogd server has a dynamic IP address, which changes from time to time. Setting Relative redirection = 1, relative redirection is used. This uses the current URL from the browser, whatever it is, and only specifies the last part of the URL. It should noted however that relative redirections are not allowed in the HTTP standard, but most browsers support it anyhow. Problems have been reported with the Safari browser. So this option should only be used when it is really needed.

Usr = <name>
Grp = <name>

The user and group to run the elogd daemon under when started by root.

Resolve host names = 0|1

Resolve remote host names if set to 1. If set to 0, which is the default, only IP numbers are stored in any log file. If the hosts allow/deny options are used with host names, this setting must be set to 1. If turned on, the DNS server is contacted on each HTTP request to elog, which can slow down the server considerably for slow DNS servers.

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

Group Linux PCs = Red Hat, Debian, Mandrake
Group Windows PCs = 98, ME, NT, XP, CE
Group CE = 1.0, 2.UL

Top group engineering = Linux PCs, Windows PCs
Top group administration = Employees, Purchases

[global engineering]
Password file = engineers.pwd
Admin user = stefan

[global administration]
Password file = admin.pwd
Admin user = bill

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

Data dir = <directory>

This option is obsolete from version 2.2.5 on and should not be used. Use Subdir = ... instead.

Subdir = <directory>

Each logbook has a separate directory where the logbook entries are stored, which is controlled by this statement. If the directory does not exist, it is created autmatically by the elogd program. The subdirectory is relative to the logbook root directory specified with the Logbook dir = ... option. So if Logbook dir = /usr/local/elog/logbooks and Subdir = Demo then the logbook data is stored in /user/local/elog/logbooks/Demo. If the Logbook dir = ... option is not specified, then logbooks is used. If the subdirectory starts with a "/" ("\" under Windows), then it is used as an absolute path independent of the logbook dir. To see which directories are used, start elogd with the "-v" flag.

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

Theme = <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 "themes" directory which resides in the resource directory. It contains all files for that theme. The format of these files is described under the Themes section.

CSS = <filename>

A given theme can contain several Cascading Style Sheets (CSS). This can be usefule if several logbooks use the same images and icons, but differnt colors. By default, the CSS elog.css is used. This statement adds an additional CSS, which can overwrite settings from elog.css. If different CSS'es should be used for different output media, this can be accomplished with a comma- separated list in the form CSS = <file1>&<media1>,<file2>&<media2>. This will then be translated into separate style sheet statements for the different media. For example a statement CSS = default.css&screen,print.css&print will result in the HTML statements:

        <link rel="stylesheet" type="text/css" href="default.css" media="screen">
        <link rel="stylesheet" type="text/css" href="print.css" media="print">

Title image = <string>

HTML code for the icon in the upper right corner. By default, following code is used:

<img border=0 src="elog.gif" alt="ELOG logo">

This code can be replaced by <string> to display a different icon file, or to display some text. The icon image has to be present in the theme directory, which is usually <elog root>/themes/default.

Title image URL = <URL>

The ELOG icon at the right upper corner usually points to the ELOG home page. This URL can be changed to point to a corporate page for example with this option. The icon can be changed by replacing the elog.gif icon in the theme directory. This option should only be used if the Title image option is not used.

Time format = <string>

This option determines how the date and time of a logbook entry is displayed. The format of the string is the same as the C function strftime, so a string of %A, %B %d, %Y, %H:%M yields in a display of Thursday, November 15, 2001, 12:35 for example.

Time format <attribute> = <string>

Same, but just for an individual attribute.

Date format = <string>

This option determines how the date is displayed from attributes which are of type "date". The format of the string is the same as the C function strftime, so a string of %A, %B %d, %Y yields in a display of Thursday, November 15, 2001 for example.

Date format <attribute> = <string>

Same, but just for an individual attribute.

Welcome Page = <file>

By default, the list with the last twenty entries of a logbook is displayed when the logbook is selected. This can be overridden with this option, which causes a HTML file to be shown instead of the message list. This file can contain further links for new logbook messages of for logbook queries. Here is a simple example of such a file:

<h1>Welcome to the test logbook</h1>
<ul>
  <li><a href="?cmd=new">Enter</a> a new message
  `<li><a href="?cmd=find">Search</a> the logbook
</ul>

The file 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).

Start page = <command>

This option can be used to display a different start page. command can be either 0?cmd=Last to display the last message, or any other ELog menu command in the form ?cmd=xxx. To start with the search page, one uses

Start page = ?cmd=Find

Please note that if another language than English is selected via the Language = xxx option, the commands have to be in that language as well (like "Start page = 0?cmd=Letzter" for German).

Submit Page = <file>

This optional page can be displayed when a new message was submitted in a logbook. Here is an example:

<h1>You successfully submitted a message</h1>
<a href="?cmd=Back">Back</a> to the logbook<p>
<a href="?cmd=New">Enter</a> another message

The file must be present in the logbook directory. Alternatively, an absolute path can be used if the file name starts with a "/" (Unix) or "" or "x:" (Windows).

Message comment = <comment>

This optional comment is displayed on top of the text entry field when submitting a new message. It can contain a sentence like "Please enter your message here:".

Reply comment = <comment>

This optional comment is displayed on top of the text entry field when replying to an exiting entry. It can contain a sentence like "Please enter your reply here:".

Attachment comment = <comment>

This optional comment is displayed on top of the attachment sumbission section when entering a new message. It can contain a sentence like "Please upload your attachments here:".

Menu commands = <list>

This option specifies the menu commands displayed on top of a single logbook page. For certain installations, it can be useful to disable some commands. Following commands are possible:

• New - Enter new logbook entry
• Edit - Edit current logbook entry
• Delete - Delete current logbook entry
• Reply - Submit a reply to current entry
• Duplicate - Duplicate the current entry with the possibility to change some values
• Download - Download a message in ASCII format
• Find - Search entries in logbooks
• Last day - Display entries from last day
• Move to - Move entry to other logbook
• Copy to - Copy entry to other logbook
• Config - Edit elogd.cfg (if no "Password file" is given)
• Config - Modify/Add user accounts (if "Password file" is given)
• Admin - Edit elogd.cfg (if "Password file" is given)
• Login - Login with user name and password (if "Password file" is given)
• Import - Show CSV (comma-separated-values) import page
• Logout - Logout current user (if "Password file" is given)
• Help - General help

The commands are always in English, independent of the language = ... setting, and are automatically translated into the specified language.

If this option is not present, following default is used:

Menu commands = List, New, Edit, Delete, Reply, Duplicate, Find, Config, Help

Copy to = <logbook list>

Move to = <logbook list>

The commands Copy to and Move to make it possible to copy or move a logbook entry from one logbook to another. By default, all logbooks except the current logbook are shown as a possible destination. With the configurations options Copy to = <logbook list> and Move to = <logbook list> it is possible to specify a list of destination logbooks, separated by commata. This can make sense if only certain logbooks make sense as destinations. The flag Preserve IDs can be used to keep the entry ID in the destination logbook.

List Menu commands = <list>

This option specifies the menu commands displayed on top of the listing page. Although all commands from a above are possible, only the commands New, Find, Select, Import, Config, Admin, Change password, Logout and Help make sense. The command Select can be used to select multiple messages for deletion or for moving to other logbooks. Once the Select command is clicked, check boxes appear in front of all entries which let the user select one or more entries. A new menu bar shows up with a Delete and optionally a Coyp to ... and Move to ... button, if these commands are present in the Menu commands list. Pressing one of these buttons deletes, copies or moves all selected logbook entries.

Guest Menu commands = <list>

This option specifies the menu commands for guest logins. A guest login happens if a password file is used, but someone accesses the logbook for the first time, which means that no username/password is given. In that case the commands from the guest menu are displayed, which usually contain a subset of the normal commands. A typical scenario is a logbook which only has commands to read the logbook on the guest menu, but no commands to write/edit entries. Instead, the login command is given in the guest menu, with which one can login as a real user (username and password have to match those from the password file), which then allowes full access via the "Menu commands" list. A typical example for the menu settings for this scenario are:

  Menu commands = List, New, Edit, Reply, Duplicate, Find, Config, Logout, Help
  Guest menu commands = List, Find, Login, Help

Note that the presence of this option opens user access also to the find result or elog listing page, which usually contains some config command. So it is useful to combine the Guest menu commands option with the following Guest List Menu commands option to restrict the access to the find result page as well.

Guest List Menu commands = <list>

Same as Guest Menu commands but for the find result page.

Menu text = <file>

If this option is present, and additional menu row above the message gets displayed with the contents of <file>. This file can contain arbitrary text, images or links. One example would be following text to go back to the listing page and display the next Routine entry and all Routine entries:

<small>
&nbsp;<a href="?cmd=next&type=Routine">Next Routine entry</a>&nbsp;|
&nbsp;<a href="../?Type=Routine">All Routine entries</a>
</small>

List Menu text = <file>

The same for the list page.

Filter Menu text = <file>

The same for the filter line in the list page.

Guest Display = <list>

This option specifies which attributes are displayed on guest access. It is possible to display only a subset of all attributes for guest access, but the full list if someone is logged in (using the option "Password file"). The list consists of comma separated attributes, including the word text, if one wants to display the entry body text for guests.

<small>
&nbsp;<a href="?mode=summary">Summary</a>&nbsp;|
&nbsp;<a href="?mode=full">Full</a>&nbsp;|
&nbsp;<a href="?mode=threaded">Threaded</a>&nbsp;|
</small>

Top text = <file> | <string>

The text of this option gets displayed at the top of every Elog page. It can be a string or a filename which gets displayed. Might be useful to display company logos etc. If a file is specified, it must be present in the logbook directory. Alternatively, an absolute path can be used if the file name starts with a "/" (Unix) or "" or "x:" (Windows).

Bottom text = <file> | <string>

The text of this option gets displayed at the bottom of every Elog page instead of the little Elog home page link. It can be a string or a file. It can contain for example a link back to the main logbook selection page like:

<center><a href="/">Main page</a></center>

Or it can contain other useful links. If a file is specified, it must be present in the logbook directory. Alternatively, an absolute path can be used if the file name starts with a "/" (Unix) or "" or "x:" (Windows).

Bottom text login = <file> | <string>

The same as Bottom text but for the login page. This allows to display a different text at the bottom of the login page. It can also be used to execute some JavaScript.

Help URL = <URL>

This URL is used for the Help button. By default, the file eloghelp_xx.html is returned with the contents of the help page. Edit this file directly to add site-specific help for all logbooks. Alternatively, use the Help URL option to specify different help pages for different logbooks. It can point to a site-specific help page via http://... or to a local file like file://c:/tmp/config.html, or to the name of an HTML file which must be present in the resource directory.

Message Width = <number>

This value sets the number of characters per line of the main message entry field. The default value is 76 (78 for replies), and can be increased for installations which need a larger window size (like pasting log files etc.). If both Message Width and Message Height are not given, some JavaScript code is used which automatically resizes the message window dynamically to fit optimally into the browser window.

Message Height = <number>

This value sets the number of lines of the main message entry field. The default value is 20, and can be changed for installations which need a different window size. If both Message Width and Message Height are not given, some JavaScript code is used which automatically resizes the message window dynamically to fit optimally into the browser window.

Admin textarea = <cols>,<rows>

This defines the textarea size for the admin page. Default is 80,40.

Display mode = [full|summary|threaded]

Default mode for search display. On the find entry form, the checkboxes are set accordingly. The "Last xxx" page uses this setting directly.

Entries per page = <number>

Number of logbook entries displayed per page in a search result. The default is 20.

Restrict edit time = <hours>

If this option is set, a new message can only be edited a certain number of hours after its creation. This can be useful if one wants to ensure that old entries cannot be modified. Hours can also be fractional, like 0.5 for 30 min.

Admin restrict edit time = <hours>

Same option for admin users. This can be useful if normal users are not allowed to change entries after "restrict edit time", but an admin user should be allowed to do so. Setting this to zero disables any restriction for admin users and they can edit entries forever.

Max content length = <bytes>

This option restricts the size of attachments. When very large (>100MB) attachments are uploaded, the elogd server can be busy with this upload for a longer time and not respond to other requests during that time. To avoid this, the maximum size of attachments can be restricted. The server will then refuse to accept larger attachments. The default is 10485760 (= 10 MB). This option has to be placed into the [global] section and the elogd server has to be restarted after a change.

Fonts = <list>

List of fonts (comma separated) to be shown in the font drop-down box of the entry edit form. Default is

Fonts = Arial, Comic Sans MS, Courier New, Tahoma, Times New Roman, Verdana

On Unix systems some of these fonts might not be installed, in which case they can be replaced by others like Serif, Sans-serif, Helvetica.

All display limit = <n>

If a logbook contains many entries, the list gets divided into pages, with some page navigation for the next, previous, a specific page and all pages. If the logbook contains a large number of entries (>500), the display of all thes entries can take very long and might slow down the elogd server, especially if the entries are not displayed in "summary" mode but in "full" mode. Therefore the "All" link should not be used in the page navigation for large logbooks. The number of entries from when on the "All" link gets hidden can be specified with this number, the default value is 500.

Thumbnail size = <size>

This option determines the default thumbnail size. To make the automatic generation of thumbnails working, the ImageMagick package has to be installed. Refer to the admin guide for installation instructions. The thumbnail size size gets passed to the -thumbnail option of the conversion. A value of 300 converts all pictures to thumbnails 300 pixels wide. A value of 300> converts all pictures to thumbnails 300 pixels wide if they are larger than 300 pixels initially, and leaves them untouched if they are smaller. A value of 10% converts all pictures to 10% of their original size. If the thumbnail size option is missing, the thumbnails will be created with the original image size, and can then be resized and rotated interactively with the image manipulation buttons:

Setting Thumbnail size = 0 turns off the thumbnail creation.

Thumbnail options = <options>

With this option one can pass additional parameters to the ImageMagick package. They are passes 1:1 to the convert program. Commonly used is the -density option to increase the image quality when converting from PDF or EPS files.

Attributes

Attributes = <list>

Define a number of attributes for the logbook, separated by commata. A maximum of 100 attributes can be defined. Typical values are "Author", "Subject" or "Type". Following values are not allowed:

• Text
• Date
• Encoding
• Reply to
• In reply to
• Locked by
• Attachment
• Path

since these are used internally by elog.

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"

Extendable options = <list>

When using the Options <attribute> to specify a list of possible options, this list is fixed. Sometimes it is desirable to extend the list when a new entry in a logbook is made and a certain option is missing on the list. By adding the attribute name to the Extandable options list, a button appears next to the attribute in the message entry form which lets you add new options to the list. The elogd.cfg configuration file is then automatically updated. When a new logbook entry gets made, the new option automatically appears in the drop-down box for that attribute.

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.

Comment <attribute> = <comment>

Optional comment which is displayed below the attribute name in the entry form. Can be used to explain the attribute somehow.

Tooltip <attribute> = <comment>

Same as Comment <attribute>, except that the comment gets displayed as a tooltip (tiny pup-up window) when the user moves the mouse cursor over the attribute name in the entry form.

Tooltip <attribute> <attribute option> = <comment>

Same as Tooltip <attribute>, but for option values of a MOptions attribute. Using this option, a different tooltip can be shown above each check box of an optional value for an attribute. Please note that attributes or options with spaces should not be enclosed with quotes.

Icon comment <icon> = <comment>

Icons may contain a comment, which is then used in email notifications instead of the icon file name. One has to add a separate icon comment for each icon file.

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 logbook directory. Alternatively, an absolute path can be used if the file name starts with a "/" (Unix) or "" or "x:" (Windows).

Preset on edit <attribute> = <string>

Same as Preset <attribute>, but evaluated when editing existing entries.

Preset on reply <attribute> = <string>

Same as Preset <attribute>, but evaluated for replies.

Preset on first reply <attribute> = <string>

While Preset on reply <attribute>, is evaluated for any replies, this one is only executed for the first reply to an entry. It can be useful for example to so do something like this:

Preset on first reply Subject = Re: $Subject

So the "Re:" only gets added once, and you don't get long chains of "Re: Re: Re: ....".

Preset on duplicate <attribute> = <string>

Same as Preset <attribute>, but evaluated for duplicted entries.

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.

Show Attributes = <list>

Attributes present in this list are shown in the single entry page. Omitting attributes can make sense for attributes which are automatically derived from other attributes via the Change <attribute> command.

Show Attributes Edit = <list>

The same as Show Attributes, but for the entry form.

Propagate Attributes = <list>

With this option, changed in an attribute are autmatically propagated to all entries of a thread. This can be useful if one has an attribute "problem status" for example with the options "open", "under investigation", "fixed". A thread related to a specific problem can then have several replies. If the problem gets fixed, a new reply can be made with the attribute "problem status" being "fixed", and then the propagation causes all entries of this thread to become "fixed".

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.

Edit Page title = <string>

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

List display = <list>

Specified the display and order of items in a message listing page or a search result page. In addition to all attributes, following items can be specified:

• ID for the entry ID
• Date for the entry date/time
• Edit to display a column with an edit icon to directly edit and entry
• Delete to display a column with a delete icon to directly delete and entry

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\

List display = ID, 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. If a search goes over "all logbooks", an additional colums with the logbook name of each entry is added in front.

Guest List display = <list>

Same as List display, but for guest access (user level access with password, but not logged in). Please see also Guest display. In addition to List display, one can optionally specify Text as an attribute here. Without that attribute, the summary text of the entry body is not shown. This makes it possible to show the text for registered users and hide it for guest access.

Link display = <list>

Normally, each column in the display list contains a link to the individual entry. If this is not desired, the list of attributes with links can be restricted to only a subset with this option.

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 time: The message date and time, formatted via "Time format"
• $message id**: The message ID

A typical example would be

Thread display = $subject, posted by $author on $entry time

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 contained in the themes directory.

RSS Title = <string>

ELOG supports so-called RSS feeds. Once can subscribe to new logbook entries with RSS readers such as Mozilla Firefox. Once new entries are submitted to the logbook, the become visible in the subscripition. By default, all attributes of the last 15 logbook entries are used as the RSS title. With this option once can changed this behaviour. Following substitutions are possible:

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

A typical example would be\

RSS Title = $subject, posted by $author on $entry time

RSS Entries = <n>

Number of entries to be shown in the RSS feed. Default is 15.

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"
• $utcdate: The current UTC date (GMT) and time, formatted via "Date format"
• $version: The version of the ELOG server in the form x.y.z
• $revision: The Subversion reversion of the ELOG server as an integer number
• $shell(<command>): <command> gets passed to the operating system shell and the result is taken for substitution.

Following example use this feature to add the remote host name to the author:\

Subst Author = $author from $remote_host

Following example substitutes an attribute with the contents of a file:

Subst Info = $shell(cat /tmp/filename)              (Unix)
Subst Info = $shell(type c:\tmp\filename)           (Windows)

A special option are automatically generated tags, which are automatically incremented for each new message. This is achieved by putting #'s into the substitution string, which is used as a placeholder for the incrementing index. Each "#" stands for one digit, thus the statement

Subst Number = XYZ-#####

results in automatically created attributes "Number" of the form

XYZ-00001
XYZ-00002
XYZ-00003

and so on. In addition to the #'s one may specify format specifiers which are passed to the strftime function. This allows to create tags wich contain the current year, month and so on. Once the date part of the attribute changes, the index restarts from one. The statement

Subst Number = XYZ-%Y-%b-###

results in automatically created attributes "Number" of the form

XYZ-2005-Oct-001
XYZ-2005-Oct-002
XYZ-2005-Oct-003

and

XYZ-2005-Nov-001
XYZ-2005-Nov-002

on the next month.

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.

Quote on reply = 0 | 1

This flag controls if the original text is quoted in a reply. Default is 1

Reply string = <string>

String used to mark original message lines. Default is "> ". Can be empty string ("") if no message marking is desired.

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

Note that this option works only for the first reply. So a reply-to-a-reply would still have Re: <old subject> and not Re: Re: <old subject>. If you want the substitution for all replies, please use Preset on reply instead.

Subst on edit <attribute > = <string>

Substitution of attributes for edited messages. This option can be used to replace the author by the current author for example:\

Subst on edit author = $full_name

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 and the option Subtext can be listed here. Using the Date filter, the last day, week, month and so on can be displayed. The Subtext filter works on the entry body text.

Last default = <n>

Some logbooks are very big and searching through all entries with a quick filter can be time consuming. This option sets a default value for the Date quick filter, so that by default only the <n> last days are displayed. <n> has to match one of the entries of the data quick filter options, which are 1, 3, 7, 31, 92, 182, 364.

Format <attribute> = <flags>,<css_class_name>,<css_class_value>,<width>,<size>

Optional formatting parameters for attributes. Following items can be defined in the comma-separated list:

Values used for single message display page:

• <flags> Sum of following flags:
  • 1: Display attribute in same line as previous attribute
  • 2: Display radio buttons or check boxes in separate lines (if applicable)
• <css_class_name>,<css_class_value> Cascading Style Sheet class names used for cells containing attribute name or value, respectively. The classes must be defined in the style sheet file (usually themes/default/default.css).

Values used for new message entry form:

• <width> Width of the text entry field in characters
• <size> Maximum number of characters allowed.

Default is "0, attribname, attribvalue, 80, 500". Trailing parameters can be ommitted, so specifying for example only the flags is possible.

Type <attribute> = date | datetime | numeric | userlist | useremail | muserlist | museremail

A normal attribute can contain strings of any type. With this option, attributes can be forced to be numeric or to be a date/time, or to consist of a list of all users from the password file. When new logbook entries are made, numeric attributes are checked to contain only digits. Note that JavaScript has to be enabled to do this.

Attributes of type date are treated as a date. Their format for display can be controlled by the Date format option. Upon entry, drop-down boxes are displayed which let the user select the day, month and year. Alternatively, a pop-up date picker using a calendar can be displayed if JavaScript is enabled. Date attributes are saved internally as seconds since 1.1.1970, and can therefore be sorted propoerly by clicking on the header of a logbook entry list. On the find page, dates can be searched for via a start and end date. If date attributes are used in a quick filter (see above), a drop-down quick filter box is displayed which lets the user select "last day", "last week", "next week", and so on. The datetime type combines a date and time in HH:MM. The output of this combination is controlled by the Time format option.

If the attribute type is userlist, a drop-down box is displayed which contains all user names from the current password file. This can be useful for example in a bug tracking system, where a new entry gets assigned to an individual. The type useremail is similar, just a list of email addresses of all registered users. This can be used to send email notification to assigned people by using this attribute in an Email all = <attribute> statement. The type muserlist and museremail are the same that userlist and useremail, except that several user names or user emails can be selected at once using check boxes.

Style <attribute> <value> = <style>

Optional formatting of logbok entries in list mode. For some logbooks it might be useful to display different entries in a different color for example. To achieve this, a CSS style sheet can be attached to an entry based on the value of an attribute. If you have an attribute called importnace and you want to highlight all entries where importnace is severe for example, you can specify following style:

Style importance severe = background-color:red

For possible formattings, please refer to some CSS documentation. You can change the colors, font styles and sizes. The style is then valid for the whole row of that entry.

For empty attributes one can specify "", such as

Style importance "" = background-color:red

Cell Style <attribute> <value> = <style>

Same as above, but only for a specific cell containing <attribute>. Following options

Attributes = Author, Status
Options Status = Fixed, Under Process, Not Fixed
Cell Style Status Fixed  = background-color:green
Cell Style Status Not Fixed  = background-color:red
Cell Style Status Under Process  = background-color:yellow

for example produce following listing:

Change <attribute> = <string>

Instead of subsituting an attribute, the original attribute can be kept and just the output formatting can be changed. This can be very handy for constructing HTML links out of attributes. Presume that a company has a telephone book reachable under

http://any.company.com/telbook.cgi?search=<name>

where <name> has to be replaced by a search string. Now one can construct an automatic telephonebook lookup with following options:\

Attributes = Name, Telephone, ...
Change Telephone = <a href="http://any.company.com/telbook.cgi?search=$Name">$Name's telephone number</a>

The attribute Telephone is now automatically constructed from the attribute Name and consists of a link to the company's telephonebook. The advantage of this system is if the URL of the telephonebook changes one day, only one statement in the config file has to be changed, while otherways (like with the Subst Telephone = ... option) all entries would have to be changed manually.

List Change <attribute> = <string>

Same option for the list display.

Execute new | edit | delete = <command>

It is possible to execute a shell command on the server side after a new message has been submitted, edited or deleted. This feature has been used in the past for SMS notifications over a telephone system and for synchrnonization of the ELOG database with an external SQL database. The <command> can contain substitutions similar to the Subst command. In addition the list of all attachments can be referred to via $<attachments>. The text body of the entry can be referred to with $text. It should be noted that only the first 1500 characters of the text can be used, in order not to exceed the limits of the shell. Following (Unix) command writes a notification into some file:

Execute new = echo "New message wiht ID $message id of type $type from $long_name on $remote_host" >> /tmp/elog.log

It should be noted that this feature can impose a security problem. If someone can edit the elogd.cfg through the Config command of elogd, that person can put malicious code into elogd.cfg and execute it. This is even more severe if elogd runs with root privileges. To avoid such problems, the execute facility is disabled in elogd by default and has to be enabled explicitly with the "-x" command line flag. The administrator has to ensure then of course that only trusted people can edit elogd.cfg.

Last submission = <string>

This option determines what gets displayed on the logbook selection page in the Last submission colum. The default string is $entry time by $author. If a logbook does not contain an author attribute, another string can be chosen.

ID display = <string>

This option determines the display of the entry ID. In some applications, the entry ID can be used as a tag, containing more than just the ID number. For example

ID display = TAG-$message id

would display the entry ID as "TAG-1","TAG-2", ... and so on.

Prepend on reply = <string>

With this option a string can be placed on top of a reply. Using string substition, this can be useful for adding the author and the date of a reply, like

Prepend on reply = Added $date by $long_name\n\n

where "\n" causes a line break.

Append on reply = <string>

Same as before, but gets added after the previous entry.

Prepend on edit = <string>**

Append on edit = <string>

Same as before, but for editing entries.

Sort Attributes = <list>

For the list display, the entries are normally sorted by their ID. Alternatively, one can specify one or more (separated by commata) attributes, which are used for sorting. The first attribute in the list has the highest priority. Only if two entries have the same value in the first sort attribute, they are sorted according to the second sort attribute and so on. To the list of attributes one can add ID, Date and logbook, although ID makes only sense together with other attributes, since it is sorted as the primary key anyhow.

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

Attributes = PC Name, Operating System, Version, Distribution
Options Operating System = Linux{1}, Windows{2}
{1} Show Attributes Edit = Operating System, Distribution, PC Name
{2} Show Attributes Edit = Operating System, PC Name, Version

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:

Attributes = PC Name, Operating System, Version, Location, Floor
Options Operating System = Linux{1}, Windows{2}
Options Location = Main Building{a}, New Building{b}, Old Building{c}
{1} Options Version = 2.2, 2.4, 2.6
{2} Options Version = ME, 2k, NT, XP
{a} Options Floor = Ground, First, Second
{b,c} Options Floor = Ground, First

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

{1&a} ...

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

List conditions = 1

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:

Password file = <file>

Login expiration = <hours>

Admin user = <user list>

Login user = <user list>

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

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- created by MXML on Tue Nov 07 08:15:51 2006 -->
<list>
  <user>
    <name>stefan</name>
    <password encoding="SHA256">Ebx/a.9tFFQ/iUW3mU8GbnPpCVk74jFt56CmiJXVwdm</password>
    <full_name>Stefan Ritt</full_name>
    <last_logout>Tue Oct 17 12:59:47 2006</last_logout>
    <last_activity>Tue Nov 07 08:15:51 2006</last_activity>
    <email>stefan.ritt@psi.ch</email>
    <email_notify>
      <logbook>demo</logbook>
    </email_notify>
  </user>
  <user>
    <name>midas</name>
    <password encoding="SHA256">t56CmiJXVwdmEbx/a.9tFFQ/iUW3mU8GbnPpCVk74jF</password>
    <full_name>Midas User</full_name>
    <last_logout>0</last_logout>
    <last_activity>0</last_activity>
    <email>midas@psi.ch</email>
    <email_notify>
      <logbook>demo</logbook>
    </email_notify>
  </user>
</list>

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:

• Specify a password file name with Password file = <file> in the configuration file
• Connect to the logbook. You will be presented with the new user page. Enter the user login name, full name, email and password, then click on the "Save" button.
• 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, ... Subst Author = $long_name from $remote_host Subst 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. 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.

Self register = 0|1|2|3|4

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.

Allow password change = 0|1

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.

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.

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:

Authentication = <method(s)>

Kerberos Realm = <realm>

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.

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

• Enable LDAP authentication in the Makefile by setting USE_LDAP = 1
• Change elogd.cf to contain LDAP authentication:
• Authentication = LDAP
• LDAP server = ldap://example.org:389
• LDAP userbase = ou=People;dc=example,dc=org
• LDAP login attribute = uid
• LDAP register = 1

The login attribute is from the DN (distinguished name), e.g. uid=user,ou=People,dc=example,dc=org. The register flag determines if LDAP users are automatically stored in the local password file, which is necessary for email notifications.

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. To use PAM in elogd, do the following:

• Compile elogd with PAM support, by either setting USE_PAM = 1 in the Makefile, or by specifying it when invoking make. If you compile via CMake, set USE_PAM via ccmake.
• Enable PAM authentication in elogd.cfg:
• Authentication = PAM
• Password file = elogd.passwd
• Self register = 3

The Password file is used to store the user names and email addresses of PAM authenticated users, since this information can not be (universally) requested via PAM. For security reasons the password file does not store a hash of the user password. Self registration has to be enabled (Self register ≥ 1) to use PAM authentication. - To be able to use PAM, the PAM module in elogd needs to be able to access the authentication facilities on the system (e.g. be able to read /etc/shadow). This can be achieved by either running elogd as root, or by specifying the appropriate SUID/GUID values for the binary. [WARNING:]{style="color:red"} When running elogd as root, be careful when using the -x option to enable execution of commands via $shell, since the commands will be executed using the access rights of the user running elogd!

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

• Email <attribute> <value> = <list>
• Use Email Subject = <string>
• Use Email Subject Edit = <string>
• Use Email From = <string>
• Default Email From = <string>
• Use Email Heading = <string>
• Use Email Heading Edit = <string>
• Omit Email To = 0|1
• Suppress Email to users = 0|1
• Email attributes = <list>
• Use Email URL = <URL>

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 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. []{#flags}

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

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.

Enable attachments = 0|1

This flag controls the attachment submission at the bottom of a message entry page. If this flag is 0, the attachment section is not displayed. This might be useful for logbooks where attachments are not used. 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.

Preview attachments = 0|1

This flag controls the display of attachments in the edit form. If one one uploads an attachment, but has not yet submitted the entry, the uploaded attachments are shown at the bottom if this flag is 1. Only ASCII files and images are shown of course. 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.

Summary line length = x

This specifies the number of charactes of the summary lines. After this number of charactes, a line break is inserted in long lines to keep the column width not too wide. The default is 40.

Attachment lines = x

This specifies the number of text lines displayed for ASCII attachments. For long ASCII attachments, it can be useful to only display the first few lines not to make the HTML page too long. The default is 300.

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" query) 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|2

If this flag is 1 or 2, the search form displays the button "Search all logbooks". If the flag is 2, the button is checked by default. Setting this flag to 0 hides this button. It might be necessary to do this for public logbooks if there are also protected logbooks. Otherwise the search result would also display entries from the protected logbooks. The default is 1.

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

Default encoding = 0|1|2

This specifies the default encoding for new entries. For installations where entries are normally submitted as plain text, the default can be set to 1. Set to 0 for ELCode encoding, to 2 for HTML encoding. The default is 2, which activates the built in FCKeditor automatically for new installations. If this editor is not wanted or people are concerned about cross site scripting, the default encoding should be set to 0 or 1.

Allowed encoding = <n>

Allowed encoding options. <n> can be the sum of following flags: - 1 : Plain - 2 : ELCode encoding - 4 : HTML encoding

To allow plain and HTML encoding for example, set <n> to 5. Default is 7. Note that allowing HTML encoding may cause some security risk, since an elog entry may contain malicious scripting code. It should therefor only be allowed for installations where it is really needed and with no public write access.

Allow HTML = 0|1

This flag allows or denys the usage of HTML in attributes. Note that allowing HTML encoding may cause some security risk, since an elog entry may contain malicious scripting code. It should therefor only be allowed for installations where it is really needed and with no public write access. The default value is 0.

Suppress default = 0|1|2|3

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. If this value is set to 3, the email notification is always suppressed. The default is 0.

Suppress Email on edit = 0|1|2|3

This is the same as Suppress default, but just for edited entries. 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.

Resubmit replies = 0|1

If this flag is set to 1 and an entry is resubmited as a new entry and this entry has replies, all replies of this entry are resubmittes as new entries as well. 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 Format = <n>

Specifies what is sent in an email notification. <n> is the sum of following flags:\ - 1 : Send heading line "A new entry has been submitted..." - 2 : Send attributes - 4 : Send URL of logbook entry - 8 : Send message body - 16: Send optional attachments as email attachments - 32: Send logbook name - 64: Send names of optional attachments

So to send for example only the attributes and the URL, set <n> to 6. Default is 63 (send everything).

Email Encoding = <n>

Specifies in which encoding an email is sent. <n> is the sum of following flags:\ - 1 : Plain text - 2 : HTML in the form of the plain text, but with ELCode interpreted - 4 : Full HTML page as shown in elog

So to send email in plain text and full HTML, set <n> to 5. Some email clients have the possibility then to switch from one view to the other. Default is 2.

Max email attachment size = <n>

This option specifies the maximum allowed email attachment size for email notifications. Most mail delivery systems have a maximum attachment size and refuse to accept emails with larger sizes. If the size of an attachment exceeds this limit, it is not included in the email notificaiton but rather a link to the attachment on the elog server is used. The default value is 10000000 (ten million bytes).

Back to main = 0|1

If this flag is 1, the "List" 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.

Logout to URL = <URL>

If this URL is set, the "Logout" operation takes you to a specific web page specified in the URL.

List after submit = 0|1

If this flag is 1, the list page is shown after the submission of a new entry. If this flag is 0, the entry just submitted is shown. 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.

Hidden = 0|1

If this flag is 1, the logbook is not displayed in the initial logbook selection page and in the logbook tabs. This can be useful for logbooks which are only accessed for backup or archiving and would clutter up the logbook list for the normal user. To access hidden logbooks, one has to enter the logbook URL directly, or from a bookmark list. Default is 0.

Hide Comments = 0|1

If this flag is 1, the logbook "Comment" is not displayed in the logbook selection page. Default is 0.

Use Lock = 0|1

If this flag is 1, a logbook entry is locked when someone edits it (clicking the Edit command). A locked message gets displayed with a little red sign indicating that the message is currently edited by someone and should not be touched. This can be helpful in installations where several people can edit messages. Without locking, the second submission of an edited message overwrites the first submission without notice. Although the sign gets displayed, the message can still be edited (the lock can be "stolen"), but it's the user's response to avoid any conflict.

Since elog cannot determine if someone keeps a message very long for editing or if only the browser got closed, the locking can show up even if the message is not kept for editing any more. In that case, the message has to be edited again and submitted, to remove the origial lock.

Note that logbooks accessible from the internet usually get scanned by search engines. This can lead to situations where the Edit link of each message is "followed" by a bot, resulting in all messages being locked. In those cases locking has to be turned off.

Since release 2.5.4, some Javascript code has been added to avoid unwanted locks. If someone edits an entry, but then goes away from that page or closes the browser without submitting the changes, a pop-up window appears asking the user to submit the changed entry. Although this works for most browsers in most cases, it could be that Javascript has been turned off in a browser, in which case the stale locks still might appear.

Default for "Use Lock" is 0.

Show top groups = 0|1

When using top groups, the root of the elogd server is not accessible any more, to avoid cases where one group can "see" the logbooks of the other groups. If this feature is unwanted, the flag Show top groups can be set to 1, in which case a list of available top groups is shown.

Fix text = 0|1

With this options the main text body can be fixed, so that it cannot be changed via the Edit button later. This feature can be useful for set-ups where some attributed must be changed later, but the text body should be preserved. The default is 0.

Case sensitive search = 0|1

This switch has two meanings. First, it defines the default state of the Case sensitive check box in the "Find" page. Second, it determines if the quick filters are case sensitive or not. The default is 0.

Mode commands = 0|1

If this flag is missing or set to 1, the links "Full", "Summary" and "Threaded" are shown on the top of the listing page. If this flag is set to 0, these commands are hidden. This might be useful in logbooks where only one mode makes sense for example.

Suppress execute default = 0|1

External scripts can be called with the Execute new/edit/delete options. If these options are enabled, a checkbox appears which lets the user suppress execution of the external script. The setting of this flag determines the default state of this checkbox. In logbooks where a script should only be ocasionally executed, it could make sense to set this flag to 1.

Preserve IDs = 0|1

When a logbook entry is copied or moved to another logbook, it obtains a new entry ID in the destination logbook. This can cause problems if the logbook entries reference each other with their IDs. To keep the same ID in the destination logbook, this setting can be set to 1. If an entry with the same ID in the destination logbook exists already, it gets overwritten. Default for this setting is 0.

Collapse to last = 0|1

In threaded view, the list of replies can be collapsed into a single entry. If this flag is 1, then the last entry of each thread is shown, otherwise the first thread is displayed. Default for this setting is 1.

Sort Attribute Options <attribute> = 0|1

If this option is 1, the options for this attribute are sorted alphanumerically. This can be handy when locating options from long lists in drop-down boxes in quick filters for example. Default for this setting is 0.

Allow branching = 0|1

With this option one can probihit "branching", which is that an entry gets more than one reply. When branching is prohibited, only linear threads are possible, which is one head entry, one reply to it, then one reply to the reply and so on. Default for this setting is 1.

Enable Smileys = 0|1

When encoding an entry with ELCode, certain sequenes such as :-) get automatically converted into small "smiley" images. If this behavior is not wanted, it can be turned off with this option. The default for this setting is 1.

Refresh = <seconds>

The elog listing page can be refreshed periodically with this option. If it is given, the page automatically reloads after <seconds>. This can be useful for logbooks where other people often post entries or where some entries are posted automatically (via the elog utility) and one wants to keep an eye on what's new. The default for this setting is 0 meaning no refresh.

Show last default = <days>

In large logbooks, search operations can take quite long, blocking other users from accessing ELOG. On the Find page, one can restrict the search operation to a certain time period, like last day, last week, etc, which makes searching much faster, but restricts it to a certain time in the past. If one forgets however to enter anyting in the Show last drop-down box, then the search again can take quite long. This option pre-selects an option in the Show last drop-down box, so that the user does not have to think about selecting a certain time period. Following options are possible: 0, 1, 3, 7, 31, 92, 182, 364. "0" means an unrestricted search default.

Save drafts = 0|1

Starting with version 3.1, ELOG supports auto saving. When text for a new entry is entered in the browser, it might get lost if the browser windows is closed before the entry has been submitted. In order to avoid this, entries can be saved as drafts, to be finished and submitted later. This can be achieved by clicking on the Save button or by the autosave feature (see next option). The Save drafts option turns this feature on or off. Default is 1.

Autosave = <seconds>

Drafts can be sent to the server regularly after some editing (see previous option). This option determines the interval this is done. The default is 10 seconds after the last edit. Setting Autosave to zero disables the autosave functionality.

List drafts = 0|1

By default, draft entries are shown in the list display in another browser when the entries are currently edited. This can be confusing to other users since the draft entries are frequently updated. To avoid this, this flag can be se to 0, which hides all draft entries in the list view. If they are hidden, the only way to come back to them is to hit the New menu item, in which case the system presents to the user a list of open draft messages to be continued.

Hard wrap = 0|1

If entries are entered in plain text mode, the browser adds automatically a CRLF at the end of each line where the text wraps. This ensures that the submitted entry has the same line breaks as in the edit box. If this behaviour is not wanted, the adding of hard wraps can be turned off by setting this value to 0. If the user then enters a very long line without hitting the newline key, the long line is preserved which can make it hard to read.

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:

Mirror server = <URL-list>

This statement specifies one or more mirror servers. Each URL must contain the host, port and possible subdirectory of the remote server, as if you would access it through your browser. A typical statement looks like:

Mirror server = myhost.mydomain.org:8080, http://another.server.org/elog/, https://yet.another.org

The URL should not contain any logbook name, this gets added automatically. The second example contains a subdirectory, which is typically used if the elogd daemon runs under an Apache proxy. The third example shows a server running under the SSL protocol.

Mirror config = 0 | 1

Normally, only the logbook entries are mirrored. One can also mirror the contents of the elogd.cfg configuration file for individual logbooks. This can be turned on by setting this option to 1. Default is 0. Only the individual logbook section is mirrored, not the [global] section. Settings which are specific to one server, for example the URL = statement, should then be kept in the [global] section, so that they are not mirrored between different servers.

Mirror cron = Minute Hour Day Month Weekday

This statement turns on periodic mirroring. The format is similar to the UNIX cron command. Each of the five values can either be an asterisk, which means all possible values, a comma-separated list or a range. It can be explained most easily with examples:

Mirror cron	meaning
0 3 * * *	Every night at 3:00
30 7 1,15 * *	At 7:30 every 1st and 15th of a month
0 12 10 10 *	Once a year at 12:00 on my birthday
0 7-18 * * 1-5	Once every hour from 7:00 to 18:00 from Monday to Friday

Valid ranges for each value are:

Item.	Range
Minute	0-59
Hour	0-23
Day	1-31
Month	1-12
Weekday	0-6 with 0=Sunday, 1=Monday, etc.

If mirroring is turned on, it is advisable to use the Logfile = option to turn on logging, so that one can inspect the logfile to see if the mirroring works correctly.

Mirror user = <name>

If periodic mirroring is used via the Mirror cron = statement and the remote logbook uses user-level access, this statement specifies the user name which is used to log in to the remote logbook. The password is taken from the local password file and has to match the password in the remote password file, otherwise the access is not allowed. The user name is typical the login name of the administrator.

Mirror simulate = 0 | 1

If one wants to try out mirroring without causing any harm, one can turn on this flag. During synchronization, entries are compared and necessary transfers are displayed, but not executed. Default is 0.

Mirror exclude = 0 | 1

By default, all logbooks are mirrored. Individual logbooks might be excluded from mirroring by putting Mirror exclude = 1 in their individual logbook section of the configuration file (Not the [global] section). Default is 0.

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:

• If an entry has been modified locally but not remotely, it is submitted to the remote server.
• If an entry has been modified remotely but not locally, it is retrieved from the remote server and saved locally.
• If an entry has been modified remotely and locally since the last synchronization, an error is shown that the entries are conflicting. In that case one has to merge the entries manually and delete it on one side.
• If an entry has been deleted locally, it is deleted remotely.
• If an entry has been deleted remotely, it is deleted locally.
• If a new entry exists locally, it is submitted.
• If a new entry exists remotely, it is retrieved from the remote server and saved locally.
• If new entries exist locally and remotely having the same entry ID, the local entries are changed to have higher entry IDs, then the remote ones are retrieved. Care should be taken if external links (such as elog:123) to the local entries are used, since they will point afterwards to the wrong entry.

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.