|
Document revision: 2024-10-28
Refers to WEBDLG2 version: B0840 2409-1
Table of contents
Overview
To start and run a WEBDLG2 application, the web browser loads an
HTML document which in turn loads
the WEBDLG2 client JavaScript code and CSS rules.
In addition, applications may open further documents such as
PDF printouts, archived invoices,
HtmlView contents, etc.
The eloqwebd2 includes an HTTP/1.1 web server
to serve such static documents. This allows to use WEBDLG2 applications
without needing to install and configure an additional web server, e.g.,
Apache httpd.
Alternatively, if a web server is available on the system, e.g., Apache
httpd, it may as well be used
instead of the eloqwebd2 internal web server.
Internal web server
- Integrated in WEBDLG2, does not depend on additional web server.
- Easy to configure.
- Functionality is tailored to typical Eloquence DLG application use.
External web server, e.g.,
Apache httpd
- Provides additional functionality, for example to serve active content
such as PHP applications and/or CGI programs.
Starting applications
The documents required to start WEBDLG2 applications
(application start document,
client JavaScript code and CSS
rules) are installed in the htdocs subdirectory below the
Eloquence share/webdlg2 directory, thus they are automatically
available to the internal web server.
- HP-UX, Linux
- /opt/eloquence/8.4/share/webdlg2/htdocs
- Windows
- C:\Program Files\Eloquence\8.4\share\webdlg2\htdocs
By default, the internal web server handles an URI root path
as application identifier
(app_id) to start the
specified application.
For example:
http://SERVER.NAME/APPLICATION
A Handler=App URI pattern
may be configured to specify a different
application base URI, and/or to specify a
custom start document, and/or to apply
access rules. For example:
[/app]
Handler = App
Allow = 192.168.77.0/24
In this example, clients located in the 192.168.77.0 network are
allowed to start WEBDLG2 applications.
The application base URI is /app, a request like below
would start the specified application:
http://SERVER.NAME/app/APPLICATION
This example uses the default eloqwebd2
start document because no path is specified.
If path would be specified, a custom start document
would be used.
File format
The default URI configuration file is eloqwebd2.uri located
in the Eloquence etc directory:
- HP-UX, Linux
-
/etc/opt/eloquence/8.4/eloqwebd2.uri
- Windows
-
C:\Program Files\Eloquence\8.4\etc\eloqwebd2.uri
The eloqwebd2.cfg uriFile
configuration may be used to specify a file name different from the default.
A running eloqwebd2 server automatically reloads
the URI configuration file whenever it is modified.
URI definitions configured in this file define how an HTTP request
URI is mapped to a static document located in the file system.
In addition, the default URI definitions for the
application start document and for
the eloqwebd2 server status page may be customized.
Each URI definition is a separate section. The section header in square
brackets specifies the URI pattern to be matched against a request URI.
The URI pattern in square brackets is case sensitive.
String values can be enclosed in double quotes to protect leading or trailing
spaces. An unquoted hash character (#) starts a comment.
URI pattern matching
A pattern like [/path/to] matches any request URI starting with
/path/to, for example:
/path/to/sitemap.html
/path/to/images/logo.png
The URI pattern may use the * and/or ?
wildcard characters:
- The * wildcard matches any sequence of characters
except the / path separator.
- The ? wildcard matches any single character.
If an URI pattern segment consists of a single * wildcard
it matches zero or one or multiple hierarchy levels (aka. directories).
For example, the URI pattern [/path/to/*/docs] matches any
request URI below:
/path/to/docs/invoice.pdf
/path/to/my/special/docs/info.txt
Consequently, an URI pattern starting with a single *
wildcard matches regardless of the hierarchy level, for example,
[*/*.pdf] matches any requested PDF document
such as:
/doc/manual.pdf
/assets/catalog/item.pdf
If a request URI matches multiple patterns, more specific patterns are
matched before less specific patterns. For example, assuming that these
URI patterns are configured:
- Pattern A: [/docs/schematics]
- Pattern B: [/docs]
- Pattern C: [*/*.comp]
Given the request URI:
/docs/schematics/components/A2602.comp
- First, the (C) pattern is matched, it has a leading wildcard
which is more specific than any other pattern having a leading
/ slash. The (C) pattern configuration
would typically define the media type
for the *.comp files, for example:
[*/*.comp]
MediaType = application/xml
- Next, the (A) pattern is matched, it is more specific than the (B)
pattern because it specifies more hierarchy levels. The (A) pattern could,
for example, define an access rule for the schematics subdirectory
(GroupList,
Allow, Deny,
see below):
[/docs/schematics]
Allow = 192.168.77.0/24
GroupList = @auth
- Finally, the (B) pattern is matched, which would typically define the
path, i.e., which directory in the file system is
associated with the /docs URI. For example:
[/docs]
Path = /srv/eloqwebd2/htdocs/common
When the path is known, pattern matching is complete.
The result is the path defined by the (B) pattern
along with the access rule defined by the (A) pattern and the media type
defined by the (C) pattern, for example:
Path = /srv/eloqwebd2/htdocs/common
Allow = 192.168.77.0/24
GroupList = @auth
MediaType = application/xml
In this example, the resulting document location in the file system
is:
/srv/eloqwebd2/htdocs/common/schematics/components/A2602.comp
User directory pattern
A pattern starting with /~*/ may be used to map user-specific files,
for example located in a subdirectory below the user's home directory.
- Example 1:
[/~*/]
Path = /home/*/public
Request URI |
Mapped to |
/~mary/info.txt |
/home/mary/public/info.txt |
/~joe/doc/9876.pdf |
/home/joe/public/doc/9876.pdf |
The /*/ path placeholder is replaced with
/USERNAME/.
On Windows, \*\ is recognized as path placeholder as well.
- Example 2:
[/~*/docs]
Path = /docs/user
Request URI |
Mapped to |
/~mary/docs/info.txt |
/docs/user/mary/info.txt |
/~joe/docs/new/9876.pdf |
/docs/user/joe/new/9876.pdf |
When the path does not contain the /*/
placeholder, the user name is assumed to indicate a subdirectory one level
below the specified path.
Please note: Multiple /*/ path
placeholders are not supported.
Configuration
-
Path
- Specifies the absolute path of either a directory or a file
in the file system.
- Directory
- The last URI path component matching the specified pattern
is appended to form the absolute path of the document.
- File
- The specified absolute document path is used, the last
URI path component matching the specified pattern is ignored.
If Handler=App is configured,
Path needs to refer to an application
start document in the file system (see below).
If Handler=Status is configured,
Path needs to refer to an eloqwebd2 server status
document in the file system (see below).
-
Index
- Specifies an index file name to be used when the request URI matches
a directory in the file system.
For example:
[/docs]
Index = index.html
Given a request URI like /docs or
/docs/schematics, and assuming the URI matches
a directory in the file system, the index.html
file name is appended to form the absolute path of the document.
-
MediaType
- Defines the media type to be used when serving a document
matching the specified pattern.
By default, the media type is obtained from the
mimeFile configuration,
or it is application/octet-stream if the type cannot be
determined.
Typically, MediaType is used for custom (non-standard) file
types, for example:
[*/*.comp]
MediaType = application/xml
-
Handler
- Specifies that this pattern defines a special, non-document URI.
- Handler = App
- This may be configured to define an
application start document URI
different from the default, and/or to replace the
built-in start document,
and/or to define start document
access rules (Allow, Deny,
see below).
If Path is specified, it needs to refer to an
application start document
in the file system.
The document needs to contain the <script id="eq-webdlg">
tag having the app=$((APP)) query string argument,
such as:
<script id="eq-webdlg"
src="eq-webdlg.js?app=$((APP))">
</script>
The document may in addition contain the $((TITLE)) token which
is replaced with the
application title,
for example:
<title>$((TITLE))</title>
A custom start document should be derived from the
default eloqwebd2 start document
eq-webdlg-app.html installed in the htdocs
subdirectory below the Eloquence share/webdlg2 directory:
- HP-UX, Linux
- /opt/eloquence/8.4/share/webdlg2/htdocs/eq-webdlg-app.html
- Windows
- C:\Program Files\Eloquence\8.4\share\webdlg2\htdocs\eq-webdlg-app.html
If Path is not specified, the
default eloqwebd2 start document
is used.
- Handler = Status
- This may be configured to define an URI for the
eloqwebd2 server status page different from
the default, and/or to replace the
built-in status document, and/or to define
status page access rules
(Allow, Deny, see below).
If Path is specified, it needs to refer to a
status document in the file system.
A custom status document should be derived from the
default eloqwebd2 status document
eq-webdlg-status.html installed in the htdocs
subdirectory below the Eloquence share/webdlg2 directory:
- HP-UX, Linux
- /opt/eloquence/8.4/share/webdlg2/htdocs/eq-webdlg-status.html
- Windows
- C:\Program Files\Eloquence\8.4\share\webdlg2\htdocs\eq-webdlg-status.html
If Path is not specified, the
default eloqwebd2 status document is used.
-
CacheMax
- Defines the maximum age in seconds of a matching document in the
web browser user's private cache.
A suffix may be optionally appended:
m | - | minutes | (60 seconds) |
h | - | hours | (3600 seconds) |
d | - | days | (86400 seconds) |
w | - | weeks | (604800 seconds) |
The browser is instructed to revalidate the document when the
maximum cache age has expired. If the document has not been
modified, the eloqwebd2 responds with a 304 Not Modified HTTP
status, which resets the cache age and allows the browser to
continue using the cached document.
If set to zero, the browser will never cache a document matching
the specified pattern.
The default is: 1h (one hour, 3600 seconds)
-
HttpHeader
-
Allows to set additional HTTP response headers.
Multiple HttpHeader entries are recognized.
For example:
HttpHeader = Strict-Transport-Security: max-age=15768000
- Informs the browser that the document's web site domain should
only be accessed using HTTPS. The browser will remember this
for 6 months (15768000 seconds).
HttpHeader = Access-Control-Allow-Origin: *
- Permits cross-origin access to the document.
Browsers restrict loading sensitive resources such as JavaScript
documents based on their origin. By default, origins must match.
The https://server.name and https://server.name:8188
origins are different. To allow that a https://server.name
HTML document can load JavaScript from https://server.name:8188,
the URI definition for the JavaScript document requires:
HttpHeader = Access-Control-Allow-Origin: https://server.name
The * wildcard may be used to allow any origin:
HttpHeader = Access-Control-Allow-Origin: *
HttpHeader = X-Frame-Options: SAMEORIGIN
- Specifies that this document may only be embedded into another
document if the other document and all its ancestors have the
same origin.
-
GroupList
- Comma- or space-separated list of group names, used to enable
or reject access to the URI based on group membership.
- GroupList = @auth
- Specifies that the URI is restricted to authenticated users.
Typically, this means that access to the related documents is granted
in application context, i.e., when the user has successfully logged in
to start an application, but access is denied to the public.
Please note: URI authentication is currently not functional yet.
Only the GroupList=@auth configuration is currently supported.
-
Allow
Deny
- Used to enable or reject access to the URI based on the
client network address.
Allow / Deny argument syntax:
{ All | hostname | ip-address [/{addrbits|netmask}] }
-
Multiple Allow / Deny entries are
recognized and combined.
-
hostname is the name of a host or network that is resolved into one
or more ip addresses.
-
ip-address is either an IPv4 or IPv6 address.
-
An IPv6 address, enclosed in square brackets, such as [::1].
The addrbits option may be used to specify the number of relevant bits
in the IP address.
-
An IPv4 address, such as 127.0.0.1. The addrbits option may be
used to specify the number of relevant bits in the IP address.
The netmask option allows to specify an IPv4 network mask, such as
255.255.255.0.
If neither Allow nor Deny are configured,
access to the URI is enabled from all network addresses
(implied Allow=All).
If Allow and/or Deny are configured,
access to the URI is denied unless specifically allowed
(implied Deny=All).
|
|