• Overview
• Starting applications
• File format
• URI pattern matching
• User directory pattern
• Configuration

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.

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.

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.

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.

/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

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

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

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

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.

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