Nomad Web server connection options
Daniel Nashed – 25 January 2023 08:57:35
Nomad Web is a modern HCL client offering in form of a Progressive Web Application (PWA) running in your web browser.
In addition to Windows or Mac, it also works on Ubuntu and other Linux distributions! So there is finally a client offering for Linux clients again!
The Nomad Web application is installed on a server providing the required files for download.
Those files can be stored on a SafeLinx or Domino/Nomad Web server.
Your browser downloads the application and runs it locally in your browser.
It is basically a cross compile using the Notes basic client code.
Special connectivity requirements: WebSockets
Nomad Web clients cannot directly connect to your Domino servers using NRPC with a standard TCP/IP connection.
Because the client is in a browser it uses modern web technologies to connect to the server.
This brings new advantages but also new challenges.
Standard HTTPS connections are not a stateful network connection.
You can send multiple HTTPS request over the same connection and have a TLS session.
But it isn't a TCP/IP network session in the way NRPC would require it.
Modern web technology supports so called web-sockets to allow stateful network connections for web applications.
Nomad Web tunnels the NRPC session with all it's transactions via WebSockets to Domino.
But because Domino itself does not understand WebSocket NRPC connections, you need a server component to translate the network packages.
SafeLinx Server
Until the Nomad Server was released recently a HCL SafeLinx server was the only network component allowing to bridge the protocols.
You don't need to separate license a SafeLinx server. But it is a separate server component, which is not always intuitive to deploy.
Therefore the HCL Domino Container Community project provides an easy to configure SafeLinx container --> https://opensource.hcltechsw.com/domino-container/safelinx/
The container is easy to configure specifying just a couple of environment variables instead of using the old fashioned Java admin client application.
SafeLinx offers a connection module specially designed for Nomad Web bridging the WebSocket protocol to NRPC.
It also allows you to define target Domino servers and the corresponding internet host name.
Safelinx handles the TLS connection and tunnels the NRPC connection to the right target host.
In addition to a static configuration mapping Domino server names to host names to connect to, SafeLinx can leverage a LDAP connection to a Domino server to map server names dynamically.
The SafeLinx container image uses this type of configuration to avoid complex configurations.
"Server Name Indication"
SafeLinx receives all the traffic over the same HTTPS connection using a single TLS/SSL certificate on a single IP address to dispatch all the traffic acting as a secure reverse proxy.
The first NRPC package connecting the client to the server contains the target Domino server name in the first network package.
SafeLinx uses this Domino name to map the session to the right Domino server using it's FQDN (lookup in it's own configuration or via LDAP from a Domino server).
The resulting stateful WebSocket connection is handled by the SafeLinx server.
This means you can use a single SafeLinx server to connect to multiple Domino servers in parallel.
SafeLinx ensures the dispatching and handles the stateful WebSocket connection tunneling the NRPC socket connection for you.
Nomad Web Server
Because not every customer wants to install a separate SafeLinx server, HCL came up with a new server component called "Nomad Web Server".
A Nomad Web Server consists mainly on two parts.
Let's have a look at the two binary files shipped with the Windows version:
nwsp-win.exe
Is a Node.js application compiled into a single executable. Node.js provides native WebSocket protocol already and a Node.js application is a low overhead way to implement a way to bride protocols.
All connections are going thru this component and will be routed to the target Domino server directly.
You can run this component separately from your Domino server and configure all settings in a YAML file.
In this case the YAML configuration contains settings for the TLS certificate/key and also mapping configuration for your Domino servers.
Very similar to what SafeLinx provides with a static configuration.
nnomad.exe
The more convenient way is to use this component directly on a Domino server in combination with a Nomad servertask.
This server task is started on a Domino server running on the same host.
Both components talk to each other using a private TLS connection.
The Nomad servertask provides configuration information to connect to the own Domino server it is running on.
And also provides connectivity information to other Domino servers in the Domain.
This is comparable to what SafeLinx provides using the LDAP lookup.
Both components work hand in hand and glue together. You can even leverage existing TLS Credentials in your Domino Certificate store (certstore.nsf).
The only configuration needed in this case is the hostname for the certificate specified in a notes.ini setting:
NOMAD_WEB_HOST=domino.acme.com
This would also work for wild-card certificates like this:
NOMAD_WEB_HOST=*.acme.com
The TLS Credentials document just must be assigned to the Domino server to have Domino decrypt the private key.
And it needs to be a unique match in your certstore.nsf.
Using a Load Balancer or Secure Reverse Proxy in front of Nomad Web with SNI
Nomad Web Server and SafeLinx work very similar in handling the connection and establishing the session.
Both also handle the mapping to the right Domino server in the same way analyzing the first NRPC package.
But what if you want to put NGINX or another load balancer in front of your server?
Note: I would even advice you to add a robust load balancer like NGINX as a first line of defense in front of any Node.js application like Nomad Server.
Because the websocket protocol is HTTPS based, most modern load-balancers and reverse proxies can handle the HTTPS session and even dispatch traffic over server name indication (SNI).
This means you can run those HTTPS sessions on the same IP and TLS port 443 you are using for other connections.
The only special requirement for WebSockets is a configuration which supports the WebSocket upgrade header.
You find a sample configuration for NGINX in the Nomad Web Server documentation referenced below.
Conclusion and additional tips
This blog post is mainly intended to give you and overview and not an instruction how to setup Nomad Web.
Specially for intranet environments the Nomad Server is an easy to install component, which helps you to deploy Nomad Server quite quickly.
We added the Nomad Server package to the Domino community image as an add-on, which can be automatically build into the Domino server image --> https://opensource.hcltechsw.com/domino-container/.
Still even for intranet deployments I would always add a secure load balancer in front of the Nomad server.
SafeLinx in contrast is already a secure load-balancer written in C on a more robust stack.
But both options provide you with the required WebSocket connectivity for Nomad Web.
References for more details:
Nomad Web Documentation
https://help.hcltechsw.com/nomad/1.0_web/nomad_web.html
Nomad Server Documentation
https://help.hcltechsw.com/nomad/1.0_admin/nomadserver_domino.html
WebSocket Wikipedia
https://en.wikipedia.org/wiki/WebSocket
RFC6455 The WebSocket Protocol
https://datatracker.ietf.org/doc/html/rfc6455
The WebSocket API (WebSockets)
https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
- Comments [9]
![[HCL Domino]](../lotus-domino.gif){kind=small}
![[Domino on Linux]](../domino-linux.gif){kind=small}
![[Nash!Com]](../nashcom.gif){kind=small}
![[Daniel Nashed]](../daniel-nsh.gif){kind=small}