3294 lines
138 KiB
HTML
Executable File
3294 lines
138 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Windows (vers 1 June 2005), see www.w3.org">
|
|
<title>
|
|
ELOG - Syntax of elogd.cfg
|
|
</title>
|
|
<link rev="made" href="mailto:fredpmygale.org">
|
|
<meta name="author" content="Fred Pacquier">
|
|
<meta name="description" content=
|
|
"Home of the Electronic Logbook (ELOG) package">
|
|
<meta name="keywords" content="ELOG MIDAS PSI RITT">
|
|
<link rel="stylesheet" type="text/css" href="elog.css">
|
|
</head>
|
|
<body bgcolor="white" text="black" link="blue" vlink="purple" alink="red">
|
|
<div class="title">
|
|
ELOG - Syntax of elogd.cfg
|
|
</div>
|
|
<br>
|
|
<div class="menu">
|
|
[<a class="nav" href="adminguide.html">back to Administrator's
|
|
Guide</a>]
|
|
</div>
|
|
<br>
|
|
<div class="menu">
|
|
* Server : [<a class="nav" href="#global">Global</a>] - Logbooks :
|
|
[<a class="nav" href="#general">General</a>] [<a class="nav" href=
|
|
"#groups">Logbook groups</a>] [<a class="nav" href=
|
|
"#attrib">Attributes</a>] [<a class="nav" href=
|
|
"#conditional">Conditional Attributes</a>] [<a class="nav" href=
|
|
"#email">E-mail</a>] [<a class="nav" href="#access">Access
|
|
Control</a>] [<a class="nav" href="#flags">Flags</a>] [<a class="nav"
|
|
href="#themes">Themes</a>] [<a class="nav" href=
|
|
"#mirroring">Mirroring</a>] *
|
|
</div>
|
|
<br>
|
|
<div class="Sub">
|
|
<i>Global and individual logbook options for an ELOG server</i>
|
|
</div>
|
|
<hr>
|
|
<p>
|
|
The configuration file <b><code>elogd.cfg</code></b> contains entries
|
|
which define the structure of logbooks and the behaviour of
|
|
<code><b>elogd</b></code>. The file has a simple ASCII format. Each
|
|
logbook is defined by a <b><code>[<name>]</code></b> section where
|
|
<name> is the name of the logbook. The <b><code>[global]</code></b>
|
|
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.
|
|
</p>
|
|
<p>
|
|
Here is a simple example, which define two logbooks, "<i>Linux</i>" and
|
|
"<i>PC</i>":
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
[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
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<a name="global" id="global"></a>
|
|
</p>
|
|
<hr>
|
|
<div class="title">
|
|
Global options
|
|
</div>
|
|
<p>
|
|
The notation of the following options is such that items enclosed by
|
|
<b>"<"</b> and <b>">"</b> should be replaced by a specific string.
|
|
If a value contains blanks (like a complete sentence), it should
|
|
<b>not</b> be enclosed in quotation marks.
|
|
</p>
|
|
<p>
|
|
If a setting has a number of possible options, they are shown in the form
|
|
<code><b>option1|option2|...</b></code>, meaning that one of the options
|
|
(without any vertical bar) should be used. The following options are
|
|
specific to the <b><code>[global]</code></b> section:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Port = <port></code></b><br>
|
|
Specifies the TCP port under which the server is listening. Default is
|
|
80. Can be superseeded via the '-p' command line flag.
|
|
</li>
|
|
<li>
|
|
<b><code>SSL = <0 | 1></code></b><br>
|
|
Turn on Secure Socket Layer transport. If SSL is on, one can connect
|
|
via <code><b>https://...</b></code> to the elogd daemon. If the
|
|
<code><b>URL =</b></code> directive is used, make sure to use
|
|
<code><b>https://...</b></code> instead of <code><b>http://...</b></code>
|
|
there. The ELOG distribution contains a simple self-signed certificate
|
|
in the <code><b>ssl</b></code> 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 <code><b>0</b></code>.
|
|
</li>
|
|
<li>
|
|
<b><code>Interface = <interface></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Resource dir = <directory></code></b><br>
|
|
Specifies the root directory for ELOG resources like help files,
|
|
themes and icons. Can be overwritten with the
|
|
<b><code>-s</code></b> flag when starting elogd. If not specified, use
|
|
the directory where the configuration file
|
|
<b><code>elogd.cfg</code></b> resides. <i>Changing this option requires
|
|
a restart of the elogd server</i>.
|
|
</li>
|
|
<li>
|
|
<b><code>Logbook dir = <directory></code></b><br>
|
|
Specifies the root directory for logbooks. Can be overwritten with the
|
|
<b><code>-d</code></b> flag when starting elogd. If not specified, use
|
|
the directory where the configuration file
|
|
<b><code>elogd.cfg</code></b> resides. Each logbook data is stored in a
|
|
separate directory under this root directory specified by the
|
|
<b><code>Subdir</code></b> option. <i>Changing this option requires a
|
|
restart of the elogd server</i>. This directory also contains any
|
|
password file and user HTML file.
|
|
</li>
|
|
<li>
|
|
<b><code>Language = <name></code></b><br>
|
|
The language setting determines the language of the
|
|
<code><b>elogd</b></code> output. Not affected by this setting are the
|
|
configuration file options and the commands specified with the optional
|
|
<code><b>Menu commands</b></code> and <code><b>List menu
|
|
commands</b></code>, 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.<br>
|
|
<br>
|
|
If a language name is given (currently "<i>german</i>",
|
|
"<i>french</i>", "<i>spanish</i>", "<i>dutch</i>", "<i>brazilian</i>"
|
|
are supported out-of-the-box), the system searches for a file named
|
|
<b>eloglang.<name></b> containing string translations from
|
|
English into that language. <i>If you create a new translation file,
|
|
please send it back to the author to be included in future
|
|
distributions</i>.<br>
|
|
<br>
|
|
The online help for <code><b>elogd</b></code> is contained in the file
|
|
<b>eloghelp_<i>xx</i>.html</b> where <i>xx</i> are the first two
|
|
letters of the language (like "<i>en</i>", "<i>ge</i>" and
|
|
"<i>fr</i>"). For new languages, a new file of that type must be
|
|
created as well.
|
|
</li>
|
|
<li>
|
|
<b><code>charset = <name></code></b><br>
|
|
Specifies the charset of the pages produced by
|
|
<b><code>elogd</code></b>. Can be used to switch to Russian or Asian
|
|
fonts.
|
|
</li>
|
|
<li>
|
|
<b><code>Logbook Tabs = [0|1]</code></b><br>
|
|
This flag controls the display of "<i>tabs</i>" on top of the logbook
|
|
page which allow to quickly switch between logbooks. Default is
|
|
<b><code>1</code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Main Tab = <string></code></b><br>
|
|
If this option is present, an additional first tab is displayed which
|
|
takes you back to the main logbook selection page. The
|
|
<b><code>string</code></b> is used for the contents of the tab.
|
|
</li>
|
|
<li>
|
|
<b><code>Main Tab URL = <string></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Welcome Title = <html code></code></b><br>
|
|
This optional HTML code gets displayed in the title of the logbook
|
|
selection page. It can contain images via <b><code><img
|
|
src="welcome.gif"></code></b>. These images must be stored in the
|
|
resource directory or in the theme directory.<br>
|
|
<br>
|
|
The following line is an example Welcome Title:<br>
|
|
<br>
|
|
<pre>
|
|
Welcome title = <img src="welcome.jpg"><p><font size=5 color=white>Welcome to our Elog</font>
|
|
</pre>
|
|
<br>
|
|
This displays an image and a text below.
|
|
</li>
|
|
<li>
|
|
<b><code>Page title = <string></code></b><br>
|
|
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 <b><code>Page title</code></b> in the
|
|
<b><code>[global]</code></b> section is used for the logbook selection
|
|
page.
|
|
</li>
|
|
<li>
|
|
<b><code>List page title = <string></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Selection page = <file></code></b><br>
|
|
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 <b><code>"/"</code></b> (Unix) or <b><code>"\"</code></b>
|
|
or <b><code>"x:"</code></b> (Windows).<br>
|
|
<br>
|
|
It can be completely customized in order to contain logos etc. As a
|
|
template, the standard selection page produced by
|
|
<code><b>elogd</b></code> can be used.
|
|
</li>
|
|
<li>
|
|
<b><code>Guest Selection page = <file></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Protect Selection page = 0 | 1</code></b><br>
|
|
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 <b><code>1</code></b>. Default is <b><code>0</code></b>.
|
|
It is necessary to put the <code><b>Password file = ...</b></code> into
|
|
the <i>[global]</i> section of the config file for this to work.
|
|
</li>
|
|
<li>
|
|
<b><code>Expand Selection page = 0 | 1</code></b><br>
|
|
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 <b><code>1</code></b>.
|
|
</li>
|
|
<li>
|
|
<b><code>SMTP host = <host.domain></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>SMTP username = <username></code></b><br>
|
|
Some SMTP server require username/passowrd authentication. This option
|
|
specifies the SMTP user name, while the option <code><b>SMTP
|
|
password</b></code> can be created or modified via the
|
|
<code><b>-t</b></code> switch when starting elogd. This is necessary
|
|
since the password is encrypted. To set your SMPT password, enter on
|
|
the command line:
|
|
<pre>
|
|
elogd -t <your password>
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>SMTP port = <port></code></b><br>
|
|
This defines the port under which the SMTP server is listening. The
|
|
default is 25, but some newer servers use port 587.
|
|
</li>
|
|
<li>
|
|
<b><code>Logfile = <file></code></b><br>
|
|
This option specifies a filename which logs all login/logout activities
|
|
and successful user connections for logbooks with user level access.
|
|
The the <code><b>logging level</b></code> (see below) is larger than 1,
|
|
also read and write accesses can be logged.
|
|
</li>
|
|
<li>
|
|
<b><code>Logging level = 1 | 2 | 3</code></b><br>
|
|
Specifies the logging level. The higher this value, the more
|
|
information is logged. Default is <b>2</b>:
|
|
<ul>
|
|
<li>
|
|
<b>1:</b> Log only logins and logouts
|
|
</li>
|
|
<li>
|
|
<b>2:</b> Log also write accesses
|
|
</li>
|
|
<li>
|
|
<b>3:</b> Log also read accesses
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<b><code>URL =
|
|
<http[s]://host.domain[:port]/[subdir/]></code></b><br>
|
|
If one of the three cases is true:
|
|
<ul>
|
|
<li>
|
|
<code><b>elogd</b></code> runs with <i>SSL</i> enabled
|
|
</li>
|
|
<li>
|
|
<code><b>elogd</b></code> runs under a proxy
|
|
</li>
|
|
<li>The automatic email notifications contains the wrong URL
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
then the URL under which <code><b>elogd</b></code> 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<br>
|
|
<br>
|
|
</p>
|
|
<table border="0" cellpadding="10">
|
|
<tr>
|
|
<td>
|
|
<code>URL = http://host.domain:8080/</code>
|
|
</td>
|
|
<td>
|
|
if running on port 8080
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>URL = https://host.domain/</code>
|
|
</td>
|
|
<td>
|
|
if SSL is enabled (SSL = 1)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<code>URL = http://host.domain/subdir/</code>
|
|
</td>
|
|
<td>
|
|
if running under a proxy
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
This URL is then used for any redirection. For example if one submits a
|
|
new entry, the URL in the browser reads
|
|
<b>...<logbook>/?cmd=Submit&...</b>, containing all the attributes
|
|
etc. After the submit this page gets redirected to
|
|
<b>...<logbook>/<ID></b>, 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.
|
|
<li>
|
|
<b><code>Relative redirection = 0|1</code></b><br>
|
|
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 <b>http://</b>, and the
|
|
other with <b>https://</b>. Another case is when the elogd server has
|
|
a dynamic IP address, which changes from time to time. Setting
|
|
<b><code>Relative redirection = 1</code></b>,
|
|
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.
|
|
</li>
|
|
</li>
|
|
<li>
|
|
<b><code>Usr = <name></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Grp = <name></code></b><br>
|
|
The user and group to run the elogd daemon under when started by root.
|
|
</li>
|
|
<li>
|
|
<b><code>Resolve host names = 0|1</code></b><br>
|
|
Resolve remote host names if set to <b>1</b>. If set to <b>0</b>, which
|
|
is the default, only IP numbers are stored in any log file. If the
|
|
<b><code>hosts allow/deny</code></b> options are used with host names,
|
|
this setting must be set to <b>1</b>. 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.
|
|
</li>
|
|
</ul>
|
|
<hr>
|
|
<a name="groups" id="groups"></a>
|
|
<hr>
|
|
<div class="section">
|
|
Groups of logbooks
|
|
</div>
|
|
<p>
|
|
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
|
|
</p>
|
|
<p>
|
|
<code><b>Group <group name> = <Logbook1>, <Logbook2>,
|
|
<other group></b></code>
|
|
</p>
|
|
<p>
|
|
in the <b><code>[global]</code></b> section of the configuration file.
|
|
</p>
|
|
<p>
|
|
To define following logbook hierarchy:
|
|
</p>
|
|
<p>
|
|
<img src="hierarchy.gif">
|
|
</p>
|
|
<p>
|
|
one would use following statements:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
[global]
|
|
Group Linux PCs = Red Hat, Debian, Mandrake
|
|
Group Windows PCs = 98, ME, NT, XP, CE
|
|
Group CE = 1.0, 2.0
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
The logbook tabs would then look like this:
|
|
<p>
|
|
<img src="tabs.gif">
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<hr>
|
|
<div class="section">
|
|
Top groups
|
|
</div>
|
|
<p>
|
|
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 <code><b>Top
|
|
groups</b></code>. The configuration could look like this:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
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
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
Note that there can be a <b><code>[global]</code></b> 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 <b><code>[global
|
|
<top group>]</code></b> setting, which by itsel overrides a setting
|
|
in the <b><code>[global]</code></b> section. This way one can define
|
|
settings for all top level groups (such as the SMTP host) in the
|
|
<b><code>[global]</code></b> section, and define different password files
|
|
and administrators in the individual top level group sections.<br>
|
|
<br>
|
|
If top groups are used, the root of the elogd server is not accessible any
|
|
more. Presume that elogd is accessible normally under
|
|
<b><code>http://your.host:8080/</code></b>, 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 <b><code>http://your.host:8080/engineering</code></b> or
|
|
<b><code>http://your.host:8080/administration</code></b>. 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 <code><b>Show top groups =
|
|
1</b></code>.
|
|
<hr>
|
|
<div class="title">
|
|
Individual logbook options
|
|
</div>
|
|
<p>
|
|
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 <code><b>[global]</b></code> section. Thus if the following
|
|
options are placed in the <code><b>[global]</b></code> section, they are
|
|
defaults for all logbooks. If they are present in the
|
|
<code><b>[global]</b></code> and in the logbook section, the logbook
|
|
option is used.
|
|
</p>
|
|
<p>
|
|
Here are the available options, by broad categories:
|
|
</p>
|
|
<p>
|
|
<a name="general" id="general"></a>
|
|
</p>
|
|
<hr>
|
|
<div class="section">
|
|
General options
|
|
</div>
|
|
<ul>
|
|
<li>
|
|
<b><code>Data dir = <directory></code></b><br>
|
|
This option is obsolete from version 2.2.5 on and should not be used.
|
|
Use <code><b>Subdir = ...</b></code> instead.
|
|
</li>
|
|
<li>
|
|
<b><code>Subdir = <directory></code></b><br>
|
|
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 <code><b>elogd</b></code>
|
|
program. The subdirectory is relative to the logbook root directory
|
|
specified with the <b><code>Logbook dir = ...</code></b> option. So if
|
|
<code><b>Logbook dir = /usr/local/elog/logbooks</b></code> and
|
|
<code><b>Subdir = Demo</b></code> then the logbook data is stored in
|
|
<code><b>/user/local/elog/logbooks/Demo</b></code>. If the
|
|
<b><code>Logbook dir = ...</code></b> option is not specified, then
|
|
<b><code>logbooks</code></b> 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 <code><b>elogd</b></code> with the "-v" flag.
|
|
</li>
|
|
<li>
|
|
<b><code>Comment = <comment></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Theme = <theme></code></b><br>
|
|
A theme determines which layout and colors are used for a logbook,
|
|
similar to <i>skins</i> in other programs. The <i>theme</i> option
|
|
points to a subdirectory under the <i>"themes"</i> directory which
|
|
resides in the resource directory. It contains all files for that
|
|
theme. The format of these files is described under the <i>Themes</i>
|
|
section.
|
|
</li>
|
|
<li>
|
|
<b><code>CSS = <filename></code></b><br>
|
|
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 <i>elog.css</i> is used. This
|
|
statement adds an additional CSS, which can overwrite settings from
|
|
<i>elog.css</i>. If different CSS'es should be used
|
|
for different output media, this can be accomplished with a comma-
|
|
separated list in the form
|
|
<code><b>CSS = <file1>&<media1>,<file2>&<media2></b></code>. This will then be
|
|
translated into separate style sheet
|
|
statements for the different media. For example a statement
|
|
|
|
<code><b>CSS = default.css&screen,print.css&print</b></code>
|
|
|
|
will result in the HTML statements:
|
|
|
|
<pre>
|
|
<link rel="stylesheet" type="text/css" href="default.css" media="screen">
|
|
<link rel="stylesheet" type="text/css" href="print.css" media="print">
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>Title image = <string></code></b><br>
|
|
HTML code for the icon in the upper right corner. By default, following
|
|
code is used:
|
|
<p>
|
|
<img border=0 src="elog.gif" alt="ELOG logo">
|
|
</p>
|
|
<p>
|
|
This code can be replaced by <b><code><string></code></b> 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
|
|
<b><code><elog root>/themes/default</code></b>.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<b><code>Title image URL = <URL></code></b><br>
|
|
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
|
|
<b><code>elog.gif</code></b> icon in the theme directory. This option
|
|
should only be used if the <b><code>Title image</code></b> option is
|
|
not used.
|
|
</li>
|
|
<li>
|
|
<b><code>Time format = <string></code></b><br>
|
|
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
|
|
<a href="strftime.txt">strftime</a>, so a string of <b>%A, %B %d, %Y,
|
|
%H:%M</b> yields in a display of <b>Thursday, November 15, 2001,
|
|
12:35</b> for example.
|
|
</li>
|
|
<li>
|
|
<b><code>Time format <attribute> = <string></code></b><br>
|
|
Same, but just for an individual attribute.
|
|
</li>
|
|
<li>
|
|
<b><code>Date format = <string></code></b><br>
|
|
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 <a href="strftime.txt">strftime</a>, so a string of <b>%A, %B %d,
|
|
%Y</b> yields in a display of <b>Thursday, November 15, 2001</b> for
|
|
example.
|
|
</li>
|
|
<li>
|
|
<b><code>Date format <attribute> = <string></code></b><br>
|
|
Same, but just for an individual attribute.
|
|
</li>
|
|
<li>
|
|
<b><code>Welcome Page = <file></code></b><br>
|
|
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:
|
|
<pre>
|
|
<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>
|
|
</pre>
|
|
The file must be present in the resource directory. Alternatively, an
|
|
absolute path can be used if the file name starts with a
|
|
<b><code>"/"</code></b> (Unix) or <b><code>"\"</code></b> or
|
|
<b><code>"x:"</code></b> (Windows).
|
|
</li>
|
|
<li>
|
|
<b><code>Start page = <command></code></b><br>
|
|
This option can be used to display a different start page.
|
|
<b><code>command</code></b> can be either <i>0?cmd=Last</i> to display
|
|
the last message, or any other ELog menu command in the form
|
|
<b><code>?cmd=xxx</code></b>. To start with the search page, one uses
|
|
<pre>
|
|
Start page = ?cmd=Find
|
|
</pre>
|
|
Please note that if another language than English is selected via the <b>
|
|
Language = xxx</b> option, the commands have to be in that language as
|
|
well (like <i>"Start page = 0?cmd=Letzter"</i> for German).
|
|
</li>
|
|
<li>
|
|
<b><code>Submit Page = <file></code></b><br>
|
|
This optional page can be displayed when a new message was submitted in
|
|
a logbook. Here is an example:
|
|
<pre>
|
|
<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
|
|
</pre>
|
|
The file must be present in the logbook directory. Alternatively, an
|
|
absolute path can be used if the file name starts with a
|
|
<b><code>"/"</code></b> (Unix) or <b><code>"\"</code></b> or
|
|
<b><code>"x:"</code></b> (Windows).
|
|
</li>
|
|
<li>
|
|
<b><code>Message comment = <comment></code></b><br>
|
|
This optional comment is displayed on top of the text entry field when
|
|
submitting a new message. It can contain a sentence like "<i>Please
|
|
enter your message here</i>:".
|
|
</li>
|
|
<li>
|
|
<b><code>Reply comment = <comment></code></b><br>
|
|
This optional comment is displayed on top of the text entry field when
|
|
replying to an exiting entry. It can contain a sentence like "<i>Please
|
|
enter your reply here</i>:".
|
|
</li>
|
|
<li>
|
|
<b><code>Attachment comment = <comment></code></b><br>
|
|
This optional comment is displayed on top of the attachment sumbission
|
|
section when entering a new message. It can contain a sentence like
|
|
"<i>Please upload your attachments here</i>:".
|
|
</li>
|
|
<li>
|
|
<b><code>Menu commands = <list></code></b><br>
|
|
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:
|
|
<ul>
|
|
<li>
|
|
<b>New</b> - Enter new logbook entry
|
|
</li>
|
|
<li>
|
|
<b>Edit</b> - Edit current logbook entry
|
|
</li>
|
|
<li>
|
|
<b>Delete</b> - Delete current logbook entry
|
|
</li>
|
|
<li>
|
|
<b>Reply</b> - Submit a reply to current entry
|
|
</li>
|
|
<li>
|
|
<b>Duplicate</b> - Duplicate the current entry with the possibility
|
|
to change some values
|
|
</li>
|
|
<li>
|
|
<b>Download</b> - Download a message in ASCII format
|
|
</li>
|
|
<li>
|
|
<b>Find</b> - Search entries in logbooks
|
|
</li>
|
|
<li>
|
|
<b>Last day</b> - Display entries from last day
|
|
</li>
|
|
<li>
|
|
<b>Move to</b> - Move entry to other logbook
|
|
</li>
|
|
<li>
|
|
<b>Copy to</b> - Copy entry to other logbook
|
|
</li>
|
|
<li>
|
|
<b>Config</b> - Edit elogd.cfg (if <b>no</b> "<i>Password file</i>"
|
|
is given)
|
|
</li>
|
|
<li>
|
|
<b>Config</b> - Modify/Add user accounts (if "<i>Password file</i>"
|
|
is given)
|
|
</li>
|
|
<li>
|
|
<b>Admin</b> - Edit elogd.cfg (if "<i>Password file</i>" is given)
|
|
</li>
|
|
<li>
|
|
<b>Login</b> - Login with user name and password (if "<i>Password
|
|
file</i>" is given)
|
|
</li>
|
|
<li>
|
|
<b>Import</b> - Show CSV (comma-separated-values) import page
|
|
</li>
|
|
<li>
|
|
<b>Logout</b> - Logout current user (if "<i>Password file</i>" is
|
|
given)
|
|
</li>
|
|
<li>
|
|
<b>Help</b> - General help
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
<br>
|
|
The commands are always in English, independent of the
|
|
<code><b>language = ...</b></code> setting, and are automatically
|
|
translated into the specified language.<br>
|
|
<br>
|
|
If this option is not present, following default is used:<br>
|
|
<pre>
|
|
Menu commands = List, New, Edit, Delete, Reply, Duplicate, Find, Config, Help
|
|
</pre>
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Copy to = <logbook list></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Move to = <logbook list></code></b><br>
|
|
The commands <code><b>Copy to</b></code> and <code><b>Move
|
|
to</b></code> 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
|
|
<b><code>Copy to = <logbook list></code></b> and <b><code>Move to
|
|
= <logbook list></code></b> 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 <code><b>Preserve IDs</b></code>
|
|
can be used to keep the entry ID in the destination logbook.
|
|
</li>
|
|
<li>
|
|
<b><code>List Menu commands = <list></code></b><br>
|
|
This option specifies the menu commands displayed on top of the listing
|
|
page. Although all commands from a above are possible, only the
|
|
commands <code><b>New, Find, Select, Import, Config, Admin, Change
|
|
password, Logout</b></code> and <code><b>Help</b></code> make sense.
|
|
The command <code><b>Select</b></code> can be used to select multiple
|
|
messages for deletion or for moving to other logbooks. Once the
|
|
<code><b>Select</b></code> 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 <code><b>Delete</b></code> and optionally
|
|
a <code><b>Coyp to ...</b></code> and <code><b>Move to ...</b></code>
|
|
button, if these commands are present in the <code><b>Menu
|
|
commands</b></code> list. Pressing one of these buttons deletes, copies
|
|
or moves all selected logbook entries.
|
|
</li>
|
|
<li>
|
|
<b><code>Guest Menu commands = <list></code></b><br>
|
|
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 <b>login</b>
|
|
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 <b>"Menu commands"</b>
|
|
list. A typical example for the menu settings for this scenario are:
|
|
<pre>
|
|
Menu commands = List, New, Edit, Reply, Duplicate, Find, Config, Logout, Help
|
|
Guest menu commands = List, Find, Login, Help
|
|
</pre>
|
|
<p>
|
|
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 <code><b>Guest menu
|
|
commands</b></code> option with the following <code><b>Guest List
|
|
Menu commands</b></code> option to restrict the access to the find
|
|
result page as well.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<b><code>Guest List Menu commands = <list></code></b><br>
|
|
Same as <b>Guest Menu commands</b> but for the find result page.
|
|
</li>
|
|
<li>
|
|
<b><code>Menu text = <file></code></b><br>
|
|
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 <i>Routine</i> entry
|
|
and all <i>Routine</i> entries:<br>
|
|
<pre>
|
|
<small>
|
|
&nbsp;<a href="?cmd=next&type=Routine">Next Routine entry</a>&nbsp;|
|
|
&nbsp;<a href="../?Type=Routine">All Routine entries</a>
|
|
</small>
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>List Menu text = <file></code></b><br>
|
|
The same for the list page. One example would be following text to
|
|
switch between the different display modi:<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Filter Menu text = <file></code></b><br>
|
|
The same for the filter line in the list page.<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Guest Display = <list></code></b><br>
|
|
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 <code><b>list</b></code> consists of comma
|
|
separated attributes, including the word <i>text</i>, if one wants to
|
|
display the entry body text for guests.
|
|
<pre>
|
|
<small>
|
|
&nbsp;<a href="?mode=summary">Summary</a>&nbsp;|
|
|
&nbsp;<a href="?mode=full">Full</a>&nbsp;|
|
|
&nbsp;<a href="?mode=threaded">Threaded</a>&nbsp;|
|
|
</small>
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<code><b>Top text = <file> | <string></b></code><br>
|
|
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 <b><code>"/"</code></b> (Unix) or <b><code>"\"</code></b> or
|
|
<b><code>"x:"</code></b> (Windows).
|
|
</li>
|
|
<li>
|
|
<b><code>Bottom text = <file> | <string></code></b><br>
|
|
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:
|
|
<pre>
|
|
<center><a href="/">Main page</a></center>
|
|
</pre>
|
|
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 <b><code>"/"</code></b> (Unix) or <b><code>
|
|
"\"</code></b> or <b><code>"x:"</code></b> (Windows).
|
|
</li>
|
|
<li>
|
|
<b><code>Bottom text login = <file> | <string></code></b><br>
|
|
The same as <b><code>Bottom text</code></b> 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.
|
|
</li>
|
|
<li>
|
|
<b><code>Help URL = <URL></code></b><br>
|
|
This URL is used for the Help button. By default, the file
|
|
<b>eloghelp_xx.html</b> is returned with the contents of the help page.
|
|
Edit this file directly to add site-specific help for all logbooks.
|
|
Alternatively, use the <b><code>Help URL</code></b> option to specify
|
|
different help pages for different logbooks. It can point to a
|
|
site-specific help page via <b><code>http://...</code></b> or to a
|
|
local file like <b><code>file://c:/tmp/config.html</code></b>, or to
|
|
the name of an HTML file which must be present in the resource
|
|
directory.
|
|
</li>
|
|
<li>
|
|
<b><code>Message Width = <number></code></b><br>
|
|
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 <code><b>Message Width</b></code>
|
|
and <code><b>Message Height</b></code> are not given, some JavaScript
|
|
code is used which automatically resizes the message window
|
|
dynamically to fit optimally into the browser window.
|
|
</li>
|
|
<li>
|
|
<b><code>Message Height = <number></code></b><br>
|
|
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 <code><b>Message Width</b></code>
|
|
and <code><b>Message Height</b></code> are not given, some JavaScript
|
|
code is used which automatically resizes the message window
|
|
dynamically to fit optimally into the browser window.
|
|
</li>
|
|
<li>
|
|
<b><code>Admin textarea = <cols>,<rows></code></b><br>
|
|
This defines the textarea size for the admin page. Default is
|
|
<b>80,40</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Display mode = [full|summary|threaded]</code></b><br>
|
|
Default mode for search display. On the find entry form, the checkboxes
|
|
are set accordingly. The "Last xxx" page uses this setting directly.
|
|
</li>
|
|
<li>
|
|
<b><code>Entries per page = <number></code></b><br>
|
|
Number of logbook entries displayed per page in a search result. The
|
|
default is 20.
|
|
</li>
|
|
<li>
|
|
<b><code>Restrict edit time = <hours></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Admin restrict edit time = <hours></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Max content length = <bytes></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Fonts = <list></code></b><br>
|
|
List of fonts (comma separated) to be shown in the font drop-down box
|
|
of the entry edit form. Default is<br>
|
|
<br>
|
|
<code>Fonts = Arial, Comic Sans MS, Courier New, Tahoma, Times New
|
|
Roman, Verdana</code><br>
|
|
<br>
|
|
On Unix systems some of these fonts might not be installed, in which
|
|
case they can be replaced by others like <b>Serif</b>,
|
|
<b>Sans-serif</b>, <b>Helvetica</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>All display limit = <n></code></b><br>
|
|
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 <b><code>500</code></b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Thumbnail size = <size></code></b><br>
|
|
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 <a href="adminguilde.html#imagemagick">
|
|
admin guide</a> for installation instructions. The thumbnail size
|
|
<b><code>size</code></b> gets passed to the <b><code>-thumbnail</code></b>
|
|
option of the conversion. A value of <b><code>300</code></b> converts
|
|
all pictures to thumbnails 300 pixels wide. A value of
|
|
<b><code>300></code></b> 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 <b><code>10%</code></b>
|
|
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:<p>
|
|
|
|
<img src="thumbnail.png">
|
|
<p>
|
|
|
|
Setting <b><code>Thumbnail size = 0</code></b> turns off the thumbnail
|
|
creation.
|
|
<p>
|
|
</li>
|
|
<li>
|
|
<b><code>Thumbnail options = <options></code></b><br>
|
|
With this option one can pass additional parameters to the ImageMagick
|
|
package. They are passes 1:1 to the <b>convert</b> program. Commonly
|
|
used is the <b>-density</b> option to increase the image quality when
|
|
converting from PDF or EPS files.<p>
|
|
</li>
|
|
</ul>
|
|
<a name="attrib" id="attrib"></a>
|
|
<hr>
|
|
<div class="section">
|
|
Attributes
|
|
</div>
|
|
<ul>
|
|
<li>
|
|
<b><code>Attributes = <list></code></b><br>
|
|
Define a number of attributes for the logbook, separated by commata. A
|
|
maximum of 100 attributes can be defined. Typical values are
|
|
"<i>Author</i>", "<i>Subject</i>" or "<i>Type</i>". Following values
|
|
are not allowed:<p>
|
|
<ul>
|
|
<li>Text
|
|
<li>Date
|
|
<li>Encoding
|
|
<li>Reply to
|
|
<li>In reply to
|
|
<li>Locked by
|
|
<li>Attachment
|
|
<li>Path
|
|
</ul>
|
|
<p>
|
|
since these are used internally by elog.
|
|
</li>
|
|
<li>
|
|
<b><code>Options <attribute> = <list></code></b><br>
|
|
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
|
|
<pre>
|
|
Options town = San Francisco, "Paris, Texas", "Paris, France"
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>Extendable options = <list></code></b><br>
|
|
When using the <code><b>Options <attribute></b></code> 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 <code><b>Extandable options</b></code> 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.
|
|
</li>
|
|
<li>
|
|
<b><code>ROptions <attribute> = <list></code></b><br>
|
|
Same as <code><b>Options</b></code> above, but using radio buttons
|
|
instead of a drop-down box.
|
|
</li>
|
|
<li>
|
|
<b><code>MOptions <attribute> = <list></code></b><br>
|
|
This list allows for "<i>Multiple Options</i>", 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
|
|
<pre>
|
|
<value1> | <value2> | ...
|
|
</pre>
|
|
In the "<i>find</i>" page only one of these values can be specified,
|
|
which is then treated as a substring in the search filter.
|
|
</li>
|
|
<li>
|
|
<b><code>IOptions <attribute> = <list></code></b><br>
|
|
This list specifies a set of icons for an attribute. Some icons are
|
|
contained in the <i>themes/default/icons</i> directory which can be
|
|
used here like
|
|
<pre>
|
|
Attributes = Author, Icon, Subject...
|
|
IOptions Icon = icon1.gif, icon2.gif, icon3.gif, ...
|
|
</pre>
|
|
New icons are welcome and should be sent back to the author to be
|
|
incorporated in the next version.
|
|
</li>
|
|
<li>
|
|
<b><code>Comment <attribute> = <comment></code></b><br>
|
|
Optional comment which is displayed below the attribute name in the
|
|
entry form. Can be used to explain the attribute somehow.
|
|
</li>
|
|
<li>
|
|
<b><code>Tooltip <attribute> = <comment></code></b><br>
|
|
Same as <code><b>Comment <attribute></b></code>, 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.
|
|
</li>
|
|
<li>
|
|
<b><code>Tooltip <attribute> <attribute option> = <comment></code></b><br>
|
|
Same as <code><b>Tooltip <attribute></b></code>, but for option
|
|
values of a <code><b>MOptions</b></code> 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 <b>not</b> be enclosed with quotes.
|
|
</li>
|
|
<li>
|
|
<b><code>Icon comment <icon> = <comment></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Options <attribute> = boolean</code></b><br>
|
|
If an attribute is marked "<i>boolean</i>" this way, a checkbox is
|
|
displayed for this attribute.
|
|
</li>
|
|
<li>
|
|
<b><code>Preset <attribute> = <string></code></b><br>
|
|
This option uses a preset string for an attribute. The string can
|
|
contain subsitutions like the ones described under the "<i>Subst
|
|
<attribute></i>" command. One possible application is to use the
|
|
login name for the author field like:
|
|
<pre>
|
|
Preset Author = $long_name
|
|
</pre>
|
|
If the attribute should be locked at the Web submission, use the
|
|
"<i>Locked Attributes = ...</i>" 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.<br>
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Preset text = <string> or <file></code></b><br>
|
|
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
|
|
<b><code>"/"</code></b> (Unix) or <b><code>"\"</code></b> or
|
|
<b><code>"x:"</code></b> (Windows).
|
|
</li>
|
|
<li>
|
|
<b><code>Preset on edit <attribute> =
|
|
<string></code></b><br>
|
|
Same as <b><code>Preset <attribute></code></b>, but evaluated when
|
|
editing existing entries.
|
|
</li>
|
|
<li>
|
|
<b><code>Preset on reply <attribute> =
|
|
<string></code></b><br>
|
|
Same as <b><code>Preset <attribute></code></b>, but evaluated for
|
|
replies.
|
|
</li>
|
|
<li>
|
|
<b><code>Preset on first reply <attribute> =
|
|
<string></code></b><br>
|
|
While <b><code>Preset on reply <attribute></code></b>, 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:
|
|
<pre>
|
|
Preset on first reply Subject = Re: $Subject
|
|
</pre>
|
|
So the "Re:" only gets added once, and you don't get long chains of
|
|
"Re: Re: Re: ....".
|
|
</li>
|
|
<li>
|
|
<b><code>Preset on duplicate <attribute> =
|
|
<string></code></b><br>
|
|
Same as <b><code>Preset <attribute></code></b>, but evaluated for
|
|
duplicted entries.
|
|
</li>
|
|
<li>
|
|
<b><code>Locked Attributes = <list></code></b><br>
|
|
The attributes specified here cannot be modified when a new entry is
|
|
submitted. This makes only sense for preset attributes.
|
|
</li>
|
|
<li>
|
|
<b><code>Fixed Attributes Edit = <list></code></b><br>
|
|
The attributes specified here cannot be modified when an existing entry
|
|
is modified via the <b><code>Edit</code></b> button. This feature can
|
|
be useful to preserve the original author of the message, when using
|
|
the <b><code>Preset Author = $long_name</code></b> option as described
|
|
above.
|
|
</li>
|
|
<li>
|
|
<b><code>Fixed Attributes Reply = <list></code></b><br>
|
|
The attributes specified here cannot be modified when an existing entry
|
|
is replied on via the <b><code>Reply</code></b> button. This feature
|
|
can be useful to preserve the original subject of a message for
|
|
example.
|
|
</li>
|
|
<li>
|
|
<b><code>Required Attributes = <list></code></b><br>
|
|
The attributes specified here are required when a new entry is
|
|
submitted. The attribute names are marked with <font color=
|
|
"red">*</font> on the entry form.
|
|
</li>
|
|
<li>
|
|
<b><code>Show Attributes = <list></code></b><br>
|
|
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
|
|
<b><code>Change <attribute></code></b> command.
|
|
</li>
|
|
<li>
|
|
<b><code>Show Attributes Edit = <list></code></b><br>
|
|
The same as <b><code>Show Attributes</code></b>, but for the entry form.
|
|
</li>
|
|
<li>
|
|
<b><code>Propagate Attributes = <list></code></b><br>
|
|
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".
|
|
</li>
|
|
<li>
|
|
<b><code>Page title = <string></code></b><br>
|
|
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 "<i>Subst <attribute></i>"
|
|
option.
|
|
</li>
|
|
<li>
|
|
<b><code>Edit Page title = <string></code></b><br>
|
|
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 "<i>Subst
|
|
<attribute></i>" option.
|
|
</li>
|
|
<li>
|
|
<b><code>List display = <list></code></b><br>
|
|
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:<br>
|
|
<br>
|
|
<ul>
|
|
<li>
|
|
<b><code>ID</code></b> for the entry ID
|
|
</li>
|
|
<li>
|
|
<b><code>Date</code></b> for the entry date/time
|
|
</li>
|
|
<li>
|
|
<b><code>Edit</code></b> to display a column with an edit icon to
|
|
directly edit and entry
|
|
</li>
|
|
<li>
|
|
<b><code>Delete</code></b> to display a column with a delete icon
|
|
to directly delete and entry
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
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<br>
|
|
<pre>
|
|
List display = ID, Date, <all attributs>
|
|
</pre>
|
|
Which displays the message number, date, and all attributes. The display
|
|
of the message body is controlled by the <b><code>Display mode</code></b> and
|
|
<b><code>Summary lines</code></b> options. If a search goes over "all
|
|
logbooks", an additional colums with the logbook name of each entry is added in
|
|
front.
|
|
</li>
|
|
<li>
|
|
<b><code>Guest List display = <list></code></b><br>
|
|
Same as <code><b>List display</b></code>, but for guest access (user
|
|
level access with password, but not logged in). Please see also
|
|
<code><b>Guest display</b></code>. In addition to <code><b>List
|
|
display</b></code>, one can optionally specify <code><b>Text</b></code>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Link display = <list></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Thread display = <string></code></b><br>
|
|
Optional way to specify the line contents in the threaded search
|
|
result. Following substitutions are possible:
|
|
<ul>
|
|
<li>
|
|
<b>$<attribute></b>: The value of the attribute
|
|
</li>
|
|
<li>
|
|
<b>$logbook</b>: The name of the current logbook
|
|
</li>
|
|
<li>
|
|
<b>$entry time</b>: The message date and time, formatted via
|
|
"<i>Time format</i>"
|
|
</li>
|
|
<li>
|
|
<b>$message id</b>: The message ID
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
A typical example would be<br>
|
|
<pre>
|
|
Thread display = $subject, posted by $author on $entry time
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>Thread icon = <attribute></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>RSS Title = <string></code></b><br>
|
|
ELOG supports so-called <i>RSS feeds</i>. 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:
|
|
<ul>
|
|
<li>
|
|
<b>$<attribute></b>: The value of the attribute
|
|
</li>
|
|
<li>
|
|
<b>$logbook</b>: The name of the current logbook
|
|
</li>
|
|
<li>
|
|
<b>$entry time</b>: The message date and time, formatted via
|
|
"<i>Time format</i>"
|
|
</li>
|
|
<li>
|
|
<b>$message id</b>: The message ID
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
A typical example would be<br>
|
|
<pre>
|
|
RSS Title = $subject, posted by $author on $entry time
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>RSS Entries = <n></code></b><br>
|
|
Number of entries to be shown in the RSS feed. Default is 15.
|
|
</li>
|
|
<li>
|
|
<b><code>Subst <attribute> = <string></code></b><br>
|
|
When submitting logbook entries, attribute values can be substituted by
|
|
some text. This text can contain arbitrary fixed text and following
|
|
values:
|
|
<ul>
|
|
<li>
|
|
<b>$<attribute></b>: The entered value of the attribute
|
|
itself
|
|
</li>
|
|
<li>
|
|
<b>$host</b>: The host name where <code><b>elogd</b></code> is
|
|
running
|
|
</li>
|
|
<li>
|
|
<b>$remote_host</b>: The host name of the host from with the entry
|
|
was submitted
|
|
</li>
|
|
<li>
|
|
<b>$short_name</b>: The login name (if password file is present)
|
|
</li>
|
|
<li>
|
|
<b>$long_name</b>: The full name from the password file for the
|
|
current user
|
|
</li>
|
|
<li>
|
|
<b>$user_email</b>: The email address from the password file for
|
|
the current user
|
|
</li>
|
|
<li>
|
|
<b>$logbook</b>: The name of the current logbook
|
|
</li>
|
|
<li>
|
|
<b>$date</b>: The current date, formatted via "<i>Date format</i>"
|
|
</li>
|
|
<li>
|
|
<b>$utcdate</b>: The current UTC date (GMT) and time, formatted via
|
|
"<i>Date format</i>"
|
|
</li>
|
|
<li>
|
|
<b>$version</b>: The version of the ELOG server in the form x.y.z
|
|
</li>
|
|
<li>
|
|
<b>$revision</b>: The Subversion reversion of the ELOG server as an
|
|
integer number
|
|
</li>
|
|
<li>
|
|
<b>$shell(<command>)</b>: <command> gets passed to the
|
|
operating system shell and the result is taken for substitution.
|
|
</li>
|
|
</ul>
|
|
<br>
|
|
Following example use this feature to add the remote host name to the
|
|
author:<br>
|
|
<pre>
|
|
Subst Author = $author from $remote_host
|
|
</pre>
|
|
<br>
|
|
Following example substitutes an attribute with the contents of a
|
|
file:<br>
|
|
<pre>
|
|
Subst Info = $shell(cat /tmp/filename) (Unix)
|
|
Subst Info = $shell(type c:\tmp\filename) (Windows)
|
|
</pre>
|
|
<br>
|
|
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
|
|
<pre>
|
|
Subst Number = XYZ-#####
|
|
</pre>
|
|
results in automatically created attributes <i>"Number"</i> of the form
|
|
<pre>
|
|
XYZ-00001
|
|
XYZ-00002
|
|
XYZ-00003
|
|
</pre>
|
|
and so on. In addition to the #'s one may specify format specifiers which
|
|
are passed to the <a href="strftime.txt">
|
|
strftime</a> 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
|
|
<pre>
|
|
Subst Number = XYZ-%Y-%b-###
|
|
</pre>
|
|
results in automatically created attributes <i>"Number"</i> of the form
|
|
<pre>
|
|
XYZ-2005-Oct-001
|
|
XYZ-2005-Oct-002
|
|
XYZ-2005-Oct-003</pre>
|
|
<br>
|
|
and
|
|
<br>
|
|
<pre>
|
|
XYZ-2005-Nov-001
|
|
XYZ-2005-Nov-002</pre>
|
|
<br>
|
|
on the next month.
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Remove on reply = <list></code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Quote on reply = 0 | 1</code></b><br>
|
|
This flag controls if the original text is quoted in a reply. Default
|
|
is <b>1</b>
|
|
</li>
|
|
<li>
|
|
<b><code>Reply string = <string></code></b><br>
|
|
String used to mark original message lines. Default is <b><code>">
|
|
"</code></b>. Can be empty string ("") if no message marking is
|
|
desired.
|
|
</li>
|
|
<li>
|
|
<b><code>Subst on reply <attribute > =
|
|
<string></code></b><br>
|
|
Substitution of attributes for replies. This option can be used to
|
|
replace the current subject with a "Re: <old subject>":<br>
|
|
<pre>
|
|
Subst on reply subject = Re: $subject
|
|
</pre>
|
|
Note that this option works only for the first reply. So a
|
|
reply-to-a-reply would still have <b>Re: <old subject></b>
|
|
and not <b>Re: Re: <old subject></b>. If you want the substitution
|
|
for all replies, please use <code><b>Preset on reply</b></code> instead.
|
|
</li>
|
|
<li>
|
|
<b><code>Subst on edit <attribute > =
|
|
<string></code></b><br>
|
|
Substitution of attributes for edited messages. This option can be used
|
|
to replace the author by the current author for example:<br>
|
|
<pre>
|
|
Subst on edit author = $full_name
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>Quick filter = <list></code></b><br>
|
|
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 <b><code>Attributes
|
|
=</code></b> list, the attribute <b><code>Date</code></b> and the
|
|
option <b><code>Subtext</code></b> can be listed here. Using the
|
|
<b><code>Date</code></b> filter, the last day, week, month and so on
|
|
can be displayed. The <b><code>Subtext</code></b> filter works on the
|
|
entry body text.
|
|
</li>
|
|
|
|
<li>
|
|
<b><code>Last default = <n></code></b><br>
|
|
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 <code><b>Date</b></code> 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.
|
|
</li>
|
|
<li>
|
|
<b><code>Format <attribute> =
|
|
<flags>,<css_class_name>,<css_class_value>,<width>,<size></code></b><br>
|
|
|
|
Optional formatting parameters for attributes. Following items can be
|
|
defined in the comma-separated list:
|
|
<p>
|
|
Values used for single message display page:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><flags></b> Sum of following flags:
|
|
<ul>
|
|
<li>
|
|
<b>1</b>: Display attribute in same line as previous attribute
|
|
</li>
|
|
<li>
|
|
<b>2</b>: Display radio buttons or check boxes in separate
|
|
lines (if applicable)
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<b><css_class_name></b>,<b><css_class_value></b>
|
|
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
|
|
<i>themes/default/default.css</i>).
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Values used for new message entry form:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><width></b> Width of the text entry field in characters
|
|
</li>
|
|
<li>
|
|
<b><size></b> Maximum number of characters allowed.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Default is <i>"0, attribname, attribvalue, 80, 500"</i>. Trailing
|
|
parameters can be ommitted, so specifying for example only the flags
|
|
is possible.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<code><b>Type <attribute> = date | datetime | numeric |
|
|
userlist | useremail | muserlist | museremail</b></code><br>
|
|
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.<br>
|
|
<br>
|
|
Attributes of type <b><code>date</code></b> are treated as a date.
|
|
Their format for display can be controlled by the <b><code>Date
|
|
format</code></b> 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 <b><code>datetime</code></b> type combines a date and time in
|
|
HH:MM. The output of this combination is controlled by the
|
|
<b><code>Time format</code></b> option.<br>
|
|
<br>
|
|
If the attribute type is <b><code>userlist</code></b>, 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
|
|
<b><code>useremail</code></b> 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
|
|
<b><code>Email all = <attribute></code></b> statement. The type
|
|
<b><code>muserlist</code></b> and <b><code>museremail</code></b> are the
|
|
same that <b><code>userlist</code></b> and <b><code>useremail</code></b>,
|
|
except that several user names or user emails can be selected at once
|
|
using check boxes.
|
|
</li>
|
|
<li>
|
|
<b><code>Style <attribute> <value> = <style></code></b><br>
|
|
|
|
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 <code><b>importnace</b></code> and you want to highlight
|
|
all entries where <code><b>importnace</b></code> is <code><b>severe</b></code>
|
|
for example, you can specify following style:
|
|
<pre>
|
|
Style importance severe = background-color:red
|
|
</pre>
|
|
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.<br/>
|
|
<br/>
|
|
For empty attributes one can specify "", such as
|
|
<pre>
|
|
Style importance "" = background-color:red
|
|
</pre>
|
|
</li>
|
|
<li>
|
|
<b><code>Cell Style <attribute> <value> = <style></code></b><br>
|
|
|
|
Same as above, but only for a specific cell containing <attribute>.
|
|
Following options
|
|
<pre>
|
|
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
|
|
</pre>
|
|
for example produce following listing:<br>
|
|
<p><img border=0 src="cell_style.png"></p>
|
|
</li>
|
|
<li>
|
|
<code><b>Change <attribute> = <string></b></code><br>
|
|
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<br>
|
|
<br>
|
|
<pre>
|
|
http://any.company.com/telbook.cgi?search=<name>
|
|
</pre>
|
|
where <name> has to be replaced by a search string. Now one can
|
|
construct an automatic telephonebook lookup with following options:<br>
|
|
<pre>
|
|
Attributes = Name, Telephone, ...
|
|
Change Telephone = <a href="http://any.company.com/telbook.cgi?search=$Name">$Name's telephone number</a>
|
|
</pre>
|
|
The attribute <b><code>Telephone</code></b> is now automatically
|
|
constructed from the attribute <b><code>Name</code></b> 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 <b><code>Subst Telephone =
|
|
...</code></b> option) all entries would have to be changed manually.
|
|
</li>
|
|
<li>
|
|
<code><b>List Change <attribute> = <string></b></code><br>
|
|
Same option for the list display.
|
|
</li>
|
|
<li>
|
|
<code><b>Execute new | edit | delete = <command></b></code><br>
|
|
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 <b><code><command></code></b> can contain
|
|
substitutions similar to the <b><code>Subst</code></b> command. In
|
|
addition the list of all attachments can be referred to via
|
|
<b><code>$<attachments></code></b>. The text body of the entry
|
|
can be referred to with <b><code>$text</code></b>. 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:
|
|
<pre>
|
|
Execute new = echo "New message wiht ID $message id of type $type from $long_name on $remote_host" >> /tmp/elog.log
|
|
</pre>
|
|
<br>
|
|
It should be noted that this feature can impose a security problem. If
|
|
someone can edit the elogd.cfg through the <b><code>Config</code></b>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<code><b>Last submission = <string></b></code><br>
|
|
This option determines what gets displayed on the logbook selection
|
|
page in the <i>Last submission</i> colum. The default string is
|
|
<code><b>$entry time by $author</b></code>. If a logbook does not
|
|
contain an <code><b>author</b></code> attribute, another string can be
|
|
chosen.
|
|
</li>
|
|
<li>
|
|
<code><b>ID display = <string></b></code><br>
|
|
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
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
ID display = TAG-$message id
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
would display the entry ID as "TAG-1","TAG-2", ... and so on.
|
|
</li>
|
|
<li>
|
|
<b><code>Prepend on reply = <string></code></b><br>
|
|
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<br>
|
|
<br>
|
|
<b><code>Prepend on reply = Added $date by
|
|
$long_name\n\n</code></b><br>
|
|
<br>
|
|
where "\n" causes a line break.
|
|
</li>
|
|
<li>
|
|
<b><code>Append on reply = <string></code></b><br>
|
|
Same as before, but gets added after the previous entry.
|
|
</li>
|
|
<li>
|
|
<b><code>Prepend on edit = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Append on edit = <string></code></b><br>
|
|
Same as before, but for editing entries.
|
|
</li>
|
|
<li>
|
|
<b><code>Sort Attributes = <list></code></b><br>
|
|
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 <b>ID</b>,
|
|
<b>Date</b> and <b>logbook</b>, although <b>ID</b> makes only sense
|
|
together with other attributes, since it is sorted as the primary
|
|
key anyhow.
|
|
</li>
|
|
</ul>
|
|
<a name="conditional" id="conditional"></a>
|
|
<hr>
|
|
<div class="section">
|
|
Conditional attributes
|
|
</div>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
Attributes = PC Name, Operating System, Version
|
|
Options Operating System = Linux, Windows
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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
|
|
<i>conditional attributes</i>. Simply write following configuration:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
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
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
If you enter a new entry into that logbook, the drop-down list for
|
|
<code><b>Version</b></code> changes automatically depending on the
|
|
<code><b>Operating System</b></code>. 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.
|
|
</p>
|
|
<p>
|
|
The number {1} and {2} in the configuration file are called
|
|
<i>conditions</i>. Depending on these conditions, certain other lines can
|
|
be activated. So if the Operating System <i>Linux</i> is selected,
|
|
condition {1} is true, which selects the line starting with {1} to select
|
|
the options <i>2.2, 2.4, 2.6</i>.
|
|
</p>
|
|
<p>
|
|
This technique offers various other possibilities, since any
|
|
configuration option can be made conditional by adding a
|
|
<code><b>{<n>}</b></code> 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
|
|
<code><b>Preset text = ...</b></code> can be used to copy some
|
|
pre-defined forms into the message body, which can then be filled out.
|
|
Consider following example:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
Attributes = Author, Type
|
|
Options Type = Network check{1}, System check{2}
|
|
|
|
{1} Preset text = network.txt
|
|
{2} Preset text = system.txt
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
This causes two text files <i>network.txt</i> and <i>system.txt</i> to be
|
|
copied into the message body when a new entry is made. The file
|
|
<i>network.txt</i> could look like:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
Routers checked: [ ]
|
|
DHCP checked: [ ]
|
|
Comment: ...
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
Another use of conditional attributes is in conjunction with the option
|
|
<code><b>Message comment</b></code>. 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.
|
|
</p>
|
|
<p>
|
|
<b><code>Show Attributes Edit = <list></code></b><br>
|
|
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:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
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
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The above statements cause the atrribute <b><code>Version</code></b> to be
|
|
only visible when "Windows" is selected, and
|
|
<b><code>Distribution</code></b> to be only visible when "Linux" is
|
|
selected. If "Windows" is selected, the PC name is shown before the
|
|
version.
|
|
</p>
|
|
<h2>
|
|
Multiple conditions
|
|
</h2>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
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
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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 <i>"The PC has Linux or is in the Main Building"</i>. To specify a
|
|
AND between conditions, a "&" is used. The condition
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<pre>
|
|
{1&a} ...
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
specifies for example the condition "Linux AND Main Building". If
|
|
several lines with condition combinations are true, the upper one is used.
|
|
</p>
|
|
|
|
<h2>
|
|
Conditions in the list display
|
|
</h2>
|
|
|
|
<p>
|
|
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 <B><code>
|
|
list display</code></b> option. To enable the evaluation of conditional
|
|
attributes for the list display, on uses the option
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code><b>List conditions = 1</b></code><br>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<a name="access" id="access"></a>
|
|
<hr>
|
|
<div class="section">Access control</div>
|
|
<p>
|
|
<b>Note: Starting with version 2.9.0, the password level access using
|
|
the options <i>Read password</i>, <i>Write password</i> and
|
|
<i>Admin password</i> is not supported any more. Please use the user
|
|
level access as described below.</b>
|
|
</p>
|
|
|
|
<h2>
|
|
Password file
|
|
</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Following options can be used to control the behavior:
|
|
<ul>
|
|
<li>
|
|
<b><code>Password file = <file></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Login expiration = <hours></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Admin user = <user list></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Login user = <user list></code></b>
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
This file contains user names and passwords in XML format, such as
|
|
</p>
|
|
<ul>
|
|
<pre>
|
|
|
|
<?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>
|
|
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The passwords are encoded. New users can either be created by hitting
|
|
<b>Register as new user</b> on the login page if <b><code>Self register =
|
|
1</code></b> in the configuration file, or by the admin user in the
|
|
<b>Config</b> page by pressing <b>New user</b>. 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 <b>Config</b> command.
|
|
</p>
|
|
<p>
|
|
To start a new password file, follow these steps:
|
|
</p>
|
|
<ul>
|
|
<li>Specify a password file name with <code><b>Password file =
|
|
<file></b></code> in the configuration file
|
|
</li>
|
|
<li>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.
|
|
</li>
|
|
<li>Add <b><code>Admin user = <user></code></b> into the
|
|
configuration file, using your login name from above
|
|
</li>
|
|
<li>If you now enter the "Config" page, you can add other users
|
|
</li>
|
|
<li>Remove the self registration option if you like
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The presence of a password file requires all users to "<i>log in</i>"
|
|
using their name and password, except when a guest login is allowed via
|
|
the <b>"Guest menu commands"</b> 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 <i>Author</i> and the
|
|
<i>Email</i> attributes with the current user name and email:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<code>Attributes = Author, Email, ...</code>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li>
|
|
<code>Subst Author = $long_name from $remote_host<br>
|
|
Subst Email = $user_email</code>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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 "<i>Subst <attrib></i>" option.
|
|
</p>
|
|
<p>
|
|
The user name and password are stored as cookies on the user side. The
|
|
expiration is controlled by the <b><code>Remember me</code></b> 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 <code><b>Login expiration</b></code> 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 <code><b>Login expiration</b></code> option can be set to
|
|
zero, in which case the <b><code>Remember me</code></b> checkbox is not
|
|
displayed.
|
|
</p>
|
|
<p>
|
|
The <code><b>Admin user = <user list></b></code> is a list of one
|
|
or more user names, which have admin rights. They see a button
|
|
<b><code>Change elogd.cfg</code></b> on the config page by which they can
|
|
edit elogd.cfg through the web. They can also modify other users on the
|
|
<b><code>Config</code></b> page, change their passwords or remove them.
|
|
In addition, the admin user(s) can delete or edit entries from other
|
|
users if <code><b>Restrict edit = 1</b></code>.
|
|
</p>
|
|
<p>
|
|
The <code><b>Login user = <user list></b></code> 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 <b><code>Password file</code></b> is present
|
|
under the <code><b>[global]</b></code> 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 <b><code>Login user</code></b> 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.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Self register = 0|1|2|3|4</code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
With this option it is possible for new users to self-register an user
|
|
account. At the login page, a link is displayed <b>"Register as a new
|
|
user"</b> 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 <b>Config</b> menu command.
|
|
</p>
|
|
<p>
|
|
Setting this option to <b>0</b> disables self registration. With option
|
|
<b>1</b>, users can silently register, while setting it to <b>2</b>
|
|
causes elogd to send an email notification to the admin user(s). The
|
|
option <b>3</b> is used to <i>only</i> 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 <b>4</b>
|
|
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.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Allow password change = 0|1</code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Enables or disabled the ability for users to change their password. If
|
|
disabled, the <i>"Forgot password?</i> link in the login page is ommitted
|
|
as well. The admin user(s) can always change passwords.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Allow <command> = <user list></code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Commands can be restricted to certain login names (separated by commas).
|
|
For each command in the list defined with the "<i>Menu commands</i>"
|
|
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.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Deny <command> = <user list></code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Hosts allow = <list></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Hosts deny = <list></code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
These two settings can be used to restrict the access to the logbook to
|
|
certain computers. It is similar to the UNIX <i>hosts.allow</i> and
|
|
<i>hosts.deny</i> files. The list can consist of individual host names or
|
|
IP numbers, subnet masks like <code><b>123.213.</b></code> (note the
|
|
trailing '.') or <code><b>.mit.edu</b></code>, or the word
|
|
<b><code>All</code></b>. The following rules are applied:
|
|
</p>
|
|
<ul>
|
|
<li>Access will be granted when a host matches a pattern in "<i>hosts
|
|
allow</i>".
|
|
</li>
|
|
<li>Otherwise, access will be denied when a host matches a pattern in
|
|
"<i>hosts deny</i>".
|
|
</li>
|
|
<li>Otherwise, access will be granted.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
These rules are applied <i>before</i> any password is checked. To debug
|
|
problems, start <code><b>elogd</b></code> with the "-v" flag, in which
|
|
case the rule checking is printed on the screen.
|
|
</p>
|
|
<p>
|
|
The global option <code><b>Logfile = <filename></b></code> can be
|
|
specified to log all user login/logout activities plus all successful
|
|
user connections.
|
|
</p>
|
|
<p>
|
|
If any of the password statements are in the <b><code>[global]</code></b>
|
|
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.
|
|
</p>
|
|
|
|
<h2>
|
|
Kerberos authentication
|
|
</h2>
|
|
<p>
|
|
Starting from version 2.9.0, site authentication has been implemented
|
|
in elog using the <a href="http://web.mit.edu/kerberos/">Kerberos</a>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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 <code><B>HAVE_KRB5</B></code>> defined in the compilation process.
|
|
To configure elogd to use Kerberos, use following options:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Authentication = <method(s)></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Kerberos Realm = <realm></code></b>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
where <method(s)> can be <code><b>File</b></code> or
|
|
<code><b>Kerberos</b></code> or both such
|
|
as in <code><b>Kerberos, File</b></code>. If the authentication option contains
|
|
<b>Kerberos</b>, the user credentials are authenticated using the default
|
|
Kerberos Realm. This is typically obtained from the file
|
|
<b><code>c:\windows\krb5.ini</code></b> (Windows) or
|
|
<b><code>/etc/krb5.conf</code></b> (Linux). If another than the default
|
|
realm should be used, this can be overwritten with the <b><code>Kerberos
|
|
Realm</code></b> option.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
If both authentications <code><b>Kerberos, File</b></code> 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.
|
|
</p>
|
|
<p>
|
|
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).
|
|
</p>
|
|
<p>
|
|
Beside the Kerberos authentication, elogd version 3.0 and higher can be configured to accept a authentication done
|
|
by the webserver.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Authentication = Webserver</code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
You can also combine it with other authentication methods as shown for Kerberos.
|
|
</p>
|
|
<p>
|
|
Elogd is then accepting the username set in the Request-Header "X-Forwarded-User" as already logged in.<br/>
|
|
To make this work, you need to configure the webserver correctly, as describe in the adminguide.
|
|
</p>
|
|
|
|
|
|
<h2>
|
|
LDAP authentication
|
|
</h2>
|
|
<p>
|
|
LDAP (lightweight Directory Access Protocol) has been implemented by
|
|
vykozlov in a separate branch at <a href="https://github.com/vykozlov/elog-ldap">https://github.com/vykozlov/elog-ldap</a>.
|
|
The code has been merged into this distribution on
|
|
an as-is basis. Following info has copied from the link above:</p>
|
|
|
|
<p>
|
|
To use LDAP authentication, do the following:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Enable LDAP authentication in the <b><code>Makefile</code></b> by setting
|
|
<b><code>USE_LDAP = 1</code></b>
|
|
</li>
|
|
<li>
|
|
Change elogd.cf to contain LDAP authentication:
|
|
<ul>
|
|
<li><b><code>Authentication = LDAP</code></b></li>
|
|
<li><b><code>LDAP server = ldap://example.org:389</code></b></li>
|
|
<li><b><code>LDAP userbase = ou=People;dc=example,dc=org</code></b></li>
|
|
<li><b><code>LDAP login attribute = uid</code></b></li>
|
|
<li><b><code>LDAP register = 1</code></b></li>
|
|
</ul>
|
|
The <code><b>login attribute</b></code> is from the DN (distinguished name), e.g.
|
|
uid=user,ou=People,dc=example,dc=org. The <code><b>register</b></code> flag determines
|
|
if LDAP users are automatically stored in the local password file, which is
|
|
necessary for email notifications.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Please note that it is not possible to change a password in the LDAP database from within ELOG.
|
|
</p>
|
|
|
|
<h2>
|
|
PAM authentication
|
|
</h2>
|
|
<p>
|
|
PAM (Pluggable authentication modules) support has been implemented by Jan Christoph Terasa. To use PAM in elogd,
|
|
do the following:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Compile <b><code>elogd</code></b> with PAM support, by either setting <b><code>USE_PAM = 1</code></b> in the
|
|
<b><code>Makefile</code></b>, or by specifying it when invoking <b><code>make</code></b>. If you compile
|
|
via CMake, set USE_PAM via ccmake.
|
|
</li>
|
|
<li>
|
|
Enable PAM authentication in <b><code>elogd.cfg</code></b>:
|
|
<ul>
|
|
<li><b><code>Authentication = PAM</code></b></li>
|
|
<li><b><code>Password file = elogd.passwd</code></b></li>
|
|
<li><b><code>Self register = 3</code></b></li>
|
|
</ul>
|
|
The <b><code>Password file</code></b> 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 <b>not</b> store a hash of the user password.
|
|
Self registration has to be enabled (<b><code>Self register ≥ 1</code></b>) to use PAM authentication.
|
|
</li>
|
|
<li>
|
|
To be able to use PAM, the PAM module in <b><code>elogd</code></b> needs to be able to access the authentication
|
|
facilities on the system (e.g. be able to read <code>/etc/shadow</code>). This can be achieved by either running
|
|
<code><b>elogd</b></code> as <code>root</code>, or by specifying the appropriate SUID/GUID values for the
|
|
binary.</br>
|
|
<span style="color:red"><b>WARNING:</b></span> When running elogd as root, be careful when using the <code>-x</code> option
|
|
to enable execution of commands via <code>$shell</code>, since the commands will be executed using the access
|
|
rights of the user running <code>elogd</code>!</b>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Please note that it is not possible to change the PAM password within ELOG. Instead, please use the available methods
|
|
on the system
|
|
</p>
|
|
|
|
|
|
<p>
|
|
<a name="email" id="email"></a>
|
|
</p>
|
|
<hr>
|
|
<div class="section">
|
|
EMail notification
|
|
</div>
|
|
<ul>
|
|
<li>
|
|
<b><code>Email <attribute> <value> =
|
|
<list></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Use Email Subject = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Use Email Subject Edit = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Use Email From = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Default Email From = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Use Email Heading = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Use Email Heading Edit = <string></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Omit Email To = 0|1</code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Suppress Email to users = 0|1</code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Email attributes = <list></code></b>
|
|
</li>
|
|
<li>
|
|
<b><code>Use Email URL = <URL></code></b>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
To send email automatically when new entries are created in a logbook, a
|
|
<code><b>SMTP host =</b></code> entry must be present in the
|
|
<b><code>[global]</code></b> section of the configuration file. To submit
|
|
an email based on an attribute value, use the statement <code><b>Email
|
|
<attribute> <value> = <list></b></code>. Whenever an
|
|
entry is submitted where <b><code>attribute</code></b> is equal to
|
|
<b><code>value</code></b>, an email notification is sent to the email
|
|
addresses in <b><code>list</code></b>. Several mail addresses may be
|
|
supplied, separated by commas. The mail addresses can contain attributes
|
|
via the <b>"$"</b> substitution. If a logbook contains for example an
|
|
attribute <i>name</i> which contains email names, then one can put
|
|
<i>$name@domain</i> to form a valid email address.
|
|
</p>
|
|
<p>
|
|
Multiple <b><code>Email xxx</code></b> 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:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<code>Email type "Normal routine" = ...</code>
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The statement <b><code>Email All = <list></code></b> sends an email
|
|
notification independent of the type and category. The <code><b>Use Email
|
|
Subject = <string></b></code> statement specifies which text is
|
|
used as the email subject. The text can contain
|
|
<b><code>$<attribute></code></b> statements which are substituted
|
|
with the current value of that attribute. For a full list of possible
|
|
substitutions, see the "<i>Subst <attribute></i>" option. The
|
|
<b><code>Use Email Heading = <string></code></b> specifies the text
|
|
for the email heading line. Default is <i>"A new entry has been submitted
|
|
on [host]"</i>. The option <b><code>Use Email Heading Edit =
|
|
<string></code></b> works the same way for updated (edited)
|
|
entries.
|
|
</p>
|
|
<p>
|
|
The option <b><code>Use Email From = <string></code></b> is used
|
|
for the "<i>From:</i>" field in the email. Since more and more email
|
|
servers do not accept invalid <i>"From:"</i> addresses in order to reduce
|
|
spam mail, it might be important that a "real" email address is used in
|
|
the <i>"From:"</i> field. If <b><code>Use Email From</code></b> is
|
|
present, it is always used. If not, the email address of the currently
|
|
logged in user is used for the <i>"From:"</i> 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 <b><code>Default Email From</code></b>
|
|
is used for the "<i>From:</i>" field. Only if this option is not specified,
|
|
a generic address <i>ELOG@<hostname></i> is used, which might be
|
|
rejected by the SMTP server however.
|
|
</p>
|
|
<p>
|
|
If the flag <code><b>Omit Email To</b></code> is set to <b>1</b>, the
|
|
<i>To:</i> 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.
|
|
</p>
|
|
<p>
|
|
The flag <code><b>Suppress Email to users</b></code> can be set to
|
|
<b>"1"</b> if email should only be sent to the recipients of the
|
|
<b><code>Email <attribute> <value> = <list></code></b>
|
|
statements but not to the users who have registerd for automatic email
|
|
notification.
|
|
</p>
|
|
<p>
|
|
If one wants to send only some attributes but not all in an email
|
|
notification, one can use the option <b><code>Email attributes =
|
|
<list></code></b>, where a subset of the attributes can be
|
|
specified as well as their order. <a name="flags" id="flags"></a>
|
|
</p>
|
|
|
|
<p>
|
|
The option <code><b>Use Email URL = <URL></b></code> can be used to
|
|
set the URL of the ELOG logbook used in email notifications. This can be
|
|
useful if no <b><code>URL = ...</code></b> statement is used form some
|
|
reason.
|
|
</p>
|
|
|
|
<hr>
|
|
<div class="section">
|
|
Flags
|
|
</div>
|
|
<ul>
|
|
<li>
|
|
<b><code>Show text = 0|1</code></b><br>
|
|
This flag controls if logbook entries contain a body text. If an
|
|
installation only requires attributes, this flag can be set to
|
|
<b>0</b>. Default is <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Enable attachments = 0|1</code></b><br>
|
|
This flag controls the attachment submission at the bottom of a message
|
|
entry page. If this flag is <b>0</b>, the attachment section is not
|
|
displayed. This might be useful for logbooks where attachments are not
|
|
used. Default is <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Show attachments = 0|1</code></b><br>
|
|
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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Preview attachments = 0|1</code></b><br>
|
|
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 <b>1</b>.
|
|
Only ASCII files and images are shown of course. Default is <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Summary lines = x</code></b><br>
|
|
This specifies the number of text lines displayed in a summary page.
|
|
Zero displays no text at all. The default is 3.
|
|
</li>
|
|
<li>
|
|
<b><code>Summary line length = x</code></b><br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Attachment lines = x</code></b><br>
|
|
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 <b>300</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Reverse sort = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, all listing pages (the default page view, the
|
|
result of a search query and the result of the <i>"Last day"</i> query)
|
|
is sorted in reverse order (newest entry down to oldest). The checkbox
|
|
<i>Sort in reverse order</i> 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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Search all logbooks = 0|1|2</code></b><br>
|
|
If this flag is <b>1</b> or <b>2</b>, the search form displays the button
|
|
<i>"Search all logbooks"</i>. If the flag is <b>2</b>, the button
|
|
is checked by default. Setting this flag to <b>0</b> 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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Enable browsing = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, browsing (hitting the next/previous button)
|
|
is enabled. For some rare occasions it might be necessary to disable
|
|
browsing. Default is <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Filtered browsing = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, 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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Default encoding = 0|1|2</code></b><br>
|
|
This specifies the default encoding for new entries. For installations
|
|
where entries are normally submitted as plain text, the default can be
|
|
set to <b>1</b>. Set to <b>0</b> for <a href=
|
|
"http://elog.psi.ch/elog/elcode_en.html">ELCode</a> encoding, to
|
|
<b>2</b> for HTML encoding. The default is <b>2</b>, 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 <b>0</b> or <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Allowed encoding = <n></code></b><br>
|
|
Allowed encoding options. <code><b><n></b></code> can be the sum of
|
|
following flags:
|
|
<ul>
|
|
<li>1 : Plain
|
|
</li>
|
|
<li>2 : ELCode encoding
|
|
</li>
|
|
<li>4 : HTML encoding
|
|
</li>
|
|
</ul>
|
|
To allow plain and HTML encoding for example, set
|
|
<code><b><n></b></code> to 5. Default is <b>7</b>. 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.
|
|
</li>
|
|
<li>
|
|
<b><code>Allow HTML = 0|1</code></b><br>
|
|
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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Suppress default = 0|1|2|3</code></b><br>
|
|
This specifies the default state of the "<i>Suppress Email
|
|
notification</i>" button on the new message entry form. For
|
|
installations where normally an email notification is not necessary,
|
|
the default can be set to <b>1</b>. If an important entry is entered,
|
|
users can then uncheck the suppress box. If this value is set to
|
|
<b>2</b> , the suppress box is not displayed at all, so that an email
|
|
notification is always produced. If this value is set to <b>3</b>, the
|
|
email notification is always suppressed. The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Suppress Email on edit = 0|1|2|3</code></b><br>
|
|
This is the same as <b><code>Suppress default</code></b>, but just for
|
|
edited entries. The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Resubmit default = 0|1|2</code></b><br>
|
|
This specifies the default state of the "<i>Resubmit as new entry</i>"
|
|
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 <b>2</b>, the resubmit box is not
|
|
displayed at all. The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Resubmit replies = 0|1</code></b><br>
|
|
If this flag is set to <b>1</b> 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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Display Email recipients = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, 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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Email Format = <n></code></b><br>
|
|
Specifies what is sent in an email notification. <n> is the sum
|
|
of following flags:<br>
|
|
<ul>
|
|
<li>1 : Send heading line "A new entry has been submitted..."
|
|
</li>
|
|
<li>2 : Send attributes
|
|
</li>
|
|
<li>4 : Send URL of logbook entry
|
|
</li>
|
|
<li>8 : Send message body
|
|
</li>
|
|
<li>16: Send optional attachments as email attachments
|
|
</li>
|
|
<li>32: Send logbook name
|
|
</li>
|
|
<li>64: Send names of optional attachments
|
|
</li>
|
|
</ul>
|
|
So to send for example only the attributes and the URL, set
|
|
<n> to <b>6</b>. Default is <b>63</b> (send everything).
|
|
</li>
|
|
<li>
|
|
<b><code>Email Encoding = <n></code></b><br>
|
|
Specifies in which encoding an email is sent. <n> is the sum of
|
|
following flags:<br>
|
|
<ul>
|
|
<li>1 : Plain text
|
|
</li>
|
|
<li>2 : HTML in the form of the plain text, but with ELCode
|
|
interpreted
|
|
</li>
|
|
<li>4 : Full HTML page as shown in elog
|
|
</li>
|
|
</ul>
|
|
So to send email in plain text and full HTML, set <n> to
|
|
<b>5</b>. Some email clients have the possibility then to switch from
|
|
one view to the other. Default is <b>2</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Max email attachment size = <n></code></b><br>
|
|
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 <b>10000000</b> (ten million bytes).
|
|
</li>
|
|
<li>
|
|
<b><code>Back to main = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, the "<i>List</i>" button takes you back to
|
|
the logbook selection page instead to the last entry of the current
|
|
logbook. The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Logout to main = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, the "<i>Logout</i>" operation takes you back
|
|
to the logbook selection page instead to the login page. The default is
|
|
<b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Logout to URL = <URL></code></b><br>
|
|
If this URL is set, the "<i>Logout</i>" operation takes you to
|
|
a specific web page specified in the URL.
|
|
</li>
|
|
<li>
|
|
<b><code>List after submit = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, the list page is shown after the
|
|
submission of a new entry. If this flag is <b>0</b>, the entry just
|
|
submitted is shown. The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Restrict edit = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, 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 <i>"Preset xxxx"</i>
|
|
option. The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Expand default = 0|1|2|3</code></b><br>
|
|
This setting determines how messages are displayed in threaded mode.
|
|
Following options are possible:
|
|
<ul>
|
|
<li>
|
|
<b>0</b>: Only message heads are displayed, no replies. A "+"
|
|
indicates which message has one or more replies.
|
|
</li>
|
|
<li>
|
|
<b>1</b>: Messages and replies are displayed, but no message body.
|
|
</li>
|
|
<li>
|
|
<b>2</b>: Messages and replies are displayed together with the
|
|
first few lines of the message body. The number of lines is
|
|
controlled by the <code><b>Summary lines</b></code> option.
|
|
</li>
|
|
<li>
|
|
<b>3</b>: Messages and replies are displayed together with the full
|
|
message body.
|
|
</li>
|
|
</ul>
|
|
The default is <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Hidden = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, 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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Hide Comments = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, the logbook "Comment" is not displayed in the
|
|
logbook selection page. Default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Use Lock = 0|1</code></b><br>
|
|
If this flag is <b>1</b>, a logbook entry is <i>locked</i> when someone
|
|
edits it (clicking the <i>Edit</i> 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.<br>
|
|
<br>
|
|
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.<br>
|
|
<br>
|
|
Note that logbooks accessible from the internet usually get scanned by
|
|
search engines. This can lead to situations where the <i>Edit</i> link
|
|
of each message is "followed" by a bot, resulting in all messages being
|
|
locked. In those cases locking has to be turned off.<br>
|
|
<br>
|
|
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.<br>
|
|
<br>
|
|
Default for "Use Lock" is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Show top groups = 0|1</code></b><br>
|
|
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 <code><b>Show top
|
|
groups</b></code> can be set to <code><b>1</b></code>, in which case a
|
|
list of available top groups is shown.
|
|
</li>
|
|
<li>
|
|
<b><code>Fix text = 0|1</code></b><br>
|
|
With this options the main text body can be fixed, so that it cannot be
|
|
changed via the <b><code>Edit</code></b> 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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Case sensitive search = 0|1</code></b><br>
|
|
This switch has two meanings. First, it defines the default state of
|
|
the <code><b>Case sensitive</b></code> check box in the "Find" page.
|
|
Second, it determines if the quick filters are case sensitive or not.
|
|
The default is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Mode commands = 0|1</code></b><br>
|
|
If this flag is missing or set to <b>1</b>, the links "Full", "Summary"
|
|
and "Threaded" are shown on the top of the listing page. If this flag
|
|
is set to <b>0</b>, these commands are hidden. This might be useful in
|
|
logbooks where only one mode makes sense for example.
|
|
</li>
|
|
<li>
|
|
<b><code>Suppress execute default = 0|1</code></b><br>
|
|
External scripts can be called with the <code><b>Execute
|
|
new/edit/delete</b></code> 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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Preserve IDs = 0|1</code></b><br>
|
|
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 <b>1</b>.
|
|
If an entry with the same ID in the destination logbook exists already,
|
|
it gets overwritten. Default for this setting is <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Collapse to last = 0|1</code></b><br>
|
|
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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Sort Attribute Options <attribute> = 0|1</code></b><br>
|
|
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 <b>0</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Allow branching = 0|1</code></b><br>
|
|
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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Enable Smileys = 0|1</code></b><br>
|
|
When encoding an entry with ELCode, certain sequenes such as <b>:-)</b> 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 <b>1</b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Refresh = <seconds></code></b><br>
|
|
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 <b>0</b> meaning no refresh.
|
|
</li>
|
|
<li>
|
|
<b><code>Show last default = <days></code></b><br>
|
|
In large logbooks, search operations can take quite long, blocking other users
|
|
from accessing ELOG. On the <i>Find</i> 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 <i>Show last</i> drop-down box, then the
|
|
search again can take quite long. This option pre-selects an option in the
|
|
<i>Show last</i> drop-down box, so that the user does not have to think about
|
|
selecting a certain time period. Following options are possible: <b>0, 1, 3,
|
|
7, 31, 92, 182, 364</b>. "0" means an unrestricted search default.
|
|
</li>
|
|
<li>
|
|
<b><code>Save drafts = 0|1</code></b><br>
|
|
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 <b><code>Save</code></b> button or by the
|
|
<i>autosave</i> feature (see next option). The <b><code>Save drafts</code></b>
|
|
option turns this feature on or off. Default is <b><code>1</code></b>.
|
|
</li>
|
|
<li>
|
|
<b><code>Autosave = <seconds></code></b><br>
|
|
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
|
|
<b><code>10</code></b> seconds after the last edit. Setting Autosave to
|
|
zero disables the autosave functionality.
|
|
</li>
|
|
<li>
|
|
<b><code>List drafts = 0|1</code></b><br>
|
|
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 <b><code>0</code></b>, 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
|
|
<b><code>New</code></b> menu item, in which case the system presents to the user
|
|
a list of open draft messages to be continued.
|
|
</li>
|
|
<li>
|
|
<b><code>Hard wrap = 0|1</code></b><br>
|
|
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 <b>0</b>.
|
|
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.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<a name="themes" id="themes"></a>
|
|
</p>
|
|
<hr>
|
|
<div class="section">
|
|
Themes
|
|
</div>
|
|
<p>
|
|
Themes are layout and color schemes which determine the look and feel of
|
|
a logbook (sometimes called <i>"skins"</i>). 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.
|
|
</p>
|
|
<p>
|
|
Each theme resides in a separate subdirectory and is specified with the
|
|
<b><code>theme = <dir></code></b> option in the configuration file.
|
|
Each theme can contain several CSSs, which can be selected with the
|
|
<b><code>CSS = <filename></code></b> option.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
To change colors and fonts, the source of a ELOG page can be examined.
|
|
All elements use CSS classes which are specified in the
|
|
<b><code>class="<name>"</code></b> statements. These classes can be
|
|
found in the <b><code>.../themes/default/default.css</code></b> file and
|
|
changed accordingly. For a description of all options, please consult for
|
|
example the <a href="http://www.w3.org/TR/REC-CSS1">W3C</a> consortium.
|
|
</p>
|
|
<p>
|
|
If the CSS file is edited, most browsers require a "reload" to refresh
|
|
the modified file. The <b>elogd</b> daemon does not have to be restarted
|
|
after a change in the CSS file.
|
|
</p>
|
|
<p>
|
|
These two images display the same logbook entry using different themes:
|
|
</p>
|
|
<p>
|
|
<img src="theme1.jpg"><img src="theme2.jpg">
|
|
</p>
|
|
<p>
|
|
<a name="mirroring" id="mirroring"></a>
|
|
</p>
|
|
<hr>
|
|
<div class="section">
|
|
Mirroring
|
|
</div>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
To solve this problem, <i>mirroring</i> 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.
|
|
</p>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
<b>Automatic configuration</b>
|
|
<p>
|
|
A complete elog server can be transferred to a secondary server using
|
|
the <code><b>clone</b></code> command. Assume the existing server
|
|
resides at <code><b>http://master.your.domain/</b></code>, and you
|
|
want to mirror this server to a new location at
|
|
<code><b>http://slave.your.domain/</b></code>. You do that by
|
|
installing the elog package at the slave machine, and then executing
|
|
on the slave:
|
|
</p>
|
|
<pre>
|
|
elogd -C http://master.your.domain
|
|
</pre>
|
|
or
|
|
<pre>
|
|
elogd -C https://master.your.domain
|
|
</pre>
|
|
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.
|
|
<p>
|
|
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:
|
|
</p>
|
|
<pre>
|
|
elogd -v -C http://master.your.domain
|
|
</pre>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<b>Manual configuration</b>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<b><code>Mirror server = <URL-list></code></b><br>
|
|
<br>
|
|
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:<br>
|
|
<br>
|
|
<code>Mirror server = myhost.mydomain.org:8080,
|
|
http://another.server.org/elog/, https://yet.another.org</code><br>
|
|
<br>
|
|
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.
|
|
</li>
|
|
<li>
|
|
<b><code>Mirror config = 0 | 1</code></b><br>
|
|
<br>
|
|
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 <b><code>1</code></b>. Default is <b><code>0</code></b>. Only
|
|
the individual logbook section is mirrored, not the [global]
|
|
section. Settings which are specific to one server, for example the
|
|
<b><code>URL =</code></b> statement, should then be kept in the
|
|
[global] section, so that they are not mirrored between different
|
|
servers.<br>
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Mirror cron = Minute Hour Day Month Weekday</code></b><br>
|
|
<br>
|
|
This statement turns on periodic mirroring. The format is similar
|
|
to the UNIX <code><b>cron</b></code> 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:<br>
|
|
<br>
|
|
<table border="1">
|
|
<tr>
|
|
<th>
|
|
Mirror cron=
|
|
</th>
|
|
<th>
|
|
meaning
|
|
</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
0 3 * * *
|
|
</td>
|
|
<td>
|
|
Every night at 3:00
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
30 7 1,15 * *
|
|
</td>
|
|
<td>
|
|
At 7:30 every 1st and 15th of a month
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
0 12 10 10 *
|
|
</td>
|
|
<td>
|
|
Once a year at 12:00 on my birthday
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
0 7-18 * * 1-5
|
|
</td>
|
|
<td>
|
|
Once every hour from 7:00 to 18:00 from Monday to Friday
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
Valid ranges for each value are:<br>
|
|
<br>
|
|
<table border="1">
|
|
<tr>
|
|
<td>
|
|
Minute
|
|
</td>
|
|
<td>
|
|
0-59
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Hour
|
|
</td>
|
|
<td>
|
|
0-23
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Day
|
|
</td>
|
|
<td>
|
|
1-31
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Month
|
|
</td>
|
|
<td>
|
|
1-12
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Weekday
|
|
</td>
|
|
<td>
|
|
0-6 with 0=Sunday, 1=Monday, etc.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
If mirroring is turned on, it is advisable to use the
|
|
<b><code>Logfile =</code></b> option to turn on logging, so that
|
|
one can inspect the logfile to see if the mirroring works
|
|
correctly.<br>
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Mirror user = <name></code></b><br>
|
|
<br>
|
|
If periodic mirroring is used via the <code><b>Mirror cron
|
|
=</b></code> 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.<br>
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Mirror simulate = 0 | 1</code></b><br>
|
|
<br>
|
|
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
|
|
<b><code>0</code></b>.<br>
|
|
<br>
|
|
</li>
|
|
<li>
|
|
<b><code>Mirror exclude = 0 | 1</code></b><br>
|
|
<br>
|
|
By default, all logbooks are mirrored. Individual logbooks might be
|
|
excluded from mirroring by putting <b><code>Mirror exclude =
|
|
1</code></b> in their individual logbook section of the
|
|
configuration file (<b>Not</b> the [global] section). Default is
|
|
<b><code>0</code></b>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
<p>
|
|
If the statement <code><b>Mirror server</b></code> is present in the
|
|
configuration file, a new menu option <b><code>"Synchronize"</code></b>
|
|
appears on the elog page. Clicking on this menu options starts the
|
|
synchronization:<br>
|
|
<br>
|
|
<img src="sync.gif"><br>
|
|
<br>
|
|
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:<br>
|
|
<br>
|
|
</p>
|
|
<ul>
|
|
<li>If an entry has been modified locally but not remotely, it is
|
|
submitted to the remote server.
|
|
</li>
|
|
<li>If an entry has been modified remotely but not locally, it is
|
|
retrieved from the remote server and saved locally.
|
|
</li>
|
|
<li>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.
|
|
</li>
|
|
<li>If an entry has been deleted locally, it is deleted remotely.
|
|
</li>
|
|
<li>If an entry has been deleted remotely, it is deleted locally.
|
|
</li>
|
|
<li>If a new entry exists locally, it is submitted.
|
|
</li>
|
|
<li>If a new entry exists remotely, it is retrieved from the remote
|
|
server and saved locally.
|
|
</li>
|
|
<li>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
|
|
<b><code>elog:123</code></b>) to the local entries are used, since they
|
|
will point afterwards to the wrong entry.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<hr>
|
|
<div class="footer">
|
|
Content by <a class="nav" href="mailto:Stefan.Ritt@psi.ch">Stefan
|
|
Ritt</a>, Web pages by <a class="nav" href="mailto:fredp@mygale.org">Fred
|
|
Pacquier</a>
|
|
</div>
|
|
</body>
|
|
</html>
|