WebUI Version 4.1-3 for VSI OpenVMS IA-64 and x86-64

Update the system start-up procedure (optional)

After the installation has successfully completed, include the command displayed at the end of the installation procedure into SYSTARTUP_VMS.COM to ensure that WebUI is started when OpenVMS is booted.

Add identifiers to the rights database

To be able to modify user records, the SYSUAF logical name must be defined with a path to the SYS$UAF.DAT authorization file. If you have not previously done so on your system, define the logical name as follows before continuing:

$ DEFINE/SYSTEM SYSUAF SYS$SYSTEM:SYS$UAF.DAT

Access to WebUI functionality is controlled by OpenVMS rights identifiers. Users login to the WebUI using their standard OpenVMS username and password details; however in order to use the WebUI they must also have either the WEBUI_READ or the WEBUI_WRITE rights identifier, or they may be assigned both identifiers, in which case WEBUI_WRITE will take precedence. These identifiers must be added to the rights database before the WebUI can be used (note that the values assigned to the identifiers may differ in your environment; however the values of the identifiers are not important):

$ MCR AUTHORIZE 
UAF> ADD/IDENTIFIER WEBUI_READ 
%UAF-I-RDBADDMSG, identifier WEBUI_READ value %X8001121E added to rights
database
UAF> ADD/IDENTIFIER WEBUI_WRITE 
%UAF-I-RDBADDMSG, identifier WEBUI_WRITE value %X8001121F added to
rights database

Grant rights identifiers to users

Once the rights identifiers WEBUI_READ and WEBUI_WRITE have been added to the rights database, the identifiers should be granted as appropriate to any users that will be using the WebUI. For example, if user BIGGLES requires read and write access to WebUI functions, you would grant them the WEBUI_WRITE identifier as follows:

UAF> GRANT/IDENTIFIER WEBUI_WRITE BIGGLES 
%UAF-I-GRANTMSG, identifier WEBUI_WRITE granted to BIGGLES 
UAF> 

Configure the web server

If you have not modified the CivetWeb configuration for any other purpose and/or you do not have a previous installation of WebUI, then these configuration files can simply be copied as follows in order to establish an initial working WebUI configuration:

$ SET DEFAULT CIVETWEB$ROOT:[CONF]
$ COPY CIVETWEB^.CONF.WEBUI CIVETWEB.CONF
$ COPY SERVICES^.CONF.WEBUI SERVICES.CONF
$ COPY ALERT_IMAGES^.CONF.TEMPLATE ALERT_IMAGES.CONF
$ COPY THREADS^.CONF.TEMPLATE THREADS.CONF
$ COPY WEBUI^.CONF.TEMPLATE WEBUI.CONF

If you have made configuration changes for CivetWeb and do not wish to lose them, then it may be necessary to merge the WebUI-specific details with your existing configuration.

Specifically, the url_rewrite_patterns configuration setting must be defined as follows in CIVETWEB.CONF to ensure that the WebUI REST API operates correctly:

url_rewrite_patterns /api/**=/civetweb$root/htdocs/api/api.lua

Additionally, the following entries must be included in SERVICES.CONF to ensure that WebUI user authentication and authorization work correctly:

/login /civetweb$root/local/login.exe LoginHandler
/api/token /civetweb$root/local/login.exe ApiLoginHandler

It should be noted that the WebUI installation assumes that the document root for the web server is /civetweb$root/htdocs. If this is not the case for your configuration, then additional work will be required to ensure that the WebUI components are served correctly. VSI strongly recommends that you do not change the document root.

In order to finish the configuration of the embedded terminal, generate a "server.pem" certificate (follow the instructions available at https://github.com/civetweb/civetweb/blob/master/docs/OpenSSL.md#creating-a-self-signed-certificate). You must then place this certificate into the CIVETWEB$ROOT:[RESOURCES.CERT] directory.

Define logical names for reports

The reports feature of the WebUI allows you to create command procedures that generate HTML or textual output and make them known to the WebUI so that they can be run by users as and when required to gather various data that might be of interest with regard to the operation and configuration of the OpenVMS system. This reporting facility relies on the definition of the logical names WEBUI$REPORT_SCRIPTS and WEBUI$REPORT_FILES. Generally, these logical names would be defined in the system logical name table. However, this is not a strict requirement and they may be defined in other logical name tables so long as they are visible to the CivetWeb web server process.

The logical name WEBUI$REPORT_SCRIPTS defines the location of any script files (DCL command procedures) and the logical name WEBUI$REPORT_FILES specifies the location of report files create by the script. Note that it is possible to specify one or more directory paths when defining these logical names and all paths will be searched and displayed by the WebUI when listing available scripts and generated report files.

The WebUI installation includes a sample DCL report script that gathers considerable information about the configuration of the system. This script and its output can be executed and viewed via the WebUI by defining the WEBUI$REPORT_SCRIPTS and WEBUI$REPORT_FILES logical names as follows (you may wish to specify alternative locations that are more appropriate to your particular environment):

$ DEFINE/SYS WEBUI$REPORT_FILES CIVETWEB$ROOT:[HTDOCS.REPORTS.FILES]
$ DEFINE/SYS WEBUI$REPORT_SCRIPTS CIVETWEB$ROOT:[HTDOCS.REPORTS.SCRIPTS]

You should be sure to include these logical name definitions in your system start-up procedure to ensure that they are correctly defined whenever the system is rebooted.

SSL configuration (recommended)

The default CivetWeb installation provides only HTTP. If you wish to use HTTPS for the WebUI (recommended), then this will need to be configured. A detailed description of how to configure SSL/TLS and HTTPS is beyond the scope of this document; refer to the open-source CivetWeb documentation.

Restart the web server

Once you are happy with the configuration of CivetWeb you can cycle the web server to pick up the changes as follows:

$ @SYS$STARTUP:WEBUI$RESTART.COM

Try to access the web server at http://hostname:8082 to verify that it is operating correctly (replace "hostname" with the name or IP address of the OpenVMS server on which the CivetWeb web server has been installed and change the port number if necessary, as applicable to your installation).

Examine REST API documentation

You may also wish to examine the WebUI REST API documentation, which can be found at http://hostname:8082/webui/docs/api.html. This document describes in detail the operations that can be performed via the API, request and response formats, status codes, and so on. You can use this information to develop your own tools to automate various administrative tasks on your OpenVMS systems.

Configure alerts database (optional)

Alerts such as intrusions and device errors are stored in a database that by default resides in the CIVETWEB$ROOT:[HTDOCS.API.ALERTS] directory. The database is generally not large (less than 9000 blocks) and the default location will generally be acceptable. However, an alternative location may be defined by defining the logical name WEBUI$ALERTS_ROOT to specify the desired location for the database. In addition, the logical name WEBUI$ALERTS_KEEP_COUNT can be used to specify the maximum number of alert records that will be stored in the database. By default this value is 10000, which should be more than adequate for most systems. If the number of alert records exceeds this value, WebUI will purge the oldest alert records to maintain this maximum value. These two logical names should be defined in the system table to ensure that they will be visible to WebUI.