Web API WebSocket Server and Web Servers

Deephaven includes several Web HTTP(S) Services:

Client Update Service
Web API Service
Web IDE Service
Query Web Server
Merge Web Server
DIS Web Server

Some of the web based services are disabled at install time for the following reasons:

Bringing up a web service with a self signed TLS certificate causes web browsers to display an untrusted error message with mitigation instructions.
Bringing up the web services without TLS (i.e., using http cleartext) is a security risk on an untrusted network and could be an audit violation in many organizations. Furthermore, modern browsers will refuse to serve plain http web services.

It is recommend that only valid TLS trusted CA signed certificates be used for all web services.

However, some customers may choose to enable web services without TLS in a POC, Test or Lab environment.

Client Update Service

The Client Update Service (CUS) is powered by lighttpd to update clients with server side components including JAR files, properties, etc. The CUS is disabled by default due to reasons cited above.

Securing the Customer Update Service (CUS) with HTTPS

To securely enable the CUS on HTTPS port 443:

Obtain a TLS certificate signed by your trusted CA with the domain name matching the Deephaven server, e.g: myserver.mydomain.com

Concatenate your .crt and .key file together into a single PEM file.

For example:

cat /etc/ssl/private/lighttpd.key /etc/ssl/certs/lighttpd.crt \
> /etc/ssl/private/lighttpd.pem

On the Deephaven Server, edit the /etc/lighttpd/client-update-service.conf file and set the following properties:

server.port = 443
ssl.engine = "enable"
ssl.pemfile = "/etc/ssl/private/lighttpd.pem"

Update /var/www/lighttpd/iris/iris/getdown.txt.pre file as described in the previous section, replacing http with https:

For example:

appbase = https://myserver.mydomain.com/iris/
...
#ui.install_error = http://WEBHOST/iris/error.html
ui.install_error = https://myserver.mydomain.com/iris/error.html

Restart the CUS with monit:

sudo monit restart cus

The "Client Update Service" will be available at:

https://myserver.mydomain.com/

Securing the Customer Update Service (CUS) with User Authentication

By default, the CUS does not require user authentication. The CUS is powered by lighttpd and provides basic and digest authentication methods described by RFC 2617.

To enable authentication with users defined in a file, edit /etc/lighttpd/client-update-service.conf and uncomment the lines for mod_auth and mod_authn_file in the server.modules section. Also uncomment the line (further down in the file) to include "conf.d/iris-auth.conf".

Authorized users are stored in the htpasswd file:

/etc/lighttpd/illumon-cus.user

The htpasswd file contains the username and the crypt()'ed password separated by a colon. Each entry in the file is terminated by a single newline.

For example:

iris:$apr1$1xsLWNhw$.qiKafnbTpoNda/d6X77l.

You can use the htpasswd utility from the Apache distribution to manage htpasswd files. Note that not all versions of htpasswd default to use Apache's modified MD5 algorithm for passwords, which is required by lighttpd. You can force most to use MD5 by running:

htpasswd -nbm <user> <password>

Append the output of the above command to:

/etc/lighttpd/illumon-cus.user

More information on configuration options is available in lighttpd's documentation.

To Disable Authentication:

In order to disable the username/password requirement, edit:

/etc/lighttpd/client-update-service.conf

Change (comment out) the following lines:
include "conf.d/iris-auth.conf" include "conf.d/iris-access_log.conf"
to read:
#include "conf.d/iris-auth.conf" #include "conf.d/iris-access_log.conf"

Restart the CUS with monit:
sudo monit restart client_update_service

Add Authorized users:
Htpasswd -nbm <user> <password>

Append to /etc/lighttpd/illumon-cus.user file.

To enable the CUS on cleartext HTTP port 80:

Note: This is not recommended. Only do this for testing only on a trusted private network.

On the Deephaven Server, edit the /var/www/lighttpd/iris/iris/getdown.txt.pre file. Set the appbase value, replacing WEBHOST with the FQDN (or IP address) of your Deephaven Server.

For example:

#appbase = http://WEBHOST/iris/
appbase = http://myhost.domain.com/iris/
...
#ui.install_error = http://WEBHOST/iris/error.html >ui.install_error = http://myhost.domain.com/iris/error.html

In the M/Monit config folder, remove the .disabled extension from the Client Update Service configuration file name and run Monit reload. This will instruct the M/Monit daemon to reread its configuration and re-initialize:

cd /etc/sysconfig/illumon.d/monit
sudo mv cus.conf.disabled cus.conf
sudo monit reload

Check the status of the getdown service:

sudo monit status client_update_service

Once the "Client Update Service" is up and running, you can proceed to install and run the Launcher on client desktops. The installers for Windows, Mac and Linux desktops can be downloaded from the "Client Update Service" on your Deephaven Server at:

http://<IRIS_SERVER_ADDRESS>/

Note: IRIS_SERVER_ADDRESS is the same as WEBHOST above.

Web API Server TLS Keystore

(.p12 keystore file)

The Web API Server's TLS keystore contains the certificate and private key of a TLS enabled service. You must keep this file private, and not distribute it or store the file in a non-secure location such as a git repository. The Web API Server's keystore file should be unique per node, with a certificate that is signed (issued) by a trusted CA.

The default self signed key pair for the Web API Server is generated when installing the iris-config.rpm and saved to .p12 keystore file:
[-r--r----- irisadmin dbquery ] webServices-keystore.p12

The Web Server keystore file is also protected by a unique randomly generated password stored in base64 encoded format in a read-only hidden file owned by user irisadmin and readable by dbquery group with permission set to 440:
[-r--r----- irisadmin dbquery] .webapi_passphrase

Web API Server Keystore Properties

Keystore Filename:
/etc/sysconfig/illumon.d/auth/keystore.webServices-keystore.p12

Passphrase File:
/db/TempFiles/irisadmin/.auth_passphrase

Properties File:
/etc/sysconfig/illumon.d/resources/web_api_service.prop

Keystore Property Value:
tls.keystore=/etc/sysconfig/illumon.d/auth/webServices-keystore.p12

Passphrase Property:
tls.passphrase.file=/db/TempFiles/irisadmin/.webapi_passphrase

Securing the Web API Server with your CA signed Certificate

Obtain a TLS certificate signed by your trusted CA with the domain name matching the Deephaven server, e.g: myserver.mydomain.com.

Backup the existing file keystore file:

sudo cp /etc/sysconfig/illumon.d/auth/webServices-keystore.p12 \
/etc/sysconfig/illumon.d/auth/webServices-keystore.p12.ORG

Import your CA cert and key files to the Web API Service keystore file:
For example:

STOREPASS=$(sudo cat /db/TempFiles/irisadmin/.webapi_passphrase | base64 --decode) openssl pkcs12 -export -in /etc/ssl/certs/tls.crt -inkey /etc/ssl/certs/tls.key -name webapi -out /etc/sysconfig/illumon.d/auth/webServices-keystore.p12 -passout pass:$STOREPASS

Set the correct permissions on the web services keystore file:

sudo chown irisadmin:dbquery \ /etc/sysconfig/illumon.d/auth/webServices-keystore.p12 sudo chmod 440 /etc/sysconfig/illumon.d/auth/webServices-keystore.p12

Update Query Server Prop File:

/etc/sysconfig/illumon.d/resources/iris-query-server.prop:
# Enable Web Sockets for Query Workers
RemoteQueryDispatcher.websocket.enabled=true

Restart Web API Service with Monit:

sudo monit restart web_api_service

Server Settings

Web API Server

API Server Properties File:
/etc/sysconfig/illumon.d/resources/web_api_service.prop

API Server Default Settings:

# The keystore holding the SSL certificate to use for HTTPS.
# No key file means SSL is disabled and plaintext HTTP will be used instead.
This is not recommended.
# tls.keystore=

tls.keystore=/etc/sysconfig/illumon.d/auth/webServices-keystore.p12
tls.passphrase.file=/db/TempFiles/irisadmin/.webapi_passphrase

# The port listening for incoming http/https connections
Webapi.server.port=8123

# The key file to use when signing, verifying websocket reconnection
authentication.server.reconnection.keyfile=/etc/sysconfig/illumon.d/auth/priv-authreconnect.base64.txt

# The max duration (milliseconds) for a websocket reconnect key to be valid authentication.server.reconnection.period=600000 # The provider that this installation is using for groups (LDAP, MySQL, etc.).
# Depending on this value, additional properties will be required. IrisDB.groupProvider=mysql

DIS Web Server

DIS Server Property File:
/etc/sysconfig/illumon.d/resources/iris-db-dis.prop

DIS Web Server Settings:

# DIS web server
DataImportServer.webserver.enabled=true
DataImportServer.webserver.port=8086

# HTTP Basic Auth, SSL must be enabled when authentication is required DataImportServer.webserver.authenticationRequired=true DataImportServer.webserver.sslRequired=true

tls.keystore=/etc/sysconfig/illumon.d/auth/webServices-keystore.p12 tls.passphrase.file=/db/TempFiles/irisadmin/.webapi_passphrase

Query Web Server

Query Server Properties File:
/etc/sysconfig/illumon.d/resources/iris-query-server.prop

Query Web Server Settings:

# Query web server
RemoteQueryDispatcher.webserver.enabled=true
RemoteQueryDispatcher.webserver.port=8084

# HTTP Basic Auth, SSL must be enabled when authentication is required RemoteQueryDispatcher.webserver.authenticationRequired=true RemoteQueryDispatcher.webserver.sslRequired=true

tls.keystore=/etc/sysconfig/illumon.d/auth/webServices-keystore.p12 tls.passphrase.file=/db/TempFiles/irisadmin/.webapi_passphrase

Merge Web Server

Merge Server Property File:
/etc/sysconfig/illumon.d/resources/iris-merge-server.prop

Query Web Server Settings:

Last Updated: 06 July 2020 14:35 -04:00 UTC Deephaven v.1.20190117 (See other versions)