Difference between revisions of "Tomcat (CSWS JAVA) - Easy Installation Guide"

From VSI OpenVMS Wiki
Jump to: navigation, search
(Created page with "This is an easy installation guide for setting up a Tomcat web server. As such, it will not go into explicit detail or offer any lengthy explanations. Rather, it should functi...")
Line 1: Line 1:
This is an easy installation guide for setting up a Tomcat web server. As such, it will not go into explicit detail or offer any lengthy explanations. Rather, it should function as a check list to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).
This is an easy installation guide for setting up a Tomcat web server. As such, it will not go into explicit detail or offer any lengthy explanations. Rather, it should function as a check list to make sure nothing important was missed during the base install. For more guides like this, check out the [https://wiki.vmssoftware.com/Open_Source_Software_for_OpenVMS Open Source Software for OpenVMS] page.

Latest revision as of 07:13, 20 October 2021

This is an easy installation guide for setting up a Tomcat web server. As such, it will not go into explicit detail or offer any lengthy explanations. Rather, it should function as a check list to make sure nothing important was missed during the base install. For more guides like this, check out the Open Source Software for OpenVMS page.


Before Tomcat is installed, make sure these pre-requisites are met for your server:

  • OpenVMS Integrity servers Version 8.4-1H1 or higher.
  • VSI’s OpenJDK 8 Development Kit V1.8 Update 222b or later.
***Please note: HPE Java™ JDK V1.8u_144* is not recommended.***
***In addition, HPE Java™ JDK V1.6 and earlier versions will not work and are not supported with VSI’s CSWS_JAVA V8.5-50A .***
  • Another requirement is that you install CSWS_JAVA on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Tomcat on is ODS-5 enabled is to use the following command on a mounted disk:
$ show devices $1$YOURDISK: /full

Towards the bottom of the output, you should see in plain text

Volumes Status: ODS-5, ...
  • Although not required, it is recommended that you have a recent version of the Apache web server (CSWS) installed on your system as well as a recent version of OpenSSL (SSL111). Apache will be used to provide a CGI example and OpenSSL will be used to set up HTTPS for the Tomcat web server.

Before you install VSI’s CSWS_JAVA V8.5-50a software, if you are running any existing, earlier versions of Tomcat on your system, you will be required to

  • Backup your important files. Most importantly, make sure to save a copy of the following configuration files. After the upgrade, you can use these files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation.
  • Shut down the Tomcat webserver with the command
$ @sys$startup:tomcat$shutdown.com
  • Remove Tomcat with the command
$ product remove csws_java

To completely remove Tomcat, follow the instructions in the last section of this document.


To install Tomcat, download the installation kit for CSWS_JAVA (Tomcat) to your server and read through the release notes before starting the installation. Then follow these steps:

  • Unpack the kit inside your chosen source directory with
  • Install Tomcat using the PCSI application.
$ product install csws_java

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.openJDK8u222b]VSI
-I64VMS-CSWS_JAVA-V0805-50A-1.PCSI$COMPRESSED;2 succeeded

The following product has been selected:
    VSI I64VMS CSWS_JAVA V8.5-50A          Layered Product

Do you want to continue? [YES]

Configuration phase starting ...

You will be asked to choose options, if any, for each selected product and for
any products that may be installed to satisfy software dependency requirements.

Configuring VSI I64VMS CSWS_JAVA V8.5-50A

    VMS Software Inc. & The Apache Software Foundation.

Minimum Java software version not found on system, abort installation.

This kit requires Java 1.8 for OpenVMS

Terminating is strongly recommended.  Do you want to terminate? [YES] NO

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
    VSI I64VMS CSWS_JAVA V8.5-50A          DISK$SYS1:[VMS$COMMON.]

Portion done: 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been installed:
    VSI I64VMS CSWS_JAVA V8.5-50A          Layered Product


    Post-installation tasks are required.

    To start the Tomcat web server at system boot time, add the following

        $ if f$search("file'") .nes. "" then @'file'

    To shutdown Tomcat at system shutdown time, add the following lines to

        $ if f$search("file'") .nes. "" then @'file'

    Note that default installation uses the SYSTEM account to run the the
    Web server process. It is recommended that you run the web server as
    using a less privileged account. This may be done by supplying the
    account name as a parameter to tomcat$startup.com or by defining the
    logical name tomcat$user as the desired account name. It is also
    recommended that you  change the tomcat$root:[000000...] directory tree
    ownership to this account.
%PCSIUI-I-COMPWERR, operation completed after explicit continuation from errors

The post-installation tasks listed above are taken care of in the coming configuration portion of this installation guide.

Comment for the highlighted part of the installation output above: If you have OpenJDK8 installed on a system that previously has not had JAVA installed, you will want to answer no to this question and allow the installation to complete. It will complete successfully. This will be fixed in a future release of VSI CSWS_JAVA.


There is a lot to the configuration of Tomcat. For this configuration guide, it is assumed that you already have CSWS (Apache web server) installed on your server. Although this is no longer a requirement for versions CSWS_JAVA V8.5-50 and later, the two are often used in tandem. It is further assumed that you also have VSI SSL 1.1.1 (OpenSSL) or later installed so that you can set up HTTPS for Tomcat.

Creating java$80_setup.com

If you have OpenJDK8 installed on your system without having a version of Java installed previously, you might be missing the file SYS$MANAGER:JAVA$80_SETUP.COM – without this file, Tomcat will not start. This issue will be fixed in a future release of Tomcat. The file exists in the OPENJDK8 top directory and can be copied over to SYS$MANAGER or it can be created manually. It should look like this:

$ @sys$sysdevice:[sys0.syscommon.openjdk$80.com]java$setup.com 'P1'
$ exit

Make sure that the path to JAVA$SETUP.COM matches your configuration.

Setting System Parameters

The next natural step in the installation is to create the username TOMCAT$WWW in the SYSUAF. Before doing so, however, it is a good idea to make sure that the system parameters will allow the settings chosen for the Tomcat user account. The table below shows the quotas that will be used in the creation of TOMCAT$WWW. They should be adequate for most purposes; although, resource usage should always be monitored closely and quotas adjusted as necessary.

Maxjobs:         0  Fillm:     32767  Bytlm:       3000000
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:            0
Maxdetach:       0  BIOlm:      1024  JTquota:       40000
Prclm:         100  DIOlm:      1024  WSdef:        100000
Prio:            4  ASTlm:       300  WSquo:        200000
Queprio:         4  TQElm:       400  WSextent:     800000
CPU:        (none)  Enqlm:     32767  Pgflquo:    10000000

The system parameters of importance are the channel count CHANNELCNT (which caps the file limit parameter FILLM) and the working set maximum WSMAX (which caps the working set extent WSEXTENT).

  • First, enter the System Generation Utility and have a look at the two parameters by entering the following commands.
$ set default sys$system
$ mcr sysgen
Parameter Name            Current    Default     Min.       Max.   Unit  Dynamic
--------------            -------    -------   -------    -------  ----  -------
CHANNELCNT                  32767        512        64      65535 Channels
Parameter Name            Current    Default     Min.       Max.   Unit  Dynamic
--------------            -------    -------   -------    -------  ----  -------
WSMAX                      900000     131072     16384  134217728 Pagelets
 internal value             56250       8192      1024    8388608 Pages
  • The current CHANNELCNT should have a value that is at least equal to your chosen FILLM value. If required, CHANNELCNT can safely be set to its maximum value of 65535.
  • The current value of WSMAX must be set equal to or greater than the chosen value of WSEXTENT. In the example output above the current value of WSMAX is set to 900000 and thus slightly greater than the chosen value of 800000 for WSEXTENT. You should set this value according to your own environment, which may require it to be higher or lower.
  • Use the following commands to set the system parameters, changing the values as necessary.

Note: It is important to note that the system parameters CHANNELCNT and WSMAX are not dynamic (otherwise the letter D would be present in rightmost column in the example output earlier). Therefore, the system must be rebooted for the parameters to change.

  • Another important matter to take into consideration is that running AUTOGEN using the FEEDBACK option might alter the system parameters you set directly in SYSGEN. To ensure that the parameters will not be altered by AUTOGEN, you should also specify the parameters in the file MODPARAMS.DAT. One option is to set MIN_CHANNELCNT and MIN_WSMAX if you want to make it possible for AUTOGEN to set higher values than the CHANNELCNT and WSMAX needed for Tomcat. For more details, see the OpenVMS System Management Manual.
  • Bear in mind that the quotas proposed in the table are merely suggestions, although they are a good starting point. If the number of page faults for the Tomcat process grows larger than 50000, you may wish to increase the quotas for the TOMCAT$WWW account. To optimize the performance of Tomcat, you can change the values of WSQUO, WSEXTENT, and PGFLQUO together in increments of 50000, 100000, and 1000000, respectively, while making sure that WSMAX is still greater than or equal to WSEXTENT. Both too much and too little resources can have a negative impact on performance.

Creating TOMCAT$WWW Username in SYSUAF

Setting up TOMCAT$WWW in the SYSUAF can be done by following these instructions.

  • Enter the following command to open the SYSUAF:
$ set default sys$system
$ mcr authorize
  • If an account for Apache already exists on your web server, you can use APACHE$WWW to create the user TOMCAT$WWW by copying and pasting (choosing your desired UIC, highlighted below) the command shown below. The resources given to the TOMCAT$WWW account are the same recommended initial values as those specified in the table in the previous section (you can copy the command line by line by including the dash – press Enter to start a new line).
UAF> copy apache$www tomcat$www /uic=[555,555] /dir=000000 /device=tomcat$root -
_UAF> /account=tomcat /prclm=100 /fillm=32767 /biolm=1024 /diolm=1024 /astlm=300 -
_UAF> /tqelm=400 /enqlm=32767 /bytlm=3000000 /jtquota=40000 /wsdef=100000 -
_UAF> /wsquo=200000 /wsextent=800000 /pgflquo=10000000 /batch –
_UAF> /defpr=(sysprv,bypass,impersonate) 
%UAF-I-COPMSG, user record copied
%UAF-W-DEFPWD, copied or renamed records must receive new password
%UAF-I-RDBADDMSGU, identifier TOMCAT$WWW value [000555,000555] added 
to rights database
  • The TOMCAT$WWW username should now look something like this:
UAF> show tomcat$www

Username: TOMCAT$WWW                      Owner:
Account:  TOMCAT                           UIC:    [555,555] ([TOMCAT$WWW])
CLI:      DCL                              Tables: DCLTABLES
Default:  TOMCAT$ROOT:[000000]
Flags:  LockPwd DisNewMail DisMail DisReport
Primary days:   Mon Tue Wed Thu Fri
Secondary days:                     Sat Sun
Primary   000000000011111111112222  Secondary 000000000011111111112222
Day Hours 012345678901234567890123  Day Hours 012345678901234567890123
Network:  ##### Full access ######            ##### Full access ######
Batch:    ##### Full access ######            ##### Full access ######
Local:    -----  No access  ------            -----  No access  ------
Dialup:   -----  No access  ------            -----  No access  ------
Remote:   -----  No access  ------            -----  No access  ------
Expiration:            (none)    Pwdminimum:  6   Login Fails:     0
Pwdlifetime:         90 00:00    Pwdchange:      (pre-expired)
Last Login:            (none) (interactive),            (none) (non-interactive)
Maxjobs:         0  Fillm:     32767  Bytlm:       3000000
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:            0
Maxdetach:       0  BIOlm:      1024  JTquota:       40000
Prclm:         100  DIOlm:      1024  WSdef:        100000
Prio:            4  ASTlm:       300  WSquo:        200000
Queprio:         4  TQElm:       400  WSextent:     800000
CPU:        (none)  Enqlm:     32767  Pgflquo:    10000000
Authorized Privileges:
Default Privileges:
  • If an account for Apache does not exist, you can create the account from scratch like so:
UAF> add tomcat$www /uic=[555,555] /dir=000000 /device=tomcat$root /account=tomcat -
_UAF> /flags=(dismail,disnewmail,disreport,lockpwd,nodisuser) /lgicmd=login -
_UAF> /prclm=100 /fillm=32767 /biolm=1024 /diolm=1024 /astlm=300 /tqelm=400 -
_UAF> /enqlm=32767 /bytlm=3000000 /jtquota=40000 /wsdef=100000 /wsquo=200000 - 
_UAF> /wsextent=800000 /pgflquo=10000000 /nolocal /nodialup /noremote –
_UAF> /defpr=(sysprv,bypass,impersonate)
%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier TOMCAT$WWW value [000555,000555] added to rights database

Defining Required Tomcat Logicals

Having created the TOMCAT$WWW username, it is now a good time to create the logicals needed to run Tomcat. You can do so by running the command procedure shown below from a sufficiently privileged account.

$ @sys$manager:tomcat$define_logicals.com

Running this file will create the required logical TOMCAT$ROOT, which is needed for Tomcat to run. It will also give you easy access to the Tomcat root directory. $ show logical *tomcat*








Automatic Start-up and Shutdown Commands

In this section we will set up commands for Tomcat to automatically shut down and start back up when the system is rebooted.

  • Edit the file SYS$MANAGER:SYSTARTUP_VMS.COM and insert the following lines towards the bottom of the file to start Tomcat under the TOMCAT$WWW account. Make sure to specify the correct node name highlighted below.
$    if f$search("SYS$STARTUP:TOMCAT$STARTUP.COM") .nes. ""
$    then
$    endif
Note:There should be no line break for the $ SUBMIT command above. If you cannot fit the entire command on your screen, consider setting a wider terminal width. For example:
$ set terminal /width=132
  • Edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the following lines:
$ if f$search("''file'") .nes. "" then @'file'

Setting File Ownership and Permissions

Since the username TOMCAT$WWW has been created, you can set it as owner to Tomcat’s files in addition to specifying the file permissions.

  • First, set the file ownership for the Tomcat root directory- the location of which you can find by doing a $ SHOW LOGICAL TOMCAT$ROOT. Then set Tomcat as owner for the root directory as well as the entire directory structure. Make sure that you use the UIC you specified for TOMCAT$WWW (highlighted in yellow).
$ show logical tomcat$root

$ set file /owner=[555,555] tomcat.DIR /log

$ set file /owner=[555,555] [.tomcat...]*.*;* /log
  • Second, set the file permissions. First for the root directory and then for the rest of the directory structure.
$ set file /prot=(S:RWE,O:RWED,G,W) tomcat.DIR /log
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 file protection changed to S:RWE,O:RWED,G:,W:

$ set file /prot=(S:RWE,O:RWED,G,W) [.tomcat...]*.*;* /log
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON.tomcat]bin.DIR;1 file protection changed to 
changed to S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON.tomcat]conf.DIR;1 file protection changed to 
  • To verify that the owner and file protections were set correctly, you can issue the command

$ dir [.tomcat] /owner /prot

Directory YOURDISK:[SYS0.SYSCOMMON.tomcat]

bin.DIR;1            [TOMCAT$WWW]                     (RWE,RWED,,)
BUILDING.txt;1       [TOMCAT$WWW]                     (RWE,RWED,,)
conf.DIR;1           [TOMCAT$WWW]                     (RWE,RWED,,)
CONTRIBUTING.md;1    [TOMCAT$WWW]                     (RWE,RWED,,)
lib.DIR;1            [TOMCAT$WWW]                     (RWE,RWED,,)
LICENSE.;1           [TOMCAT$WWW]                     (RWE,RWED,,)
logs.DIR;1           [TOMCAT$WWW]                     (RWE,RWED,,)
NOTICE.;1            [TOMCAT$WWW]                     (RWE,RWED,,)
README.md;1          [TOMCAT$WWW]                     (RWE,RWED,,)
RELEASE-NOTES.;1     [TOMCAT$WWW]                     (RWE,RWED,,)
RUNNING.txt;1        [TOMCAT$WWW]                     (RWE,RWED,,)
sbin.DIR;1           [TOMCAT$WWW]                     (RWE,RWED,,)
temp.DIR;1           [TOMCAT$WWW]                     (RWE,RWED,,)
webapps.DIR;1        [TOMCAT$WWW]                     (RWE,RWED,,)
work.DIR;1           [TOMCAT$WWW]                     (RWE,RWED,,)

LOGIN.COM for Tomcat

To define the ODS-5 filesystem, set the extended filename parsing required by both Java and Tomcat, and define the logicals needed to support the runtime of Tomcat, you need to make some changes to the LOGIN.COM file of Tomcat.

  • Create the file TOMCAT$ROOT:[000000]LOGIN.COM and add these lines:
$ ! Login.Com for Tomcat Web Server
$ !
$ ! exit
$ !
$ set process/parse =extend                     ! ODS-5 Support
$ set process/units = bytes                     ! ODS-5 Support (optional)
$ DEFINE DECC$FILE_SHARING "TRUE" -             ! Used to aid in Apache startup optimization
$ DEFINE DECC$ACL_ACCESS_CHECK "TRUE"           ! Ensure that ACL's are being honored by CRTL
$ DEFINE DECC$ALLOW_REMOVE_OPEN_FILES "TRUE"    ! Use for Removing Open Files during shutdown
$ DEFINE JAVA$FILENAME_CONTROLS "8"             ! Needed for Filename attributes for OpenVMS.
$ DEFINE JAVA$FSYNC_INTERVAL "50"               ! Flush RMS Buffers.
$ DEFINE SYS$SCRATCH TOMCAT$ROOT:[000000.TEMP]  ! Needs to point to ODS-5 formatted device

Starting Tomcat

It is now possible to start Tomcat under the TOMCAT$WWW account. As explained towards the bottom of the installation output it is for security reasons recommended that you run Tomcat under a less privileged account than the system account, which is used by default when SYS$STARTUP: TOMCAT$STARTUP.COM is executed directly (assuming you are logged in as system or under a privileged user account).

  • Before starting Tomcat, first edit the file SYS$STARTUP:TOMCAT$DEFS_LOCAL.COM and insert the lines shown below so that the logical TOMCAT$USER is defined during start-up. It should look something like this:
$! Add any site-specific logical definitions here
$ define /system tomcat$user tomcat$www
$ who = f$trnlnm("tomcat$user")
$ write sys$output "tomcat$user is: ''who'"
[End of file]
  • Next, use the system account to submit the following command to start Tomcat under the TOMCAT$WWW account. The account you use to do this must have the appropriate privileges.
$ submit /user=tomcat$www /queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
Unless any errors have been made up until this point, you should be able to access the Tomcat webserver in your browser by connecting to port 8080. If you cannot connect, it advisable that you have a look at the log files in TOMCAT$ROOT:[LOGS] to see where things went wrong. If your browser refuses to connect to your web server via HTTP, it might be a good idea to clear the cache to make sure you are loading the page anew. Remember that you must restart Tomcat after making your configuration changes in order for them to be implemented.
If Tomcat does start, you can make sure that it is running under the correct username and with the correct privileges with the commands below.
$ show system
00000444 APACHE$TOMCAT   HIB      6   128324   0 00:00:59.89     25597  28525 M
$ show proc/id=444 /priv

26-MAY-2021 02:29:44.39   User: TOMCAT$WWW       Process ID:   00000444
                          Node: YOURNODE         Process name: "APACHE$TOMCAT"

Authorized privileges:

Process privileges:
 BYPASS               may bypass all object access controls
 IMPERSONATE          may impersonate another user
 NETMBX               may create network device
 SYSPRV               may access objects via system protection
 TMPMBX               may create temporary mailbox

Process rights:
 TOMCAT$WWW                        resource
  • If you want to shut down Tomcat, you can do so with the following command from a privileged account.
$ @sys$startup:tomcat$shutdown.com

Enabling Access to Tomcat Manager and Host Manager

To use the Tomcat Manager-GUI and Host Manager-GUI, you need to set them up. You can do so by following the instructions below.

  • Edit the file TOMCAT$ROOT:[CONF]tomcat-users.xml. Add the highlighted lines to the very bottom of the document and make sure to substitute the example passwords with your own.
$ edit tomcat$root:[conf]tomcat-users.xml


  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <user username="tomcat" password="<must-be-changed>” "roles="tomcat"/>
  <user username="both" password="<must-be-changed>" roles="tomcat,role1"/>
  <user username="role1" password="<must-be-changed>" roles="role1"/>
<!-- -->
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <role rolename="manager-gui"/>
  <role rolename="admin-gui"/>
  <role rolename="manager-script"/>
  <role rolename="admin-script"/>
  <user username="admin" password="admin" roles="admin-gui,manager-gui"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>
  <user username="role1" password="tomcat" roles="role1"/>
<user username="tcscript" password="tomcat" roles="manager-gui,manager-script,admin-script"/>
[End of file]
  • To allow access to Admin and Manager, permissions must be set to allow for connections. Edit these two files:
Then add the comment delimiters highlighted in the lines below to both context.xml files, so that the relevant lines read

<Context antiResourceLocking="false" privileged="true" >
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
     allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />
  <Manager sessionAttributeValueClassNameFilter=

  • Finally, restart Tomcat with the commands below.
$ @sys$startup:tomcat$shutdown.com
$ submit /user=tomcat$www /queue=sys$batch /parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com

Enable CGIs in Tomcat

For CGI scripts to work with Tomcat they must first be set up, which these instructions will show you how to do. They will also show you how to use Apache to create working CGI example.

CGI Configuration

  • Edit the file TOMCAT$ROOT:[CONF]web.xml and make the changes highlighted below in the code for <servlet-name>cgi</servlet-name>. Make sure that you uncomment this section by removing the comment delimiter “-->” at the bottom and adding it to the top.
$ edit tomcat$root:[conf]web.xml


<!-- -->

Down further in the same file, uncomment the following lines for the CGI Gateway Servlet by removing the comment delimiter “-->” at the bottom and adding it to the top.

<!-- -->

  • In addition, edit the file TOMCAT$ROOT:[CONF]context.xml and add the highlighted portions below to the <Context>.
$ edit tomcat$root:[conf]context.xml


<Context reloadable="true" privileged="true">


CGI Example

  • Create the directory structure TOMCAT$ROOT:[WEBAPPS.CGI.WEB-INF.CGI]. While in TOMCAT$ROOT, run the following command.
$ create /dir [.webapps.cgi.web-inf.cgi] /log
%CREATE-I-CREATED, TOMCAT$ROOT:[000000.webapps.cgi.web-inf.cgi] created
  • The files TEST-CGI-VMS.EXE and TEST-CGI-VMS.CGI need to be copied over from APACHE$ROOT: [CGI-BIN] to TOMCAT$ROOT:[WEBAPPS.CGI.WEB-INF.CGI].
$ dir apache$root:[cgi-bin]



Total of 2 files.

$ copy /log apache$root:[cgi-bin]test-cgi-vms.exe – 
_$ tomcat$root:[webapps.cgi.web-inf.cgi]test-cgi-vms.exe
[webapps.cgi.web-inf.cgi]test-cgi-vms.exe;1 (13KB)

$ copy /log apache$root:[cgi-bin]test-cgi-vms.com -
_$ tomcat$root:[webapps.cgi.web-inf.cgi]test-cgi-vms.cgi
[webapps.cgi.web-inf.cgi]test-cgi-vms.cgi;1 (4KB)
Set the correct file ownership and protection and make sure to use the correct UIC for the TOMCAT$WWW user account.
$ set file/owner=[555,555] tomcat$root:[webapps...]*.*;* /log
%SET-I-MODIFIED, TOMCAT$ROOT:[webapps.cgi]web-inf.DIR;1 modified

$ set file/prot=(S:RWE,O:RWED,G,W) tomcat$root:[webapps...]*.*;* /log
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]cgi.DIR;1 file protection changed to S:RW
And as a last step, make sure that ownership and permissions are correct.
$ dir /sec tomcat$root:[webapps.cgi.web-inf.cgi]

Directory TOMCAT$ROOT:[webapps.cgi.web-inf.cgi]

test-cgi-vms.cgi;1   [TOMCAT$WWW]                     (RWE,RWED,,)
test-cgi-vms.exe;1   [TOMCAT$WWW]                     (RWE,RWED,,)

Total of 2 files.
  • Create the file TOMCAT$ROOT:[WEBAPPS.CGI]index.html.
$ create tomcat$root:[webapps.cgi]index.html
(Press Ctrl-Z)
  • Next, you need to change its record format from Variable Length to STREAM_LF. One way to do this is with the file STREAM_LF.FDL, which you can create on your own. Use the $ EDIT command to create the file and then copy and paste the contents shown below. Press Ctrl-Z to exit the editor.
$ edit tomcat$root:[000000]STREAM_LF.FDL
        ALLOCATION              4
        BEST_TRY_CONTIGUOUS     yes
        EXTENSION               0
        ORGANIZATION            sequential
        BLOCK_SPAN              yes
        CARRIAGE_CONTROL        carriage_return
        FORMAT                  stream_LF
        SIZE                    0
[End of file]
Using this file, the conversion can now be performed with
$ convert /fdl=tomcat$root:[000000]stream_lf.fdl -
_$ tomcat$root:[webapps.cgi]index.html tomcat$root:[webapps.cgi]
This will create a new version of the file for which you can verify that the record format is correct with the command below.
$ dir /full tomcat$root:[webapps.cgi]index.html;2
Record format:      Stream_LF, maximum 0 bytes, longest 0 bytes
  • Make sure that the ownership and permissions of the index.html file are as follows.
$ dir /sec tomcat$root:[webapps.cgi]

Directory TOMCAT$ROOT:[webapps.cgi]

index.html;2         [TOMCAT$WWW]                     (RWE,RWED,,)
index.html;1         [TOMCAT$WWW]                     (RWE,RWED,,)
web-inf.DIR;1        [TOMCAT$WWW]                     (RWE,RWED,,)

Total of 3 files.
  • Edit the file TOMCAT$ROOT:[WEBAPPS.CGI]index.html, using an editor of your choosing, and insert the following HTML code into the empty file.
$ edit index.html
    <TITLE>CGI Application Example</TITLE>
    <link href="hpweb_styles_win_ie6.css" rel="stylesheet"
    <style type="text/css">
    .style3 {font-size: 12px}
    .style4 {font-size: 12px; color: #003366;
    <h2> <class="colorE7E7E7bg color003366"><strong> CGI Application Example</strong></h2>
    <h3> <class="colorE7E7E7bg color003366"><strong> CGI from the TOMCAT Server</strong></h3></br>
    <a href="">CGI-EXE from the TOMCAT Server. </a><br>
    <a href="">CGI-COM from the TOMCAT Server. </a><br>
    <h3> <class="colorE7E7E7bg color000066"><strong>CGI from the APACHE Web Server</strong> </h3></br>
    <a href="">CGI-EXE from the APACHE Web Server.</a></br>
    <a href="">CGI-COM from the APACHE Web Server. </a></br>
      Or you can Use the non-SSL URL of: and the non-SSL URL of:
      Thank you! /VSI Support Team </span>
[End of file]
Note: Make sure to change the IP addresses and port numbers highlighted in yellow to match your current configuration.
  • Create the file TOMCAT$ROOT:[webapps.cgi.web-inf]web.xml, convert its record format to STREAM_LF, and make sure that the file owner and file permissions are set correctly. Then edit the new converted file and insert the following lines.
$ edit TOMCAT$ROOT:[webapps.cgi.web-inf]web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
  <display-name> A VSI CGI Example... </display-name>
    Used as an example for showing how CGI apps can work with Tomcat V8.5-50
[End of file]
  • With this, CGIs should now be working with Tomcat. You can test the examples that were set up in the index.html file by visiting your specified location in a web browser. Since HTTPS has not yet been set up, you will only be able to connect using HTTP. Remember that you must restart Tomcat for the configuration changes to be detected.

Enable Functionality for Automatically Deploying WAR Files

To enable the automatic deployment of WAR files, follow the instructions below. Be careful, however, about enabling automatic deployment in a production environment as you will run the risk of unintentionally deploying WAR files and, by doing so, overwrite important changes made to the deployed files.

  • Edit the file TOMCAT$ROOT:[CONF]server.xml. Close to the bottom of the, add the highlighted line shown below in the specified location.
$ edit tomcat$root:[conf]server.xml


<Host name="localhost"  appBase="webapps"
          unpackWARs="true" autoDeploy="true">
<DefaultContext reloadable="true"/>


Set Up Tomcat HTTPS Support with OpenSSL

In this part of the configuration, we will first create a self-signed certificate with OpenSSL and then change the configuration settings to allow for HTTPS connections to the server. This section assumes that SSL111 (not SSL or SSL1) is already installed on your system. You can confirm this with the command

$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT                              KIT TYPE    STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1IA           Full LP     Installed
------------------------------------ ----------- ---------

1 item found

Creating a Self-Signed Certificate

Follow these instructions to create a self-signed certificate.

  • Create the subdirectories TOMCAT$ROOT:[SSLCERTS] and TOMCAT$ROOT:[SSLKEYS]
$ create/dir tomcat$root:[sslcerts] /log
%CREATE-I-CREATED, TOMCAT$ROOT:[000000.sslcerts] created

$ create/dir tomcat$root:[sslkeys] /log
%CREATE-I-CREATED, TOMCAT$ROOT:[000000.sslkeys] created
Double-check owner and permissions so they match the following:
$ dir /sec ssl*.*
sslcerts.DIR;1       [TOMCAT$WWW]                     (RWE,RWED,,)
sslkeys.DIR;1        [TOMCAT$WWW]                     (RWE,RWED,,) 
  • Start up SSL111 (OpenSSL) and enable the environment with
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
  • Generate a self-signed certificate. Do not put a password on your certificate or key (you will be prompted for information) as this could hinder the automatic start-up of Tomcat. For example:
$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:4096 -keyout -
_$ /tomcat$root/sslkeys/server.key -out tomcat$root/sslcerts/server.crt
Generating a RSA private key
writing new private key to '/tomcat$root/sslkeys/server.key'
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Massachusetts
Locality Name (eg, city) []:Burlington
Organization Name (eg, company) [Internet Widgits Pty Ltd]:VMS SOFTWARE INC.
Organizational Unit Name (eg, section) []:OPENVMS SUPPORT
Common Name (e.g. server FQDN or YOUR name) []:NODE1.eng.vmssoftware.com
Email Address []:webmaster@NODE1.com
  • As a last step, you can verify that the certificate and key were created, that they ended up in the correct locations, and that they have the correct owner and permissions set.
$ dir [.ssl*] /sec

Directory TOMCAT$ROOT:[000000.sslcerts]

server.crt;1	[TOMCAT$WWW]			(RWE,RWED,,)

Total of 1 file.

Directory TOMCAT$ROOT:[000000.sslkeys]

server.key;1	[TOMCAT$WWW]			(RWD,RWED,,)

Total of 1 file.

Grand total of 2 directories, 2 files.

Optional – Convert Key and Certificate to DER Encoding

The key and certificate created earlier are in a PEM format. This means that if you edit the files, or type them out, you can see the characters and numbers in the encrypted files as plain text, though, they remain humanly unreadable. It is possible, however, to convert the files to other formats, such as DER, for encoding purposes. Once converted to DER encoding, the files are no longer readable and appears to be in a binary format. Sometimes, it is also convenient to combine the key, certificate, and CA certificate into one single file.

  • To convert the certificate and key from PEM to DER encoding, use the following commands.
$ openssl x509 -outform der -in tomcat$root:[sslcerts]server.crt -out -
_$ tomcat$root:[sslcerts]server_crt.der

$ openssl rsa -outform der -in tomcat$root:[sslkeys]server.key -out -
_$ tomcat$root:[sslkeys]server_key.der
View the DER encoded certificates and keys with the commands
$ openssl x509 -in tomcat$root:[sslcerts]server_crt.der -inform der -text -noout
$ openssl rsa -in tomcat$root:[sslkeys]server_key.der -inform der -text -noout
  • If you get the following error when viewing your encoded certificate, it means that you are trying to view a DER encoded certificate when your certificate is in fact PEM encoded.
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
If you get the following error, it means that you are trying to view a PEM encoded certificate with a command meant for DER encoded certificates.
unable to load certificate.
13978:error:0D0680A8:asn1 encoding routines:ASN1_CHECK_TLEN:wrong tag:tasn_dec.c:1306:
13978:error:0D07803A:asn1 encoding routines:ASN1_ITEM_EX_D2I:nested asn1
  • To transform a DER encoded certificate and key to the PEM format, use
$ openssl x509 -inform der -in tomcat$root:[sslcerts]server_crt.der -out -
_$ tomcat$root:[sslcerts]server_crt.pem

$ openssl rsa -inform der -in tomcat$root:[sslkeys]server_key.der -out -
_$ tomcat$root:[sslkeys]server_key.pem
To now view the certificate and key files in the PEM format, use
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem  -inform pem -text -noout
  • In some cases, it is advantageous to combine multiple pieces of the X.509 infrastructure into a single file. One common example would be to combine both the server key and server certificate into the same certificate file. The easiest way to combine certificates, keys, and chains is to convert each of them to PEM format and then copy the contents of each file into a new file. This is suitable for combining files to use in applications like Apache.
On OpenVMS you can combine PEM format self-signed certificates and keys with the DCL “$ APPEND” command. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.
$ create tomcat$root:[sslcerts]cert_and_key.pem
(Press Ctrl-Z)

$ append tomcat$root:[sslkeys]server_key.pem, - 
_$ tomcat$root:[sslcerts]server_crt.pem tomcat$root:[sslcerts]cert_and_key.pem
%APPEND-W-INCOMPAT, TOMCAT$ROOT:[sslkeys]server.key;1 (input) and TOMCAT$ROOT:[sslcerts]cert_and_key.pem;1 (output) have incompatible attributes
The warning message warning about incompatible attributes can be safely ignored. If you have obtained your certificate from a Certificate Authority, you can append your PEM format key, certificate, and CA certificate to a new empty file with
$ create tomcat$root:[sslcerts]cert_key_and_CA.pem
(Press Ctrl-Z)

$ append tomcat$root:[sslkeys]server_key.pem, tomcat$root:[sslcerts]server_crt.pem, - 
_$ tomcat$root:[sslcerts]CAcrt.pem tomcat$root:[sslcerts]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, TOMCAT$ROOT:[sslkeys]server_key.pem;1 (input) and TOMCAT$ROOT:[sslcerts]cert_key_and_CA.pem;1 (output) have incompatible attributes
Note: The combined key and certificate files must be in the PEM format. Converting to DER encoding after combining these files will not be successful as only the certificate will remain after the conversion.

Configure Tomcat for HTTPS on Port 8443

With key and certificate in hand, it is now possible to set up HTTPS. Pay special attention to the file names server.key and server.crt in the configuration below, as the files have been kept as they are and not converted to DER encoding or combined into a single file.

  • Edit the file TOMCAT$ROOT:[CONF]SERVER.XML. At an appropriate position somewhere under the section that asks you to define an SSL/TLS HTTP/1.1 Connector, add the following lines of code (highlighted in yellow). Make sure the paths and names for your certificate and certificate key files are correct. You may also customize the HTTPS port.
$ edit tomcat$root:[conf]server.xml


<!-- Define a SSL/TLS HTTP/1.1 Connector on port 8443 with HTTP/2
     This connector uses the APR/native implementation. When using the
     APR/native implementation or the OpenSSL engine with NIO or NIO2 then
     the OpenSSL configuration attributes must be used.


<!--  Port 8443 SSL111 Configuration  -->
<Connector port="8443"


You may now restart Tomcat and attempt to connect to the port you specified.

  • A comment about self-signed certificates: Recently, using self-signed certificates has become increasingly difficult. It is possible that although HTTPS is set up correctly for Tomcat, the browser refuses the connection. If so, you may wish to try another browser, choose some other method to test your connection, or obtain a valid certificate from a Certificate Authority.

Optional – Test HTTPS Using OpenSSL

If you cannot access your self-signed certificates through a browser, or simply do not have one handy, a quick and easy way to see if HTTPS is working is to test the connection using OpenSSL. This section will walk you through how to do just that.

  • Start up SSL111 (OpenSSL) and enable the environment with
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
  • Then use the command below to see if you can establish an HTTPS connection. Make sure you specify the correct DNS name and port for your server.
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:8443 “-showcerts” “-state”

SSL_connect:before SSL initialization
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS read server hello
SSL_connect:TLSv1.3 read encrypted extensions


To completely remove Tomcat, do the following:

  • Shut down Tomcat with the command
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
  • If you have AXIS2 or other Java plugins that make use of Tomcat, you should remove them now before you proceed.
  • Uninstall Tomcat using the $ PRODUCT REMOVE command.
$ product remove csws_java
The following product has been selected:
    VSI I64VMS CSWS_JAVA V8.5-50A          Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
    VSI I64VMS CSWS_JAVA V8.5-50A          DISK$SYS1:[VMS$COMMON.]

Portion done: 

The following product has been removed:
    VSI I64VMS CSWS_JAVA V8.5-50A          Layered Product
  • If you wish to do a complete removal of Tomcat, you should know that there are still files located in TOMCAT$ROOT:[000000] that have not been removed. The TOMCAT$ROOT logical should still be defined – something you can test with the command shown below.
$ show logical *tomcat*





  "TOMCAT$USER" = "tomcat$www"


If the logical is no longer there, you can still access the directory with the path shown above, that is if Tomcat was installed in its default location.
  • To remove the entire Tomcat directory tree, you can use the command below while inside the YOURDISK:[SYS0.SYSCOMMON] directory. Because all files are deleted without mercy, it is important to double-check and make sure you do not have any important files inside the directory tree and that the correct directory tree is specified. Use this command at your own risk.
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.tomcat...]*.*;* /log
Next, you can delete the directory YOURDISK:[SYS0.SYSCOMMON.tomcat] with the command
$ delete YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 /conf
There are also Tomcat files located in SYS$MANAGER. Use this command to find them
$ dir sys$manager:*tomcat*

TOMCAT$ARGS_LOCAL.DAT;1                 tomcat$startup.LOG;1

Total of 6 files.



Total of 1 file.

Grand total of 2 directories, 7 files.
When deleting these files, make sure that you use the /CONFIRM qualifier or specify them individually so that you do not delete any files by mistake while using wildcard characters.
$ delete sys$manager:*tomcat*.*;* /conf
Lastly, there is also the file SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT.
  • The last remnants of Tomcat are its username TOMCAT$WWW inside the SYSUAF and the TOMCAT$USER and TOMCAT$ROOT logicals. To delete the username account, do the following.
$ mcr authorize
UAF> remove tomcat$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier TOMCAT$WWW value [000555,000555] 
   removed from rights database
%UAF-I-RDBREMMSGU, identifier TOMCAT value [000555,177777] removed 
   from rights database
To delete the logicals, use the $ DEASSIGN command.
$ deassign /sys tomcat$user
$ deassign /sys tomcat$root