• Overview
• Configuration
• Starting the eloqwebd2
• Starting in foreground

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.

HP-UX, Linux

/etc/opt/eloquence/8.4/eloqwebd2.cfg

Windows

C:\Program Files\Eloquence\8.4\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)

ServiceHTTP = 8188
ServiceHTTPS = 8188

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.

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.4:/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

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

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
• M = Server status
• 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.

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: 10

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 or CookieMaxAge is set (see below).

A suffix may be optionally appended:

m	-	minutes	(60 seconds)
h	-	hours	(3600 seconds)
d	-	days	(86400 seconds)
w	-	weeks	(604800 seconds)

The default is: 10m (10 minutes, 600 seconds)

CloseTimeout

WEBDLG2 does not have any means to find out whether a web browser window or tab has been closed, or whether the page is reloaded, or whether a new page is loaded where the current DLG session is resumed.

CloseTimeout specifies the time in seconds a session waits to resume after the web browser has disconnected. When this timeout expires, WEBDLG2 assumes that the web browser window or tab has been closed, and terminates the DLG session.

The default is: 60 (1 minute)

DlgConnectTimeout

Specifies the timeout in seconds to close a DLG listener if no DLG connection is established (eloqwebd2.app DlgPort).

The default is: 60 (1 minute)

CookieMaxAge

Specifies the maximum age in seconds of the cookie identifying the web browser client (aka. user agent, see above).

If set to a nonzero value, a permanent cookie is defined which persists for the specified number of seconds, allowing to recognize cached login credentials even after the associated web browser has been closed and later reopened.

A suffix may be optionally appended:

m	-	minutes	(60 seconds)
h	-	hours	(3600 seconds)
d	-	days	(86400 seconds)
w	-	weeks	(604800 seconds)

If not set or zero, a session cookie is defined which only persists as long as the associated web browser is active.

The default is: not set (session cookie)

HTTPKeepAlive

If nonzero, the HTTP persistent connection mode is enabled so that the web browser may use a single connection for multiple requests. This typically speeds up page loading because it minimizes the overhead required to establish new connections and, in case of HTTPS, process the TLS handshake.

The default is: 15 (seconds)

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

The eloqwebd2 is started/stopped with /sbin/init.d/eloq84:

/sbin/init.d/eloq84 start eloqwebd2
/sbin/init.d/eloq84 stop eloqwebd2

The status can be queried with:

/sbin/init.d/eloq84 status eloqwebd2

The START_ELOQWEBD2 configuration in the /etc/rc.config.d/eloquence84 file specifies whether the eloqwebd2 daemon is started and stopped automatically when the system is started or shut down.

/etc/rc.config.d/eloquence84

# If START_ELOQWEBD2 is set to 1 the eloqwebd2 daemon is started
# automatically. The ELOQWEBD2_ARGS allows to specify eloqwebd2 command 
# line arguments.
#START_ELOQWEBD2=0
#ELOQWEBD2_ARGS=""

Linux

The eloqwebd2 is started/stopped with the eloqwebd84.service systemd unit:

systemctl start eloqwebd84.service
systemctl stop eloqwebd84.service

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

systemctl start eloqwebd84
systemctl stop eloqwebd84

The status can be queried with:

systemctl status eloqwebd84

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

systemctl enable eloqwebd84
systemctl disable eloqwebd84

Windows

The Windows Service Control Manager is used to start/stop the eloqwebd Windows service. Alternatively, eloqwebd may be started/stopped on the command line (as Administrator):

net start eloqwebd
net stop eloqwebd

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

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

Command line options:

 -help        = show usage (this list)

 -c name      = configuration file, default on HP-UX and Linux:
                 /etc/opt/eloquence/8.4/eloqwebd2.cfg
                Default on Windows:
                 C:\Program Files\Eloquence\8.4\etc\eloqwebd2.cfg

 -d flags     = debug flags, default:
                 configuration file [Server] LogFlags

 -l name      = log file name (or console/syslog), default:
                 configuration file [Server] LogFile

 -H directory = $WEBDLG2_HOME directory, default on HP-UX and Linux:
                 /opt/eloquence/8.4/share/webdlg2
                Default on Windows:
                 C:\Program Files\Eloquence\8.4\share\webdlg2

 -T directory = $WEBDLG2_TEMP directory, default on HP-UX and Linux:
                 { $ELOQUENCE_TMP | /var/opt/eloquence/8.4 }/webdlg2.tmp
                Default on Windows:
                 %TEMP%\webdlg2.tmp

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)

HP-UX, Linux

/opt/eloquence/8.4/bin/eloqwebd2 -f -lconsole -d*1

Windows

"C:\Program Files\Eloquence\8.4\bin\eloqwebd64" -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 command line option specifies LogFlags = *1.

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