+
+
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 enabledelogd 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.
+
+
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.
+
+
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.
+
+
Same, but just for an individual attribute.
+
+
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.
+
+
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).
+
+
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:".
+
+
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:".
+
+
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.
+
+
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>
+ <a href="?cmd=next&type=Routine">Next Routine entry</a> |
+ <a href="../?Type=Routine">All Routine entries</a>
+</small>
+
+
+
The same for the list page.
+
+
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>
+ <a href="?mode=summary">Summary</a> |
+ <a href="?mode=full">Full</a> |
+ <a href="?mode=threaded">Threaded</a> |
+</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.
+
+
Optional comment which is displayed below the attribute name in the
+ entry form. Can be used to explain the attribute somehow.
+
+
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.
+
+
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.
+
+
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 IDDate for the entry date/timeEdit to display a column with an edit icon to directly edit
+ and entryDelete 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.
+
+
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
+
+
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.
+
+
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:
+
{border="0"}
+
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 = LDAPLDAP server = ldap://example.org:389LDAP userbase = ou=People;dc=example,dc=orgLDAP login attribute = uidLDAP 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 = PAMPassword file = elogd.passwdSelf 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|1Suppress Email to users = 0|1Email 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.
+
+
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.
+
+
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:
+
+-
+
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.
+
+-
+
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.
+
+