Domino Setup Web UI (domsetup)

Overview

The Domino Setup Web UI provides a simple web-based interface to initialize or extend a Domino server setup using the Domino One-Touch Setup (OTS) mechanism. It allows both interactive setup via browser and automated setup posting a OTS JSON file. domsetup.sh implements a Micro Web server written in Bash leveraging OpenSSL command line.

Core Functionality

  • Provides a web-based UI to perform the initial Domino server setup.
  • Supports passing a first or additional server OTS JSON file for automated setup.
  • Allows uploading an OTS JSON file directly via a single HTTP POST to /ots.
  • Automatically creates a self-signed TLS certificate if none is provided.
  • Uses the OpenSSL command-line tool for key and certificate handling.
  • Supports the @Base64: format to provide an encoded server.id inside the OTS JSON.
  • Can upload server.ids in a separate upload request or post.
  • Supports both Basic Authentication and Bearer Token Authentication for secured access.

How to enable the Setup Menu

To enable the setup web GUI set the following environment variable in your container configuarion.

DOMSETUP_ENABLED=1

Scenarios

First server setup via Web GUI

A first server does not need any existing other server nor configuration and can be setup via a simple to use Web GUI. The first server setup creates the cert.id, server.id, id-vault.id and the first server configuration.

Note: Resulting ID files should be safely copied for backup purposes.

First server setup using an OTS JSON file

A first server can also be automatically setup uploading or posting a full OTS JSON file.

Additional server setup using an OTS JSON file

Additional servers can only be configured using an OTS JSON file as well. Usually the admin server is specified as the existing server to copy system databases.

In addition to the connection to an existing server, the additional servers needs it’s server.id.

On Kubernetes the server.id might be provided using a secret. But specially on Docker it might be useful to just use a single OTS JSON file with an embedded server.id using the @Base64: ... syntax described below.

The server ID can be also uploaded in a separate post before uploading an OTS JSON file.

OTS Server.ID @Base64: Syntax

To pass a server.id to an OTS additional server setup it can be encoded in base64 and stored into the server.id field.

Standard OTS configuration:

"IDFilePath": "server.id"

Custom configuration passing a server.id

"IDFilePath": "@Base64: <base64-encoded-server.id>"

Command Line Usage

Uploading an OTS JSON via curl

To upload an OTS JSON file the file can just be posted to the /ots URL.

curl -v -k -X POST https://localhost/ots -H "Content-Type: application/octet-stream" --data-binary @ots.json -u admin:password

Uploading a server.id curl

In case the OTS JSON additional server setup does not provide a server.id embedded via @Base64: syntax, the server.id can also be uploaded before uploading the OTS JSON file.

To upload an OTS JSON file the file can just be posted to the /serverid URL.

curl -s -X POST https://volt.nashcom.org:8443/serverid -H "Content-Type: application/octet-stream" --data-binary @my-server.id -u admin:password

Result:

Domino Server.ID recreived: SHA256 3ae053c7af734c9f3b97f0ece3af211762519aa8449de8ecae1f96dd43cb13b5

Uploading a server.id curl with JSON response

Specially for automation a parsable result is important. The setup GUI JavaScript calculates the hash of the uploaded file and verifies it against the resulting JSON.

curl -s -X POST https://volt.nashcom.org:8443/serverid -H "Content-Type: application/octet-stream" -H "Accept: application/json" --data-binary @my-server.id -u admin:password | jq

Result:

{
  "status": "200",
  "text": "Domino Server.ID recreived",
  "sha256": "3ae053c7af734c9f3b97f0ece3af211762519aa8449de8ecae1f96dd43cb13b5"
}

Environment Variables

The following table describes all environment variables and their default values.

Environment variables are usually passed thru the container configuration, but stay in the container until it is recreated. Therefore DominoSetup can use an environment file to pass temporary configuration environment variables.

Define DOMSETUP_ENV_FILE to specify a mounted environment file. The default value for this file is /run/secrets/domsetup/env

Variable Description Default
DOMSETUP_HOST Hostname used for setup operations. System hostname
DOMSETUP_HTTPS_PORT HTTPS port the setup web UI listens on (must be >= 1024. 1352
DOMSETUP_USER Username for Basic authentication. admin
DOMSETUP_PASSWORD Password for setup user. Can point to a file path containing the password. /tmp/domsetup-key.pass
DOMSETUP_BEARER Bearer token for authentication (used instead of username/password). (unset)
DOMSETUP_CERT_FILE TLS certificate file to use for HTTPS. /tmp/domsetup-cert.pem
DOMSETUP_KEY_FILE Private key file associated with the TLS certificate. /tmp/domsetup-key.pem
DOMSETUP_KEY_FILE_PWD File containing the password for the TLS private key, if required. /tmp/domsetup-password.txt
DOMSETUP_CERTMGR_HOST Hostname of a Domino CertMgr server used to retrieve a matching TLS certificate. (unset)
DOMSETUP_CERTMGR_LOOKUP Name used to look up an existing TLS certificate in CertMgr (supports SANs). (unset)
DOMSETUP_JSON_FILE Path where the generated OTS JSON file will be stored. $DOMINO_AUTO_CONFIG_JSON_FILE
DOMSETUP_DOMINO_REDIR URL to redirect to after successful setup. /verse
DOMSETUP_WEBROOT Directory containing the setup web UI files. <script_dir>/domsetup-webroot
DOMSETUP_NOGUI Set to 1 to disable the web UI (Allow OTS JSON posts only). (unset)
DOMSETUP_TOKEN Shared setup token to validate server and authenticate client (nonce/HMAC) (unset)

Locations checked for Domino OTS JSON Template

The Domino One Touch JSON template is the base for a first server setup. It contains environment variables which are replaced by DominoSetup.

Domino OTS JSON files are searched in the following order:

  1. Directly specified DOMINO_AUTO_CONFIG_TEMPLATE_JSON_FILE
  2. /run/secrets/domsetup/DominoAutoConfigTemplate.json
  3. /local/notesdata/DominoAutoConfigTemplate.json
  4. /first_server.json
  5. /opt/nashcom/startscript/OneTouchSetup/first_server.json

Integrated MicroCA

The default locations are checked for a TLS key and certificate first. In case no TLS certificate and key is found, temporary self signed certificate is generated.

Kubernetes Deployment Notes

Specially on Kubernetes, certificates are often stored in secrets. The script first checks the following locations for TLS key, cert and password.

Default TLS Certificate/Key Locations Checked First

If no explicit paths are defined via environment variables, the following default paths are checked first:

/run/secrets/domsetup/tls.crt
/run/secrets/domsetup/tls.key
/run/secrets/domsetup/key.pass

Kubernetes-Specific Parameters

Variable Description Default
DOMSETUP_CERT_FILE Path to the mounted TLS certificate file. /run/secrets/domsetup/tls.crt
DOMSETUP_KEY_FILE Path to the mounted TLS private key file. /run/secrets/domsetup/tls.key
DOMSETUP_KEY_FILE_PWD Path to the mounted password file for the TLS key (optional). /run/secrets/domsetup/key.pass
DOMSETUP_ENV_FILE Optional file to specify environment variables /run/secrets/domsetup/env

These locations are typically populated via Kubernetes Secrets, mounted into the container to provide TLS certificates and private keys securely at runtime. They can be also used in Docker and other environments but have their defaults adopted to the K8s secrets namespace.

Domino OTS TLS Setup Integration

For a first server setup TLS Credentials can be imported from a PEM file. To write a file containing the DominoSetup private key and certificate chain define an export file via DOMSETUP_TLS_FILE.

Example:

DOMSETUP_TLS_FILE=/tmp/domsetup_tls.pem

Domino OTS configuration example

The following example also contains the configuration needed for password protected private keys.

 "security": {
      "TLSSetup": {
        "method": "import",
        "importFilePath": "/tmp/domsetup_tls.pem",
        "importFilePassword": "@Secret:/run/secrets/domsetup/key.pass"
      }
    }

Notes

  • Requires OpenSSL command line.
  • When no certificate or key file is provided, a self-signed certificate is generated automatically.
  • When using CertMgr integration, DOMSETUP_CERTMGR_HOST must be defined.
  • For non-interactive automation, set DOMSETUP_NOGUI=1 and POST the OTS JSON directly to /ots.
  • In Kubernetes environments, it is recommended to use mounted secrets for TLS keys and certificates under /run/secrets/domsetup/.

Implementation details

Port Setup

The default port to setup a server is 1352 used for a HTTPS connection. The main reason is that none privileged processes can’t bind to ports below 1024. The program uses for communication is the OpenSSL command-line which should not be authorized to listen to restricted ports.

Waiting for server setup to complete

After the setup completes the redirect needs to change to the standard HTTPS port (443). A redirect to another port would be denied by CORS. Therefore the JavaScript in complete.html waits for /domcfg.nsf/style.css to be available before using JavaScript load the specified login page. The name of the redirect URL is passed as a parameter and the link to the style sheet is derived from that name. Requesting image files and style sheets is not restricted by CORS and works cross servers.

Checking style.css in domcfg.nsf is a reliable way to detect the server has been started and the login form is available.

Domino Setup Verification (DOMSETUP_TOKEN)

The verification mechanism provides mutual authentication between client and server using a shared secret (DOMSETUP_TOKEN). It is based on a challenge–response model using one-time nonces and HMAC. During setup, the client connects to a remote server that may not have a trusted certificate.

Without additional verification:

  • the client cannot be sure it is talking to the intended server
  • the server cannot be sure the request originates from an authorized client

The HMAC-based verification ensures that both sides share a common secret and are therefore part of the same trusted setup.

Principle

Both client and server prove knowledge of the shared secret by computing an HMAC over a nonce provided by the other side.

A nonce is a randomly generated value that is used only once.

The HMAC is computed as:

HMAC = HMAC-SHA256(DOMSETUP_TOKEN, nonce)

Verification Flow

Verification is performed in both directions.

Server verification:

  • The server returns a nonce
  • The client computes an HMAC using the nonce
  • The server verifies the HMAC

Client verification:

  • The client sends a nonce
  • The server computes an HMAC using the nonce
  • The client verifies the HMAC

Why Nonces Are Used

Nonces ensure that each verification is unique.

Without a nonce:

  • a previously captured HMAC could be reused
  • authentication could be replayed

By using a one-time value:

  • each HMAC is valid only for a single exchange
  • replay attacks are prevented

Why a Shared Secret Is Used

The shared secret (DOMSETUP_TOKEN) is known only to the client and the intended server.

By verifying the HMAC:

  • both sides prove knowledge of the secret
  • no secret is transmitted over the network

This provides a simple and efficient way to establish trust without exchanging credentials.

Security Properties

The mechanism provides:

  • mutual authentication
  • protection against replay attacks
  • detection of incorrect or unintended endpoints

It does not provide:

  • protection against active man-in-the-middle attacks during initial connection
  • protection if the shared secret is compromised

Note: Trusted TLS/SSL certificates would provide better protection but would need public certs or trusted roots distibuted.

Summary

The verification mechanism ensures that client and server belong to the same trusted setup by proving knowledge of a shared secret using one-time nonces and HMAC, without exposing the secret itself.