The web interface is configured using the HTTPPORT and HTTPROOT keywords in the Hercules configuration file. The HTTPPORT keyword specifies the TCP/IP port Hercules listens on for HTTP requests and allows a limited degree of authorisation to be applied.
HTTPPORT <port> auth <username> <password>
Using privileged port numbers less than 1024 is not recommended. In order to enable Hercules to listen on privileged ports, it would be necessary to run Hercules with the VMS privilege SYSPRV which is not a good idea. This would expose the entire VMS system (or cluster if it is a member of a cluster) to complete takeover from outside via Hercules as most of the code in Hecules is not designed with any security in mind and Hercules has no clue at all about the VMS security model.
It is possible to limit access by specifying a username and password, however the security provided by this is negligible. The credentials are stored and sent in cleartext and there is no breakin logging or breakin evasion so anyone can keep trying an unlimited number of username and password combinations for as long as they like without any consequences until they succeed in breaking in. It is strongly advised to strictly limit access to the Hercules HTTP server to a secure local network. Even then, if external logins are allowed to the operating system running under Hercules, it is necessary to consider whether a malicious user could use this to run a web browser (such as Charlotte for example) to connect to the Hercules HTTP server to take over control of Hercules (and the entire VMS system or cluster if the Hercules is inadvisedly running with SYSPRV privilege.)
The HTTPROOT keyword must be specified to provide the location of some HTML and image files used by the HTTP server code. If this is not correctly specified, the HTTP server thread will fail to start.
HTTPROOT <path>
The path must be specified in unix notation, for example something like:
HTTPROOT /dka300/hercules/html/
It is also possible to use a logical name to specify the path, for example:
HTTPROOT HERCULESHTTPPATH
where HERCULESHTTPPATH is defined as follows:
$ DEFINE HERCULESHTTPPATH SYS$SYSDEVICE:[HERCULES.HTML]
Specifying the location of the Hercules HTML files in the Hercules configuration file can be tricky because Hercules parses the filename and accepts only characters used in typical Unix filenames. In particular, characters important to VMS file specifications such as $, [, ], _ and : may be excluded. Defining a logical name which contains none of these characters as outlined above can be used to work around this difficulty.
A race condition may randomly cause the following error to arise at Hercules startup:
HHCCF066E Invalid HTTPROOT: "/usr/local/share/hercules": no such file or directory
and the webserver to fail to start. This issue can be worked around by ensuring that the HTTPROOT statement is placed ahead of the HTTPPORT statement in the configuration file.