.
Eloquence WEBDLG2 contact contact

Documentation / WEBDLG2 / The eloqwebd2 server

The eloqwebd2 server

 
.
  Document revision: 2022-08-15
Refers to WEBDLG2 version: PE83-2207080 (beta version 57)


Table of contents


The core of WEBDLG2 is a single server process, the eloqwebd2 server.

It combines a multi-user and multi-session DLG server with a HTTP/HTTPS server, allowing to serve static documents, and providing the WebSocket protocol to communicate with web browsers.

The eloqwebd2 representation of a user's web browser is the user agent. A user may run multiple Eloquence DLG applications in multiple browser windows and/or browser tabs. Each application is represented by a session managed by the eloqwebd2. Sessions running in the same browser are related because they are associated with the same eloqwebd2 user agent.

Each eloqwebd2 session maintains a DLG connection to the eloqcore process executing the application, and a WebSocket connection to the browser.

In order to run an Eloquence DLG application, the browser loads the WEBDLG2 client consisting of Javascript code (functionality) and CSS rules (visual appearance). The client Javascript code initiates the WebSocket connection to the eloqwebd2.

While the DLG connection is permanent as long as the connected DLG application runs, the WebSocket connection can disconnect and reconnect at any time. For example, when the user's device is put to sleep and later resumed, or when it is moved out of a Wi-Fi network into a cellular network, or when the user refreshes the document in a browser window or tab, the WebSocket connection is reestablished and the DLG session is resumed.


The default eloqwebd2 configuration file is eloqwebd2.cfg located in the Eloquence etc directory:
HP-UX, Linux
/etc/opt/eloquence/8.3/eloqwebd2.cfg
Windows
C:\Program Files (x86)\Eloquence\8.3\etc\eloqwebd2.cfg

It is possible, but typically not necessary, to override the default configuration file using the eloqwebd2 -c command line option.

The file is divided into sections (section names in square brackets). The section names are not case sensitive. String values can be enclosed in double quotes to protect leading or trailing spaces. An unquoted hash character (#) starts a comment.

Configuration sections:

Server configuration [server]
This section configures various eloqwebd2 settings.

Server limits [limits]
This section configures the eloqwebd2 scalability and behaviour.

ServiceHTTP
The service name (as defined in /etc/services) or the port number where the eloqwebd2 should listen for HTTP requests.

If not configured, HTTP requests are not accepted.

A suffix /4, /6, or /46 may be used for establishing IPv4 only, IPv6 (with implied IPv4) or separate IPv4 and IPv6 listening sockets. By default, separate IPv4 and IPv6 sockets are used.

For example: ServiceHTTP = 80 (equivalent to: 80/46)

ServiceHTTPS
The service name (as defined in /etc/services) or the port number where the eloqwebd2 should listen for HTTPS (secure HTTP) requests.

This requires that TLS is configured (see below).

A suffix /4, /6, or /46 may be used (see ServiceHTTP above).

For example: ServiceHTTPS = 443 (equivalent to: 443/46)

Please note:

The eloqwebd2 requires that ServiceHTTP and/or ServiceHTTPS are configured.

The default HTTP port 80 (service name is typically: http) and/or the default HTTPS port 443 (service name is typically: https) may already be occupied when another web server is running on the same system, e.g., Apache httpd. In this case the eloqwebd2 needs to be configured to a different port, for example:

ServiceHTTP = 8188
ServiceHTTPS = 8188

As shown in the example above, both ServiceHTTP and ServiceHTTPS may be set identically, the eloqwebd2 then automatically detects whether to use HTTP or HTTPS.

If the web server used to deliver the WEBDLG2 client Javascript and CSS, e.g., Apache httpd, is configured for HTTPS, the eloqwebd2 should be configured for HTTPS as well. Otherwise the web browser may refuse to open WEBDLG2 WebSocket connections due to its security policy.

TLSCertChainFile
Absolute path to a file in PEM format containing the server certificate and optionally any additional intermediate certificates which represent the verification chain up to the root certificate.

This is required if HTTPS (secure HTTP) requests should be accepted (see ServiceHTTPS above).

The certificates in this file must be sorted in the verification order, starting with the server certificate. The file may in addition contain the private key associated with the server certificate, in which case the TLSCertKeyFile configuration below can be omitted.

TLSCertKeyFile
Absolute path to a file in PEM format containing the private key associated with the server certificate. If this key is contained in the TLSCertChainFile above, configuring TLSCertKeyFile is not necessary.

Please refer to the eloqsd documentation about how to obtain the TLSCertChainFile.

UID (HP-UX, Linux)
The name (or numeric id) of the system account to run the eloqwebd2 when started as root. The default is: eloqwebd
GID (HP-UX, Linux)
The name (or numeric id) of the system group to run the eloqwebd2 when started as root. The default is: eloqwebd

Either create the HP-UX/Linux user/group eloqwebd, for example in the /etc/passwd and /etc/group files ...

# /etc/passwd:
eloqwebd:x:88:88:Eloquence WEBDLG:/var/opt/eloquence/8.3:/bin/false

# /etc/group:
eloqwebd:x:88:

... or modify the UID and GID configuration, for example (assumed that the eloq user and group are present on the system):

UID = eloq
GID = eloq

Please note: On HP-UX and Linux, the eloqwebd2 will refuse to start as root unless UID and GID are valid.

On Windows, the Windows Service Manager may be used to configure an account different from SYSTEM to run the eloqwebd service.

appFile
The path/name of the application configuration file.
The default is: eloqwebd2.app
uriFile
The path/name of the URI configuration file.
The default is: eloqwebd2.uri
mimeFile
The path/name of the media types configuration file.
The default is: eloqwebd2.mime

If specified without a path, or if a relative path is specified, the absolute path is resolved relative to the location of this configuration file.

A running eloqwebd2 automatically reloads the application and URI configuration files whenever they are modified.

LogFile
This defines where log messages are written to. This configuration value either specifies a path/file or one of the keywords below:
  • console - log messages are written to the console
  • syslog - log messages will be sent to the syslog daemon (HP-UX, Linux) or the Windows Event Log
The default is: syslog
SysIdent (HP-UX, Linux)
When logging to the syslog daemon, you can define a syslog identifier.
The default is: eloqwebd2
See syslogd(1M) for more information
SysFacility (HP-UX, Linux)
When logging to the syslog daemon, you can define a syslog facility (USER/DAEMON/LOCAL0..LOCAL7).
The default is: USER
See syslogd(1M) for more information
LogFlags
Each log message has an associated origin and severity. The log flags define which messages will be logged. The "*" origin matches all message origins, so it can be used to setup a default which can be overriden for a specific message origin, for example LogFlags = *1S2 to log more detailed connection info.

The default is: *0

The following origin are in use:

  • * = All origins
  • C = Configuration subsystem
  • D = DLG server
  • H = HTTP requests
  • N = Network transport
  • S = Server framework
  • T = Thread kernel
  • W = WebSocket protocol

The following severities are in use:

  • L_ERROR = 0 - error messages
  • L_INFO = 1 - information
  • L_DEBUG = 2 - debug
  • L_VDEBUG = 3 - verbose debug

When using syslog, the following priorities are mapped:

  • L_ERROR = LOG_ERR
  • L_INFO = LOG_NOTICE
  • L_DEBUG = LOG_DEBUG
  • L_VDEBUG = LOG_DEBUG

Please note that enabling log messages with L_VDEBUG severity may result in a large number of log messages.

Set LogFlags = *0 (the default) to enable fatal messages only.
Set LogFlags = *1 to enable regular log messages. Session start/stop/resume messages and HTTP document requests will be logged.
Set LogFlags = *1H0 to enable regular log messages but suppress HTTP document requests.
Set LogFlags = *1S2 to enable more detailed connection and disconnection messages.

AllowHTTP(S)
DenyHTTP(S)
Used to allow/deny HTTP and/or HTTPS connections based on the client network address.

AllowHTTP(S) / DenyHTTP(S) argument syntax:

{ All | hostname | ip-address [/{addrbits|netmask}] }
  • Multiple AllowHTTP(S) / DenyHTTP(S) 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 AllowHTTP(S) nor DenyHTTP(S) are configured, connections are allowed from all network addresses (implied AllowHTTP(S)=All).

If AllowHTTP(S) and/or DenyHTTP(S) are configured, connections are denied unless specifically allowed (implied DenyHTTP(S)=All).

If configured, these server-global access rules are applied on any client connection. In addition, specific Allow/Deny rules may be configured in the application and URI configuration files.

MaxClients
Limits the maximum number of active web browser clients. A web browser client (aka. user agent, see above) is typically equivalent to a user who may have multiple related DLG sessions active.

The default is: 100

MaxSessions
Limits the maximum number of active DLG sessions, i.e., simultaneously connected applications.

The default is: 1000

WorkerThreads
Sets the number of worker threads. A higher setting allows for more parallel activity.

The default is: 100

LoginTimeout
When a user interactively logs in, this specifies the maximum time in seconds until a user is expected to submit the login dialog. When this timeout expires the login dialog is closed and the application is not started.

The default is: 60 (1 minute)

LoginCacheMax
Each web browser client (aka. user agent, see above) maintains a cache of successful interactive logins for related applications (having the same LoginDomain configured in appFile, see above). When a user starts an application and the cache contains a successful login for the application's LoginDomain and server address (and login name if configured), the user is automatically logged in. This way, a user is typically required to log in only once to run multiple applications having the same LoginDomain configured.

LoginCacheMax specifies how many successful logins are cached in case different LoginDomains and/or server addresses and/or login names are used.

If LoginCacheMax is set to zero, the login cache is disabled.
The default is: 5

LoginCacheTimeout
Specifies the time in seconds a web browser client (aka. user agent, see above) persists after all related DLG sessions have been closed. During this timeout, the login cache is still available to automatically log in when applications are started, provided that the web browser has not been quit.

The default is: 600 (10 minutes)

RateBlock
RateResume
Connection rate limiting is a defense against DoS (Denial of Service) attacks. The number of new connection attempts per second is monitored. If it reaches or exceeds the configured RateBlock limit, new connections are refused until the rate drops to RateResume at most.

The defaults are: RateBlock=5000 and RateResume=50


HP-UX
WEBDLG2 has not been released for HP-UX yet.
Linux
On Linux, the eloqwebd2 is started/stopped with the eloqwebd83.service systemd unit:
systemctl start eloqwebd83.service
systemctl stop eloqwebd83.service

As a shortcut, the .service suffix may be omitted:

systemctl start eloqwebd83
systemctl stop eloqwebd83

The status can be queried with:

systemctl status eloqwebd83

To enable or disable that the eloqwebd83 systemd unit is started and stopped automatically when the system is started or shut down:

systemctl enable eloqwebd83
systemctl disable eloqwebd83
Windows
On Windows, the eloqwebd2 is available both as 64-bit executable (eloqwebd64.exe) and as 32-bit executable (eloqwebd32.exe).

Please note:

The 32-bit executable is considered experimental and may no longer be delivered with future WEBDLG2 releases.

Due to 32-bit address space limitations, using the 64-bit eloqwebd64.exe is recommended unless WEBDLG2 is used on a system where the number of simultaneously running DLG sessions is expected to be low.

Regardless which executable is used, the eloqwebd Windows service needs to be be installed first. Open a Windows Command Prompt as Administrator ("Run as Administrator"). To install the 64-bit eloqwebd service:

eloqwebd64 -install
To install the 32-bit eloqwebd service:
eloqwebd32 -install

To uninstall an installed eloqwebd service:

eloqwebd64 -remove
eloqwebd32 -remove

After the eloqwebd service is installed, the Windows Service Manager may be used to configure it to start/stop automatically when the system is started or shut down, and, if desired, to use an account different from SYSTEM.

The eloqwebd service can also be started and stopped on the command line (as Administrator):

net start eloqwebd
net stop eloqwebd

The status can be checked in the configured LogFile or with the Windows Event Viever (expand the Windows Logs folder and select the Application event log).


For diagnostic purposes, e.g., to test a modified configuration, the eloqwebd2 may be started in foreground, i.e., in the shell (HP-UX, Linux) or in a Command window (Windows).

The command line usage is:

usage: eloqwebd2 [options]

options:
 -help           = show usage (this list)
 -c name         = configuration file
 -d flags        = debug flags, default: *0
 -l name         = log file name (or console/syslog/default)
 -h directory    = WEBDLG2_HOME directory, default: share/webdlg2

HP-UX, Linux:
 -f              = run in foreground
 -F facility     = syslog facility (USER/DAEMON/LOCAL0..LOCAL7)
 -I ident        = syslog identifier
 -p pid_file     = location of pid file (default is none)

Windows:
 -install[:name] = install Windows service, default name: eloqwebd
 -remove[:name]  = remove Windows service, default name: eloqwebd

HP-UX, Linux
/opt/eloquence/8.3/bin/eloqwebd2 -f -lconsole -d*1

Windows
eloqwebd64 -lconsole -d*1
eloqwebd32 -lconsole -d*1

The eloqwebd2 needs to be run as superuser (root, Administrator) if privileged port numbers (below 1024) are configured for ServiceHTTP and/or ServiceHTTPS. Otherwise it may be run as regular (unprivileged) user.

The -f command line option (HP-UX, Linux) specifies that the eloqwebd2 should run in foreground.

The -lconsole command line option specifies that log messages should be displayed instead of being written to the configured LogFile.

The -d*1 specifies LogFlags = *1.

Press Ctrl+C to stop an eloqwebd running in foreground.


 
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision: 2022-08-15  
  Copyright © 1995-2022 Marxmeier Software AG