VSI OpenVMS Wiki - User contributions [en]

Apache (CSWS) - Easy Installation Guide

2022-01-26T17:34:53Z

Axel.elfving: /* Running APACHE$CONFIG */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist 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.

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

:Note: The quotas assigned to the APACHE$WWW account are the minimum recommended resources to start the Apache Web Server. However, each installation will be unique based on the intended use of the Apache web server and, thus, the resources will need to be increased according to what the web server is used for. Some UAF resources may also require that SYSGEN parameters be adjusted as well.

<pre>
Maxjobs: 0 Fillm: 8192 Bytlm: 1000000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 32768
Queprio: 4 TQElm: 610 WSextent: 32768
CPU: (none) Enqlm: 2000 Pgflquo: 2500000
</pre>

:The example above shows what a heavily used Apache Web Server that supports multiple directives and web-based applications. The FILLM resource requires the SYSGEN parameter CHANNELCNT be increased equal to or greater than the FILLM value in this example. Some SYSGEN parameters may require being added to MODPARAMS.DAT, and an Autogen/Reboot be performed. CHANNELCNT is one such parameter. See [https://wiki.vmssoftware.com/Tomcat_(CSWS_JAVA)_-_Easy_Installation_Guide#Setting_System_Parameters Tomcat - Easy Installation Guide] for detailed instructions on how to change the CHANNELCNT parameter.

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000]APACHE$CREATE_ROOT.COM, which will guide you through the process (will create directories).

* Run the command procedure APACHE$CERT_TOOL.COM and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

:Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

: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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

: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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

:Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier.

To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

:Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Axis2 - Easy Installation Guide

2021-10-20T07:13:33Z

Axel.elfving:

This is an easy installation guide that will take you through how to install and configure Apache Axis2 for use with the Tomcat web server on OpenVMS. Before starting the installation, it is a good idea to read through the “Tomcat (CSWS JAVA) - Easy Installation Guide” and make sure that you have you installed and configured Tomcat correctly.

The document also contains instructions for how to set up an AJP Connector between CSWS Apache Web Server and Apache Axis2 on Tomcat. If that is something you wish to do, you need to already have Apache installed and fully configured on your system. For instructions on how to install and configure Apache, consult either the Apache release notes or the “Apache (CSWS) - Easy Installation Guide”.

For more guides like this, check out the [https://wiki.vmssoftware.com/Open_Source_Software_for_OpenVMS Open Source Software for OpenVMS] page.

=Introduction=

Go through the following steps to install Axis2.

* Unpack the kit with the $ RUN command

<pre>
$ run VSI-I64VMS-AXIS2-V0107-3-1.ZIPEXE
</pre>

:Then, install Axis2 with the command

<pre>
$ product install axis2
Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.AXIS2]
vsi-i64vms-axis2-v0107-3-1.pcsi$compressed;1 succeeded

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 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 AXIS2 V1.7-3

VMS Software Inc. and The Apache Software Foundation.

Minimum JDK software version not found on system, abort installation

This kit requires the minimum Java version of 1.8.

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 AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
%PCSIUI-I-COMPWERR, operation completed after explicit continuation
from errors
</pre>

:Comment for the highlighted part of the installation output: If you have OpenJDK8 installed on a system that previously did not have JAVA installed on it, 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 and Axis2.

=Configuration=

These instructions will guide you through how to define the necessary Axis2 logicals on start-up before showing you how to set up the AJP Connector.

==Automatic Start-up Commands==

Follow these instructions if you want Axis2 logicals to be defined automatically when rebooting the system.

* Edit the file SYS$MANAGER:SYLOGICALS.COM add the lines specified below (in the section where you are asked to define site-specific logicals) to define the Axis2 logicals on start-up. Make sure to specify the correct node for your system (highlighted in yellow).

<pre>
$ edit sys$manager:sylogicals.com

...

$! ******************************************************************
$! Define any site-specific logical names below:
$! ******************************************************************

...

$ IF NODE .EQS. "YOUR_NODE_NAME"
$ THEN
$ file := SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ <nowiki>if f$search("''file'") .nes. "" then @'file'</nowiki>
$ ENDIF

...
</pre>

==Defining Axis2 Logicals==

Now is a good time to manually define the Axis2 logicals.

* Run the same file you included in the start-up procedure in the previous section. Most notably, this will define the logical AXIS2$ROOT – giving us easy access to the Axis2 root directory.

<pre>
$ @SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ show logical *axis*

(LNM$PROCESS_TABLE)

(LNM$JOB_89235900)

"AXIS$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Deploying Axis2 WAR File in Tomcat==

To enable Axis2 and integrate it with Tomcat, we need to deploy the Axis2 WAR file in the directory TOMCAT$ROOT:[WEBAPPS].

* Copy the file AXIS2$ROOT:[OPENVMS]axis2.war to TOMCAT$ROOT:[WEBAPPS] and make sure the file has TOMCAT$WWW as owner and the appropriate protections.

<pre>
$ copy /log axis2$root:[openvms]axis2.war tomcat$root:[webapps]
%COPY-S-COPIED, AXIS2$ROOT:[OpenVMS]axis2.war;1 copied to TOMCAT$ROOT:[webapps]axis2.war;1 (19.27MB)

$ dir /sec tomcat$root:[webapps]axis2.*

Directory TOMCAT$ROOT:[webapps]

axis2.DIR;1 [TOMCAT$WWW] (RWED,RWED,RE,)
axis2.war;1 [TOMCAT$WWW] (RWED,RWED,RE,RE)

Total of 1 file.

$ set file /prot=(S:RWE,O:RWED,G,W) tomcat$root:[webapps]axis2.* /log
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.war;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps.axis2]axis2-web.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
...
</pre>

:If automatic deployment is configured correctly for Tomcat, the WAR file should be unpacked automatically during runtime, resulting in the creation of TOMCAT$ROOT:[WEBAPPS]axis2.DIR.

* If you are in a production environment, or for some other reason do not wish to use automatic deployment, you may wish to deploy your WAR files using the Tomcat interface – this will allow you to deploy WAR files from a separate directory and thus run a lower risk of unexpectedly overwriting files in use.

:You may also wish to disable automatic deployment, so that WAR files placed in your TOMCAT$ROOT:[WEBAPPS] directory do not automatically deploy and overwrite your existing configuration files. To do this, edit TOMCAT$ROOT:[CONF]server.xml and set autoDeploy to “false”, as shown below. Then restart Tomcat to implement the changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...

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

...
</pre>

:Lastly, to manually deploy AXIS2$ROOT:[OPENVMS]axis2.war directly from its directory, visit your Tomcat server and enter the Manager App. Under “Deploy directory or WAR file located on server”, enter the information shown below.

<pre>
Context Path (required): /axis2
XML Configuration file path:
WAR or Directory path: axis2$root:[openvms]axis2.war
</pre>

:Note: Although you set autoDeploy to “false”, Tomcat will still deploy WAR files on start-up. Therefore, to avoid unexpected deployment, it is advisable to keep WAR files you do not wish to deploy outside your TOMCAT$ROOT:[WEBAPPS] directory.

==Enabling HTTPS for Axis2==

* Change the Axis2 Administrator account username and password, edit the file TOMCAT$ROOT:[000000.webapps.axis2.WEB-INF.conf]axis2.xml and make sure that you change these two lines (located close to the top of the file) and set a secure password.

<pre>
$ edit tomcat$root:[000000.webapps.axis2.web-inf.conf]axis2.xml

...

<parameter name="userName">admin</parameter>
<parameter name="password">axis2</parameter>

...
</pre>

:In the same file, if you wish to use HTTPS with Axis2, scroll down until you find the section that reads

<pre>
...






</pre>

:Edit the lines directly underneath, adding the transportReceiver for HTTPS (highlighted in yellow), so that the two transportReceiver directives read

<pre>
<transportReceiver name="http"
class="org.apache.axis2.transport.http.AxisServletListener"/>
<transportReceiver name="https"
class="org.apache.axis2.transport.http.AxisServletListener"/>

...
</pre>

* Make sure to restart Tomcat so that the configuration changes are implemented.

<pre>
$ @sys$startup:tomcat$shutdown.com
$ submit/user=tomcat$www/queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com

$ show system
...
0000046F APACHE$TOMCAT HIB 4 70149 0 00:00:53.85 56117 47489 M
...
</pre>

* Lastly, connect to Axis2 using the HTTPS to test the connection with the URL shown below. If the connections fails, you may want to review this guide as well as the “Tomcat (CSWS JAVA) – Easy Installation Guide” or review the log files in TOMCAT$ROOT:[000000.logs].

<pre>
https://your.server.com:8443/axis2/
</pre>

==Setting up the AJP Connector==

This section will show you how to set up the AJP Connector, which will allow you to integrate Tomcat into an existing Apache Web Server installation so that you can access Axis2 through Apache. Thus, it is necessary for Apache to be installed and working correctly. For instruction on how to install Apache, see the “Apache (CSWS) - Easy Installation Guide”.

* Edit the file TOMCAT$ROOT:[CONF]server.xml and confirm that the following directive is uncommented and that redirectPort points to the HTTPS port you have specified for Tomcat. If any of the information is incorrect, make the necessary changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

...
</pre>

* Next edit Apache’s main configuration file APACHE$ROOT:[000000.CONF]HTTPD.CONF and scroll down until you reach the list of loadable modules. Uncomment the following modules by removing the number signs (#) in front of the LoadModule directives.

<pre>
$ edit apache$root:[000000.conf]httpd.conf

...

LoadModule proxy_module modules/mod_proxy.exe
LoadModule proxy_ajp_module modules/mod_proxy_ajp.exe

...
</pre>

:Next, add the <Location> directive shown below at the very bottom of the same file. The DNS name highlighted in yellow should match that of your server. It is possible to use your IP address instead, though that might by-pass the certificate you have in place for your server and unable you from establishing an HTTPS connection to Axis2.

<pre>
...

<Location "/axis2">
ProxyPass "ajp://example.eng.vmssoftware.com:8009/axis2"
</Location>

...
</pre>

:Lastly, for Apache to implement these changes, it needs to be restarted. You can do this with

<pre>
$ @sys$startup:apache$shutdown
$ @sys$startup:apache$startup
</pre>

* To see if the AJP connector has been set up correctly, connect to Axis2 on either port 80 (HTTP) or port 443 (HTTPS). The 8009 port specified for the AJP Connector is used internally.

<pre>
http://example.eng.vmssoftware.com:80/axis2/
https://example.eng.vmssoftware.com:443/axis2/
</pre>

=Removal=

To remove Axis2, follow these instructions. If you also want to remove Tomcat, make sure you remove Axis2 first.

* First, shut down Tomcat.

<pre>
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
</pre>

* Then, uninstall Axis2 using the command below.

<pre>
$ product remove axis2

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been removed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
</pre>

* If you do not wish to remove Tomcat, but want to do a complete removal of Axis2, you can selectively remove the files belonging to Axis2 to inside TOMCAT$ROOT:[000000.webapps].

<pre>
$ delete tomcat$root:[webapps]axis2.war;1 /conf
DELETE TOMCAT$ROOT:[webapps]axis2.war;1 ? [N]: Y
</pre>

:If using the $ DELETE /TREE command when deleting the Axis2.DIR directory structure inside TOMCAT$ROOT:[000000.webapps], make sure that you are not deleting any files by mistake before executing this command. All files will be deleted instantaneously, so use the command at your own risk.

<pre>
$ delete /tree TOMCAT$ROOT:[000000.webapps.AXIS2...]*.*;* /log
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]error.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]HappyAxis.jsp;1 deleted
(24KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]index.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listFaultyService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listGroupService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listServices.jsp;1
deleted (8KB)
...

$ delete TOMCAT$ROOT:[000000.webapps]AXIS2.DIR;1 /conf
DELETE TOMCAT$ROOT:[000000.webapps]axis2.DIR;1 ? [N]: Y
</pre>

* In addition to deleting the Axis2 files, you should also go through the configuration changes made earlier in this document and revert the relevant changes.
* If you want to completely remove any traces of Axis2 you should know that the AXIS2$ROOT logical is still defined, although it now points to a non-existent directory. You can remove the logical using the $ DEASSIGN command.

<pre>
$ show logical *axis2*

(LNM$PROCESS_TABLE)

(LNM$JOB_892FB880)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
$ deassign /sys axis2$root
</pre>

* If you have a look inside SYS$STARTUP, you can see that there are also some Axis2 remnants remaining in there. You can either remove these files individually or with a wildcard qualifier (as shown below) together with the /CONFIRM qualifier. It is always advisable to use extra caution when deleting files, especially in system directories, since deleted files are not recoverable unless backed up.

<pre>
$ dir sys$startup:*axis2*

Directory SYS$SYSROOT:[SYSMGR]

axis2$define_logicals.LOG;2 axis2$define_logicals.LOG;1
axis2-tmp-8889454529806580694^.tmp.DIR;1

Total of 3 files.

Directory SYS$COMMON:[SYSMGR]

axis2$define_logicals.com;1

Total of 1 file.

Grand total of 2 directories, 3 files.
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;2 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;1 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1 ? [N]: Y
%DELETE-W-FILNOTDEL, error deleting SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1
-RMS-E-MKD, ACP could not mark file for deletion
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty
DELETE SYS$COMMON:[SYSMGR]axis2$define_logicals.com;1 ? [N]: Y
</pre>

Tomcat (CSWS JAVA) - Easy Installation Guide

2021-10-20T07:13:09Z

Axel.elfving:

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.

=Introduction=

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.

:<nowiki>***</nowiki>Please note: HPE Java™ JDK V1.8u_144* is not recommended.***

:<nowiki>***</nowiki>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:

<pre>
$ show devices $1$YOURDISK: /full
</pre>

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

<pre>
Volumes Status: ODS-5, ...
</pre>

* 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.

::TOMCAT$ROOT:[CONF]tomcat-users.xml
::TOMCAT$ROOT:[CONF]context.xml
::TOMCAT$ROOT:[CONF]web.xml
::TOMCAT$ROOT:[CONF]server.xml

* Shut down the Tomcat webserver with the command

<pre>
$ @sys$startup:tomcat$shutdown.com
</pre>

* Remove Tomcat with the command

<pre>
$ product remove csws_java
</pre>

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

=Installation=

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

<pre>
$ run VSI-I64VMS-CSWS_JAVA-V0805-50A-1.ZIPEXE
</pre>

* Install Tomcat using the PCSI application.

<pre>
$ 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

VSI I64VMS CSWS_JAVA V8.5-50A

Post-installation tasks are required.

To start the Tomcat web server at system boot time, add the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:TOMCAT$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

To shutdown Tomcat at system shutdown time, add the following lines to
SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:TOMCAT$SHUTDOWN.COM
$ 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
</pre>

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.

=Configuration=

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:

<pre>
$!***SYS$SYSROOT:[SYSMGR]JAVA$80_SETUP.COM***
$!
$ @sys$sysdevice:[sys0.syscommon.openjdk$80.com]java$setup.com 'P1'
$ exit
</pre>

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.

<pre>
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
</pre>

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.

<pre>
$ set default sys$system
$ mcr sysgen
SYSGEN> USE CURRENT
SYSGEN> SHOW CHANNELCNT
Parameter Name Current Default Min. Max. Unit Dynamic
-------------- ------- ------- ------- ------- ---- -------
CHANNELCNT 32767 512 64 65535 Channels
SYSGEN> SHOW WSMAX
Parameter Name Current Default Min. Max. Unit Dynamic
-------------- ------- ------- ------- ------- ---- -------
WSMAX 900000 131072 16384 134217728 Pagelets
internal value 56250 8192 1024 8388608 Pages
</pre>

* 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.

<pre>
SYSGEN> USE CURRENT
SYSGEN> SET CHANNELCNT 32767
SYSGEN> SET WSMAX 900000
SYSGEN> WRITE ACTIVE
SYSGEN> WRITE CURRENT
</pre>

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:

<pre>
$ set default sys$system
$ mcr authorize
</pre>

* 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).

<pre>
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
</pre>

* The TOMCAT$WWW username should now look something like this:

<pre>
UAF> show tomcat$www

Username: TOMCAT$WWW Owner:
Account: TOMCAT UIC: [555,555] ([TOMCAT$WWW])
CLI: DCL Tables: DCLTABLES
Default: TOMCAT$ROOT:[000000]
LGICMD: LOGIN
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:
NETMBX TMPMBX
Default Privileges:
BYPASS IMPERSONATE NETMBX SYSPRV TMPMBX
</pre>

* If an account for Apache does not exist, you can create the account from scratch like so:

<pre>
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
</pre>

==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.

<pre>
$ @sys$manager:tomcat$define_logicals.com
</pre>

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*

<pre>
(LNM$PROCESS_TABLE)

(LNM$JOB_89326240)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"TOMCAT$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.tomcat.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==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.

<pre>
$!
$ IF NODE .EQS. "YOUR_NODE_NAME"
$ THEN
$ if f$search("SYS$STARTUP:TOMCAT$STARTUP.COM") .nes. ""
$ then
$ submit/USER=TOMCAT$WWW/QUEUE=SYS$BATCH/PARAMETERS=(TOMCAT$WWW)
SYS$STARTUP:TOMCAT$STARTUP.COM
$ endif
$ ENDIF
$!
</pre>

: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:

<pre>
$ set terminal /width=132
</pre>

* Edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the following lines:

<pre>
$!
$ file := SYS$STARTUP:TOMCAT$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
$!
</pre>

==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).

<pre>
$ show logical tomcat$root
"TOMCAT$ROOT" = "YOURDISK:[SYS0.SYSCOMMON.tomcat.]" (LNM$SYSTEM_TABLE)

$ set default YOURDISK:[SYS0.SYSCOMMON]
$ set file /owner=[555,555] tomcat.DIR /log
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 modified

$ set file /owner=[555,555] [.tomcat...]*.*;* /log
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON.tomcat]bin.DIR;1 modified
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON.tomcat]BUILDING.txt;1 modified
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON.tomcat]conf.DIR;1 modified
...
</pre>

* Second, set the file permissions. First for the root directory and then for the rest of the directory structure.

<pre>
$ 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
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON.tomcat]BUILDING.txt;1 file protection
changed to S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON.tomcat]conf.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
...
</pre>

* To verify that the owner and file protections were set correctly, you can issue the command
$ dir [.tomcat] /owner /prot

<pre>
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,,)
</pre>

==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:

<pre>
$!********************************************
$ ! Login.Com for Tomcat Web Server
$ !
$ ! exit
$ !
$ set process/parse =extend ! ODS-5 Support
$ set process/units = bytes ! ODS-5 Support (optional)
$ DEFINE JAVA$DONT_PRESET_LOGICALS "TRUE" ! TURN LOGICAL DEFS OFF IN LIB$INITIALIZE
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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
$ EXIT
</pre>

==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:

<pre>
$!***** SYS$STARTUP:TOMCAT$DEFS_LOCAL.COM*****
$! 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]
</pre>

* 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.

<pre>
$ submit /user=tomcat$www /queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
</pre>

: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.

<pre>
$ 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:
NETMBX TMPMBX

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
</pre>

* If you want to shut down Tomcat, you can do so with the following command from a privileged account.

<pre>
$ @sys$startup:tomcat$shutdown.com
</pre>

==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.

<pre>
$ edit tomcat$root:[conf]tomcat-users.xml

...

<nowiki></nowiki>
<nowiki></nowiki>
<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"/>
</tomcat-users>
[End of file]
</pre>

* To allow access to Admin and Manager, permissions must be set to allow for connections. Edit these two files:

::TOMCAT$ROOT:[webapps.host-manager.META-INF]context.xml
::TOMCAT$ROOT:[webapps.manager.META-INF]context.xml

:Then add the comment delimiters highlighted in the lines below to both context.xml files, so that the relevant lines read

<pre>
...

<Context antiResourceLocking="false" privileged="true" >
<nowiki></nowiki>
<Manager sessionAttributeValueClassNameFilter=
"java\.lang\.(?:Boolean|Integer|Long|Number|String)|org\.apache\.c`
</Context>

...
</pre>

* Finally, restart Tomcat with the commands below.

<pre>
$ @sys$startup:tomcat$shutdown.com
$ submit /user=tomcat$www /queue=sys$batch /parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
</pre>

==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.

<pre>
$ edit tomcat$root:[conf]web.xml

...

<nowiki></nowiki>
<servlet>
<servlet-name>cgi</servlet-name>
<servlet-class>org.apache.catalina.servlets.CGIServlet
</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>executable</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>cgiPathPrefix</param-name>
<param-value>WEB-INF/cgi</param-value>
</init-param>
<load-on-startup>5</load-on-startup>
</servlet>

...
</pre>

: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.

<pre>
...



<nowiki></nowiki>
<servlet-mapping>
<servlet-name>cgi</servlet-name>
<url-pattern>/cgi-bin/*</url-pattern>
</servlet-mapping>

...
</pre>

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

<pre>
$ edit tomcat$root:[conf]context.xml

...

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

...
</pre>

===CGI Example===

* Create the directory structure TOMCAT$ROOT:[WEBAPPS.CGI.WEB-INF.CGI]. While in TOMCAT$ROOT, run the following command.

<pre>
$ create /dir [.webapps.cgi.web-inf.cgi] /log
%CREATE-I-CREATED, TOMCAT$ROOT:[000000.webapps.cgi.web-inf.cgi] created
</pre>

* 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].

<pre>
$ dir apache$root:[cgi-bin]

Directory APACHE$COMMON:[CGI-BIN]

TEST-CGI-VMS.COM;1 TEST-CGI-VMS.EXE;1

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
%COPY-S-COPIED, APACHE$COMMON:[CGI-BIN]TEST-CGI-VMS.EXE;1 copied to TOMCAT$ROOT:
[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
%COPY-S-COPIED, APACHE$COMMON:[CGI-BIN]TEST-CGI-VMS.COM;1 copied to TOMCAT$ROOT:
[webapps.cgi.web-inf.cgi]test-cgi-vms.cgi;1 (4KB)
</pre>

:Set the correct file ownership and protection and make sure to use the correct UIC for the TOMCAT$WWW user account.

<pre>
$ 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
E,O:RWED,G:,W:
...
</pre>

:And as a last step, make sure that ownership and permissions are correct.

<pre>
$ 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.
</pre>

* Create the file TOMCAT$ROOT:[WEBAPPS.CGI]index.html.

<pre>
$ create tomcat$root:[webapps.cgi]index.html
(Press Ctrl-Z)
</pre>

* 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.

<pre>
$ edit tomcat$root:[000000]STREAM_LF.FDL
FILE
ALLOCATION 4
BEST_TRY_CONTIGUOUS yes
EXTENSION 0
ORGANIZATION sequential
RECORD
BLOCK_SPAN yes
CARRIAGE_CONTROL carriage_return
FORMAT stream_LF
SIZE 0
[End of file]
</pre>

:Using this file, the conversion can now be performed with

<pre>
$ convert /fdl=tomcat$root:[000000]stream_lf.fdl -
_$ tomcat$root:[webapps.cgi]index.html tomcat$root:[webapps.cgi]
</pre>

:This will create a new version of the file for which you can verify that the record format is correct with the command below.

<pre>
$ dir /full tomcat$root:[webapps.cgi]index.html;2
...
Record format: Stream_LF, maximum 0 bytes, longest 0 bytes
...
</pre>

* Make sure that the ownership and permissions of the index.html file are as follows.

<pre>
$ 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.
</pre>

* 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.

<pre>
<nowiki>$ edit index.html
<HTML>
<HEAD>
<TITLE>CGI Application Example</TITLE>
<link href="hpweb_styles_win_ie6.css" rel="stylesheet"
type="text/css">
<style type="text/css">

</style>
</HEAD>
<BODY>
<h2> <class="colorE7E7E7bg color003366"> CGI Application Example</h2>
<h3> <class="colorE7E7E7bg color003366"> CGI from the TOMCAT Server</h3>
<a href="https://</nowiki>10.10.100.0:8443<nowiki>/cgi/cgi-bin/test-cgi-vms.exe">CGI-EXE from the TOMCAT Server. </a> 
<a href="https://</nowiki>10.10.100.0:8443<nowiki>/cgi/cgi-bin/test-cgi-vms.cgi">CGI-COM from the TOMCAT Server. </a> 
<hr>
</hr>
<h3> <class="colorE7E7E7bg color000066">CGI from the APACHE Web Server </h3>
<a href="https://</nowiki>10.10.100.0:443<nowiki>/cgi-bin/test-cgi-vms.exe">CGI-EXE from the APACHE Web Server.</a>
<a href="https://</nowiki>10.10.100.0:443<nowiki>/cgi-bin/test-cgi-vms.com">CGI-COM from the APACHE Web Server. </a>

Or you can Use the non-SSL URL of: http://</nowiki>10.10.100.0:8080<nowiki>/cgi/cgi-bin/test-cgi-vms.exe and the non-SSL URL of: http://</nowiki>10.10.100.0:80<nowiki>/cgi-bin/test-cgi-vms

Thank you! /VSI Support Team 

</BODY>
</HTML>
[End of file]</nowiki>
</pre>

: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.

<pre>
$ 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"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<display-name> A VSI CGI Example... </display-name>
<description>
Used as an example for showing how CGI apps can work with Tomcat V8.5-50
</description>
<session-config>
<session-timeout>
30
</session-timeout>
</session-config>
<welcome-file-list>
<welcome-file>
index.html
</welcome-file>
</welcome-file-list>
</web-app>
[End of file]
</pre>

* 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.

<pre>
$ edit tomcat$root:[conf]server.xml

...

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

...
</pre>

==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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

Follow these instructions to create a self-signed certificate.

* Create the subdirectories TOMCAT$ROOT:[SSLCERTS] and TOMCAT$ROOT:[SSLKEYS]

<pre>
$ 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
</pre>

:Double-check owner and permissions so they match the following:

<pre>
$ dir /sec ssl*.*
sslcerts.DIR;1 [TOMCAT$WWW] (RWE,RWED,,)
sslkeys.DIR;1 [TOMCAT$WWW] (RWE,RWED,,)
</pre>

* Start up SSL111 (OpenSSL) and enable the environment with

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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:

<pre>
$ 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
</pre>

* 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.

<pre>
$ 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.
</pre>

===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.

<pre>
$ 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
</pre>

:View the DER encoded certificates and keys with the commands

<pre>
$ 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
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ 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
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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.

<pre>
$ 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
</pre>

: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

<pre>
$ 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
</pre>

: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.

<pre>
$ edit tomcat$root:[conf]server.xml

...

<nowiki></nowiki>

...

<nowiki></nowiki>
<Connector port="8443"
connectionTimeout="20000"
enableLookups="false"
maxKeepAliveRequests="1000"
maxThreads="200"
scheme="https"
secure="true"
SSLEnabled="true"
SSLCertificateFile="/tomcat$root/000000/sslcerts/server.crt"
SSLCertificateKeyFile="/tomcat$root/000000/sslkeys/server.key"
SSLVerifyClient="none"
SSLProtocol="TLSv1.1+TLSv1.2+TLSv1.3"/>

...
</pre>

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

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:8443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

=Removal=

To completely remove Tomcat, do the following:

* Shut down Tomcat with the command

<pre>
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
</pre>

* 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.

<pre>
$ 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:
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS_JAVA V8.5-50A Layered Product
</pre>

* 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.

<pre>
$ show logical *tomcat*

(LNM$PROCESS_TABLE)

(LNM$JOB_892B9EC0)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"TOMCAT$ROOT" = "YOURDISK:[SYS0.SYSCOMMON.tomcat.]"
"TOMCAT$USER" = "tomcat$www"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

: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.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.tomcat...]*.*;* /log
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000]LOGIN.COM;2 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000]LOGIN.COM;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000]STREAM_LF.FDL;1 deleted (8KB)
...
</pre>

:Next, you can delete the directory YOURDISK:[SYS0.SYSCOMMON.tomcat] with the command

<pre>
$ delete YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 /conf
DELETE YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 ? [N]: y
</pre>

:There are also Tomcat files located in SYS$MANAGER. Use this command to find them

<pre>
$ dir sys$manager:*tomcat*

Directory SYS$SYSROOT:[SYSMGR]

TOMCAT$ARGS.DAT;2 TOMCAT$ARGS.DAT;1 TOMCAT$ARGS_LOCAL.DAT;2
TOMCAT$ARGS_LOCAL.DAT;1 tomcat$startup.LOG;1
tomcat-users_xml.TPU$JOURNAL;1

Total of 6 files.

Directory SYS$COMMON:[SYSMGR]

tomcat$define_logicals.com;1

Total of 1 file.

Grand total of 2 directories, 7 files.
</pre>

: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.

<pre>
$ delete sys$manager:*tomcat*.*;* /conf
DELETE SYS$SYSROOT:[SYSMGR]TOMCAT$ARGS.DAT;2 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]TOMCAT$ARGS.DAT;2 ? [N]: Y
...
</pre>

:Lastly, there is also the file SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT.

<pre>
$ del SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT;1 /conf
DELETE SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT;1 ? [N]: y
</pre>

* 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.

<pre>
$ 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
</pre>

:To delete the logicals, use the $ DEASSIGN command.

<pre>
$ deassign /sys tomcat$user
$ deassign /sys tomcat$root
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-20T07:12:47Z

Axel.elfving:

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist 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.

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

:Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

: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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

: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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

:Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier.

To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

:Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Open Source Software for OpenVMS

2021-10-19T11:35:55Z

Axel.elfving:

'''Open Source''' refers to software whose source code is made freely available for modification and/or distribution. Below is a list of open source software that works with OpenVMS, as well as some links to instructional open source material that can be found on this wiki.

=Open Source Software Developed by VSI=
* [https://vmssoftware.com/products/activemq/ ActiveMQ]
* [https://vmssoftware.com/products/apache-ant/ Apache ANT]
* [https://vmssoftware.com/products/maven/ Apache Maven]
* [https://vmssoftware.com/products/axis2/ AXIS2]
* [https://vmssoftware.com/products/civetweb/ CivetWeb]
* [https://vmssoftware.com/products/curl/ cURL]
* [https://vmssoftware.com/products/gearman/ Gearman]
* [https://vmssoftware.com/products/gnuplot/ Gnuplot]
* [https://vmssoftware.com/products/gnv/ GNV (GNU's not VMS)]
* [https://vmssoftware.com/products/haproxy/ HAProxy]
* [https://vmssoftware.com/products/kerberos/ Kerberos]
* [https://vmssoftware.com/products/libmariadb/ LibMariaDB]
* [https://vmssoftware.com/products/libpq/ LibPQ]
* [https://vmssoftware.com/products/librabbitmq/ LibRabbitMQ]
* [https://vmssoftware.com/products/librd-kafka/ LibRDkafka]
* [https://vmssoftware.com/products/lua/ Lua]
* [https://vmssoftware.com/products/mariadb/ MariaDB]
* [https://vmssoftware.com/products/memcached/ Memcached]
* [https://vmssoftware.com/products/mosquitto/ Mosquitto]
* [https://vmssoftware.com/products/openjdk/ OpenJDK]
* [https://vmssoftware.com/products/openldap/ OpenLDAP]
* [https://vmssoftware.com/products/paho-c/ PAHO-C]
* [https://vmssoftware.com/products/perl/ Perl]
* [https://vmssoftware.com/products/php/ PHP]
* [https://vmssoftware.com/products/python/ Python]
* [https://vmssoftware.com/products/redis/ Redis]
* [https://vmssoftware.com/products/ruby/ Ruby]
* [https://vmssoftware.com/products/samba-cifs/ Samba/CIFS]
* [https://vmssoftware.com/products/scala/ Scala]
* [https://vmssoftware.com/products/secure-web-server/ Secure Web Server]
* [https://vmssoftware.com/products/simplified-wrapper-and-interface-generator/ Simplified Wrapper and Interface Generator]
* [https://vmssoftware.com/products/sql-relay/ SQL Relay Client]
* [https://vmssoftware.com/products/svn/ SVN]
* [https://vmssoftware.com/products/syslogd/ syslogd]
* [https://vmssoftware.com/products/tomcat/ Tomcat]
* [https://vmssoftware.com/products/vgit/ vGit]
* [https://vmssoftware.com/products/vms-ide/ VMS IDE]
* [http://vmssoftware.com/products/xpdf-file-viewer/ XPDF File Viewer]
* [https://vmssoftware.com/products/zeromq/ ZeroMQ]

==Instructional Material==

In this section you can find links to wiki pages that contain instructional open source material.

===Installation Guides===

* [https://wiki.vmssoftware.com/Apache_(CSWS)_-_Easy_Installation_Guide OpenVMS Apache installation guide]
* [https://wiki.vmssoftware.com/Tomcat_(CSWS_JAVA)_-_Easy_Installation_Guide OpenVMS Tomcat installation guide]
* [https://wiki.vmssoftware.com/Axis2_-_Easy_Installation_Guide OpenVMS Axis2 installation guide]

=Community software=

{| class="wikitable"
! colspan="col" | Name
! colspan="col" | Description
! colspan="col" | Language
! colspan="col" | Architectures
! colspan="col" | Author
! colspan="col" | Year
! colspan="col" | Link
|-
| ACE
| C++ framework for developing distributed networked applications
| C++
| [[Alpha]], [[Integrity]]
| DOCGroup, ported by Remedy IT
|
| [https://github.com/DOCGroup/ACE_TAO Github]
|-
| Adventure game
| A magic/exploration simulation game.
| Fortran
| [[VAX]], [[Alpha]]
| Willie Crowther
| 1970s
| [https://github.com/whitten/m-adventure Github], [https://www.digiater.nl/openvms/decus/lt90a/mumpssig/games/ Code from DECUS 1990 L&T SIG Tape], [https://www.digiater.nl/openvms/freeware/v10/adventure/ OpenVMS Freeware]
|-
| BORG calendar
| BORG Calendar is a personal information manager written in Java and published under GPL. It is a combination of calendar, ToDo list, address book and task/project tracking system.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=borg OpenVMS Free softwares]
|-
| BatchFileConversion
| This is a Synergy/DE console application that will convert Workbench build files from Windows batch files to Unix script files or OpenVMS command files.
| Bash
|
| Unknown
|
| [https://github.com/SynSupport/BatchFileConversion Github]
|-
| C developer tools for OpenVMS
| This repo contains developer tools running on OpenVMS operating system
| C
|
| Rafiq Ahamed K
| 2017
| [https://github.com/rafiqkattangere/vms_utils Github]
|-
| C survival kit
| A set of useful functions, data structures, and macros aimed at allowing more expressive and reliable C code. Portability targets are OpenVMS and Linux.
|
|
|
|
| [https://github.com/chadjoan/C-Survival-Kit Github]
|-
| CGP_PMAS
| CommuniGate Pro and PreciseMail Anti-Spam Gateway Integration on OpenVMS systems
| Perl
|
| Thomas Morstein
|
| [https://github.com/ztmr/CGP_PMAS Github]
|-
| CMS-EXPORT
| A utility for OpenVMS to export CMS library content and revisions history. CMS is a version control system commonly used in OpenVMS environment (part of DECset). Valued for being efficient and time-proven, CMS also has its share of drawbacks -- lack of export options being one of these. cms-export utility allows export of a specified CMS library (or a set of library elements) into a file in git-fast-export format, which subsequently can be used to create a repository with an alternative version management system such as git, fossil etc.
| DCL
| [[VAX]], [[Alpha]]
| Artur Shepilko
| 2018
| [https://github.com/nomadbyte/cms-export Github]
|-
| Convert OpenVMS text files to Unix
| Convert openvms textfiles into UNIX/DOS format
| C
|
| Andika Triwidada
|
| [https://github.com/atriwidada/openvms-to-unix Github]
|-
| Cython
| The most widely used Python to C compiler
| C
|
| VMS Software
|
| [https://github.com/vmssoftware/cython Github]
|-
| DBCHECK
| Very fast check the health of a RDB database
| [[DCL]]
|
|
|
| [https://github.com/NLA0/DCL/blob/master/dbcheck Github]
|-
| DiskFree
| An implementation of the Linux df command (view disk usage)
|
| [[VAX]], [[Alpha]], [[Integrity]] (untested)
| Alan Fay
|
| [https://github.com/alan-fay/openvms Github]
|-
| DrJava
| DrJava is a lightweight Java IDE written in Java and published under the BSD license. It has the usual features such as editing with syntax coloring, automatic indentation, brace matching…, compiling, debugging, testing using JUnit…
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=drjava OpenVMS Free softwares]
|-
| EPICS on OpenVMS
| Port of EPICS to OpenVMS
| C
|
| Clemens Wermelskirchen, maintained by Freddie Akeroyd
|
| [https://github.com/FreddieAkeroyd/EPICS-VMS Github]
|-
| ES40 emulator
| A portable emulator for the ES40 Alpha
| C++
| [[Linux]]
| Github repository maintained by Dmitry Kalinkin
| 1994
| [https://github.com/veprbl/es40 Github]
|-
| FTPD server
| An FTP server with support for UNIX file lists
|
| [[VAX]], [[Alpha]]
| Alan Fay
|
| [https://github.com/alan-fay/openvms Github]
|-
| Python
| Port of Python to OpenVMS
|
|
| VMS Software
|
| [https://github.com/vmssoftware/python_3_8_2 Github]
|-
| FileTypeDetector for OpenVMS files
| Java NIO.2 FileTypeDetector Implementations for OpenVMS Specific Files
| Java
|
| Mark Wickens
|
| [https://github.com/urbancamo/openvms-filetype-detectors Github]
|-
| Fixfilenames
| A simple program to fix filenames copied from OpenVMS system
| Go
|
|
| 2013
| [https://github.com/marben/vmsfixfilenames Github]
|-
| FreeMind
| FreeMind is a mind mapping tool written in Java and published under GPL. FreeMind can be used to take notes, build a knowledge base or keep track of projects.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=freemind OpenVMS Free softwares]
|-
| GNU for OpenVMS
| The GNV Project implements a port of the GNU utilities to OpenVMS with the intent of providing a framework for porting open source software to OpenVMS. A complementary SourceForge Project is VMS-Ports (https://sourceforge.net/projects/vms-ports/), there are discussions of process and procedure there as well as regular conference calls with recordings to review progress and assess how to improve the environment.
| C
|
| John Malmberg and others
|
| [https://sourceforge.net/projects/gnv/ Github]
|-
| GT.M for Alpha
| GT.M[tm] is a vetted industrial strength, transaction processing application platform consisting of a key-value database engine optimized for extreme transaction processing throughput & business continuity.
|
| [[Alpha]]
|
|
| [https://sourceforge.net/projects/fis-gtm/files/GT.M-Alpha-OpenVMS/ Github]
|-
| GhostScript
| GhostScript for OpenVMS
|
| [[Alpha]], [[Integrity]]
| Github repositpries maintained by Troy Makaro
| 2000
| [https://github.com/OpenVMSGhostScript/ executables], [https://sourceforge.net/projects/ghostscript/files/AFPL%20Ghostscript/8.54/ sources]
|-
| Gnulib Assist
| The Gnulib Assist project is a set of routines and header files needed to try to get GNULIB to build on OpenVMS / Ia64.
|
|
| John Malmberg
|
| [https://sourceforge.net/p/gnv/wiki/Gnulib%20Assist/ Sourceforge]
|-
| ImageJ
| ImageJ is a tool for image processing and analysis written in Java and placed in the public domain. ImageJ supports the usual formats (GIF, JPEG, XPM, PNG, TIFF…) and may be extended by plugins (more than 300 plugins are available).
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=imagej OpenVMS Free softwares]
|-
| JNA
| JNA (Java Native Access) is a Java library published under LGPL which provides Java programs easy access to native shared libraries (RTL, System services on OpenVMS) without writing anything but Java code – no JNI or native code is required.
|
|
| Ported by Phillippe Vouters
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jnaJNA OpenVMS Free softwares]
|-
| JOnAS
| JOnAS is a J2EE application server published under LGPL.
|
|
| Ported by Jean-Yves Bourlès and Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jonas Jonas on OpenVMS Free softwares], [http://vmsfree.ouvaton.org/freen/index.php?s=jonas5 Jonas5 on OpenVMS Free softwares]
|-
| JRuby
| A port of JRuby to VMS (possibly frozen)
|
|
| Philippe Vouters
| 2012
| [https://github.com/Vouters/jruby-openvms Github]
|-
| JRuby
| JRuby is a Java implementation of the Ruby programming language, which means that the Ruby programs run atop the JVM. JRuby is released under a three-way CPL/GPL/LGPL license.
|
|
| Ported by Thierry Uso and Philippe Vouters
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jruby OpenVMS Free softwares]
|-
| JRuby
| A port of JRuby to VMS (possibly frozen)
|
|
| Philippe Vouters
| 2012
| [https://github.com/Vouters/jruby-openvms Github]
|-
| JRuby
| JRuby is a Java implementation of the Ruby programming language, which means that the Ruby programs run atop the JVM. JRuby is released under a three-way CPL/GPL/LGPL license.
|
|
| Ported by Thierry Uso and Philippe Vouters
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jruby OpenVMS Free softwares]
|-
| JTrac
| JTrac is an issue-tracking web application written in Java under Apache License. The application is fast, easy to use and highly customizable for any kind of issues (bugs, tasks…).
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jtrac OpenVMS Free softwares]
|-
| JXplorer
| JXplorer is a LDAP client written in Java and published under a standard OSI-style open source licence. It allows to browse and modify any LDAP directory or any X500 directory with a LDAP interface.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jxplorer OpenVMS Free softwares]
|-
| JabRef
| JabRef is a bibliography reference manager written in Java and published under GPL. It uses BibTeX as bibliography file format and has advanced features (BibTeX editor, search function, classification of entries, import/export of various formats, launch of external viewers…).
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jabref OpenVMS Free softwares]
|-
| JavaRDP
| JavaRDP is a client for Windows Terminal Server written in Java and published under GPL. It is faster than VNC and can be used as a remote control tool.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=javardp OpenVMS Free softwares]
|-
| Jetty
| Jetty is a Web server (HTTP server and servlet container) for static and dynamic content written in Java under Apache 2.0 license.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jetty Jetty on OpenVMS Free softwares], [http://vmsfree.ouvaton.org/freen/index.php?s=jetty6 Jetty 6 on OpenVMS Free softwares]
|-
| Jperf
| Jperf is a graphical frontend for Iperf written in Java. Iperf measures TCP and UDP performance (bandwidth, delay, jitter, loss). JPerf is released under a LGPL license.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jperf OpenVMS Free softwares]
|-
| Jsynoptic
| Jsynoptic is a tool dedicated to render data graphically. It is written in Java under LGPL. Data can come from different sources (files, network…) and can be static or dynamic.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=jsynoptic OpenVMS Free softwares]
|-
| LIBVMS
| This package is a reimplementation of the OpenVMS system services for use in a POSIX environment.
| C
|
| Tim Sneddon
| 2013
| [https://github.com/tesneddon/libvms Github]
|-
| Lucane
| Lucane is a groupware platform written in Java and published under LGPL. It offers the usual groupware functions such as calendar, forum, instant messaging, file sharing… and may be easily extended by plugins. Lucane has an embedded database (hsqldb) but an external database (mySQL…) can be used instead of hsqldb. Users access Lucane by a Java client or a browser (IE, Mozilla…).
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=lucane OpenVMS Free softwares]
|-
| MD5 sum
| A utility to print or check MD5 checksums (RFC 1321)
|
| [[VAX]], [[Alpha]]
| Alan Fay
|
| [https://github.com/alan-fay/openvms Github]
|-
| MMK/MAKE
| MMK is a "make" utility for VMS systems
| C, Macro
| [[VAX]], [[Alpha]], [[Integrity]]
| Matthew Madison
| 1992
| [https://github.com/endlesssoftware/mmk V5.1 on Github], V3.9-9 featured in [https://www.digiater.nl/openvms/freeware/v80/make-mmk/ Freeware CD V80]
|-
| MX
| Email-exchange software
| C, C++
| [[VAX]], [[Alpha]], [[Integrity]]
| Matthew Madison
| 1994
| [https://github.com/endlesssoftware/mx Version 6.0 on Github], featured in Freeware CD ([https://www.digiater.nl/openvms/freeware/v10/mx041/ V4.1], [https://www.digiater.nl/openvms/freeware/v30/mx041/ V4.2])
|-
| MakeShare
| Creates a command procedure to link a shared imaged from an object library
| DCL
| [[Alpha]] and [[Integrity]]
| Steve Ives
|
| [https://github.com/SteveIves/MakeShare Github]
|-
| Martineg's DCL scripts
| Miscellaneous DCL scripts: batch resubmit, LOGIN.COM, etc.
| DCL
|
| Martin Eggen
|
| [https://github.com/martineg/openvms-dcl Github]
|-
| MibbleBrowser
| MibbleBrowser is a SNMP MIB browser written in Java and published under GPL. It uses the Mibble library as SMI parser and supports SNMPv1, SNMPv2c and SNMPv3.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=mibble OpenVMS Free softwares]
|-
| NETLIB
| A library for writing TCP/IP based network applications. NETLIB provides a consistent, VMS-style interface for TCP/IP-based network programs, operating with all of the currently available TCP/IP packages available today for VMS (with one minor exception). In addition, NETLIB allows for flexibility in in the use of a TCP/IP package, by selecting the vendor-dependent library code at run-time, rather than link-time.
| C, Visual Basic
| [[VAX]], [[Alpha]]
| Hunter Goatley
|
| [https://github.com/endlesssoftware/netlib Github]
|-
| NRPE daemon for OpenVMS
| A you to remotely execute Nagios plugins on OpenVMS machines.
| C
| [[VAX]], [[Alpha]]
|
|
| [https://github.com/ordenador/nrpevms Github]
|-
| Net-SNMP 5.0.1 port to OpenVMS
| Net-SNMP v5.0.1 port to OpenVMS
| C
| [[Alpha]]
| Ported to OpenVMS by Stewart M. Smith for Siemens AG, released by Giles Burrows (Siemens AG)
| 2016
| [https://github.com/tenox7/net-snmp-v501-vms Github]
|-
| NetElf
| Run the client side of NetELF to download and execute a program over the network from a server. The server sends an arbitrary binary and command-line arguments.
| C
|
| Harry Roberts
| 2017
| [https://github.com/XiphosResearch/netelf Github]
|-
| NetWhistler
| NetWhistler is a network mapping and monitoring tool written in Java and published under GPL. It includes network discovery and diagnostic tools (ping, services monitoring, MIB browser, SNMP trap receiver console, MRTG console…).
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=netwhistler OpenVMS Free softwares]
|-
| ODS2 File System readers
| ODS2 is a program to read VMS disk volumes written in VMS ODS2 format. Provides cut down DIRECTORY, COPY and SEARCH commands for VMS volumes on non-VMS systems. These can be used to find out what is on a VMS volume, and copy files onto the local file sytem.
| C
|
| Paul Nankervis, maintained on Github by Oleg Pyzin
| 1998
| [https://github.com/FreeBSD-pzn/ods2 Github]
|-
| OMI
| A menu interpreter for OpenVMS, entirely written in DCL (OMI)
|
|
| Oscar van Eijk
|
| [https://github.com/oveas/OMI Github]
|-
| OmniORB for OpenVMS
| omniORB is a CORBA object request broker for C++ and Python. It is very fast, robust, and standards-compliant.
| C++
| [[Alpha]]
| Duncan Grisby
|
| [https://sourceforge.net/p/omniorb/svn/6253/tree/trunk/omniORB/readmes/README.openvms Github]
|-
| OpenBmx
| A Vagrantfile for a OpenVMS porting box using the alphavm emulator on a Ubuntu Linux box.
|
|
| Martin Borgman
|
| [https://github.com/martinborgman/portingbox Github]
|-
| OpenSDL
| Open version of the OpenVMS Structure Definition Language (SDL).
| C, Yacc, Lex
|
| Jonathan Belanger
| 2007
| [https://github.com/JonathanBelanger/OpenSDL Github]
|-
| OpenVMS migration utilities
| A utility that converts a OpenVMS Variable Length (VL) format file into a stream of bytes with additional line endings if required.
| C, bash
|
| Freddie Akeroyd
| 2016
| [https://github.com/FreddieAkeroyd/VMS-utils Github]
|-
| OpenVMS-DCL-Sublime-Lang-Support
| This repository contains code necessary to make Sublime Text 3 aware of the 'DIGITAL Command Language' used by HP's OpenVMS operating system.
|
|
| Gleb Nikonorov
|
| [https://github.com/gnikonorov/OpenVMS-DCL-Sublime-Lang-Support Github]
|-
| OpenVMS-DCL-VSCODE-Lang-Support
| This extension is for DCL batch scripts. These are typically ran on OpenVMS systems, and are similar to BASH scripts
| TypeScript
|
| Tom Esparson based on work by Gleb Nikonorov
|
| [https://github.com/tomesparon/OpenVMS-DCL-VSCODE-Lang-Support Github]
|-
| OpenVMS-Oracle-Rdb-Toolset
| Ready to use procedures for a database administrator of Oracle Rdb databases on OpenVMS.
|
|
| Luc Allemeersch
|
| [https://github.com/LucAllemeersch/OpenVMS-Oracle-Rdb-Toolset Github]
|-
| OpenVMS-RMS-DecBasic-Macro64
| Try to create a OpenVMS project from memory using RMS-FDL-DECBasic on a OpenVMS system. (notes)
|
|
| Jason Loewecke
|
| [https://github.com/jloewecke/OpenVMS-RMS-DecBasic-Macro64 Github]
|-
| Openfire
| Openfire is an instant messaging written in Java and published under GPL. It uses the XMPP (also called Jabber) protocol.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=openfire OpenVMS Free softwares]
|-
| PLIBSYS
| A cross-platform system C library with some helpful routines. It has zero third-party dependencies and uses only native system calls.
| C, C++
|
| Alexander Saprykin
|
| [https://github.com/saprykin/plibsys Github], [https://github.com/saprykin/plibsys/wiki wiki]
|-
| REST API component of OVMS
| REST API component of the OVMS platform.
| Javascript
|
| Nathan (najowhit)
|
| [https://github.com/najowhit/nodeAPI_OpenVMS Github]
|-
| Ruby
| A port of Ruby for OpenVMS based on Ruby 1.8.2 (MRI). This work is in early alpha development stage and not suitable for release yet
| C, Ruby, HTML, Yacc
| [[Alpha]]
| Ben Armstrong
|
| [https://github.com/bg/vmsruby Github]
|-
| Ruby for openvms webpage archive
| Web pages dedicated to Ruby for OpenVMS
| HTML
|
|
|
| [https://github.com/xiaotuanzi/vmsruby Github]
|-
| SDL
| A portable processor for Structure Definition Language (a child of the OpenVMS SDL)
| C
|
| Ruslan Laishev
|
| [https://github.com/SysMan-One/SDL Github]
|-
| SIMH VAX VMS
| A MicroVAX 3900 simulator
|
| Docker
|
|
| [https://github.com/k3ck3c/simh_vax_vms Github]
|-
| SQLite 3
| This is a native port of the SQLite database package to OpenVMS. It delivers the SQLite database to OpenVMS using the following native features:
* Thread support using the tis library. This allows support for multi-threading without having to link against the pthreads RTL.
* Direct file access. All files access is performed using the $QIO [[System Service|system services]], rather than the C RTL or even [[RMS]].
* Native locking. All locking is handled using the OpenVMS [[Distributed Lock Manager|distributed lock manager]], allowing database access to be coordinated across [[Cluster|cluster]] nodes (of all architectures).
Despite these OpenVMS-specific improvements the database file maintained by SQLite is still portable to other SQLite-based applications running on other systems.
| C
| [[VAX]], [[Alpha]], [[Integrity]]
| Tim Sneddon
| 2013
| [https://github.com/endlesssoftware/sqlite3/blob/master/readme.txt Github]
|-
| SQuirreL
| SQuirreL is a SQL client written in Java and published under LGPL. It allows to view the structure of a JDBC compliant database, browse the data in tables, issue SQL commands…
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=squirrel OpenVMS Free softwares]
|-
| SYSUAF authentication for the Mosquito MQTT broker
| A simple plugin for the Mosquitto MQTT broker (http://mosquitto.org) that provides the ability for the broker to authenticate users via standard OpenVMS means (namely checking the supplied credentials against those in SYSUAF).
| C
|
| Brett Cameron
|
| [https://github.com/brc859844/mosquitto-auth-plugin-vms Github]
|-
| Scala
| Scala is a general purpose programming language published under a BSD-style license. It combines functional and object-oriented techniques, provides a number of powerful features (closures, actors…) and is fully interoperable with Java.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=scala OpenVMS Free softwares]
|-
| StarLet File Transfer Utility
| This is a utility to transfering VMS's files over the TCP/IP network to a remote non-VMS hosts, a like the FTP or SFTP but with additional features: resuming broken transfers and generating FDL file to help restoring RMS's attributes on VMS hosts.
| C
|
| Ruslan Laishev
|
| [https://github.com/SysMan-One/SFTU Github]
|-
| Superversion
| Superversion is a version control system written in Java and published under GPL. It is an alternative to free solutions (CVS, Subversion…) running on Unix or commercial solutions (CMS…) running on OpenVMS. The stable version (Superversion 1.2) is a standalone and single-user application. The following version (Superversion 2.0) will be a client-server and multi-user application.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=suv OpenVMS Free softwares]
|-
| T4 monitor
| t4Monitor is a module for Windows and Linux that allows easy collection, preprocessing and reporting of generic OpenVMS' T4 compliant counters stored in Format-1 or Format-2 Comma Separated Values (CSV) files.
| Python
|
| J.M. Fernández
| 2014
| [https://github.com/fernandezcuesta/t4Monitor Github]
|-
| TAIL
| Performs a Variation of TYPE/TAIL on a File
| C
|
| Oleg Pyzin
|
| [https://github.com/FreeBSD-pzn/tail Github]
|-
| TAO
| CORBA implementation
| C++
| [[Alpha]], [[Integrity]]
| DOCGroup, ported by Remedy IT
|
| [https://github.com/DOCGroup/ACE_TAO Github]
|-
| UnQLite
| A VMS port of unqlite-db 1.1.6. UnQLite is a transactional NoSQL database in the same vein as SQLite.
| C
| [[Alpha]], [[Integrity]]
|
| 2012
| [https://github.com/endlesssoftware/unqlite Github]
|-
| UsingJenkinsCI (wiki)
| Using Jenkins CI To Build OpenVMS Programs
|
|
| John Malmberg and others
|
| [https://sourceforge.net/p/vms-ports/wiki/UsingJenkinsCi/ Github]
|-
| VMS ports
| Open Source and Freeware for OpenVMS
|
|
| collection by Bill Pedersen and others
|
| [https://sourceforge.net/projects/vms-ports/files/ Github]
|-
| VMSComFiles
| Lorin Ricker's personal VMS command and auxiliary support files
| [[DCL]]
|
| Lorin Ricker
|
| [https://github.com/LorinRicker/VMScomfiles Github]
|-
| VMS IDE
| Visual Studio Code Extension for OpenVMS
| [[C]]
|
| VMS Software
|
| [https://github.com/vmssoftware/vms-ide Github]
|-
| VMShistory
| A collection of historical and descriptive documents about the History and Development of the VMS (OpenVMS) operating system
|
|
| Lorin Ricker
|
| [https://github.com/LorinRicker/VMShistory Github]
|-
| VTFM https://github.com/FreeBSD-pzn/vtfm
|
|
|
|
|
|
|-
| VmsCompatibility
| A collection of DBL subroutines and functions that implement, emulate or shim the functionality of various OpenVMS system service routines.
| DBL
|
|
| Kish Baley
| [https://github.com/Synergex/VmsCompatibility Github]
|-
| WASD_LDAP_AUTHAGENT
| A modification to WASD that allows you to authenticate users against external LDAP server WITHOUT corresponding SYSUAF records.
| C++, Perl
|
| Thomas Morstein
|
| [https://github.com/ztmr/WASD_LDAP_AUTHAGENT Github]
|-
| WATCHER
| WATCHER is an idle terminal monitor. It logs out interactive users after a certain period of inactivity. WATCHER is fully configurable, allowing the system manager to define which terminals to watch, what measurements to use, and how long a terminal should be idle before getting zapped. It also includes provisions for preventing logouts or overriding inactivity settings based on any combination of username, UIC, terminal, privileges, image being run, held identifier, and time of day.
| BLISS
| [[VAX]], [[Alpha]], [[Integrity]]
| Matthew Madison
| 1994
| [https://github.com/endlesssoftware/watcher V4.1 on Github], [https://www.digiater.nl/openvms/freeware/v10/watcher/ V2.9-1 in Freeware]
|-
| Word count new utility. OpenVMS and *NIX OSes.
| Rework of wc
| C
|
| Oleg Pyzin based on original wc code
|
| [https://github.com/FreeBSD-pzn/wcn Github]
|-
| curl-parallel
| Using CURL to parallel download large datafiles
| DCL
|
| taupirho
|
| [https://github.com/taupirho/curl-parallel Github]
|-
| frontend_openvms
| OpenVMS Frontend
| Java, HTML, CSS
|
| Nathan (najowhit)
|
| [https://github.com/najowhit/frontend_OpenVMS Github]
|-
| httping
| httping is a command line tool monitoring the response time of a Web server. It is written in C and published under GPL.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=httping OpenVMS Free softwares]
|-
| iReport
| iReport is a data reporting tool written in Java and published under GPL. It offers a GUI to the report generator JasperReport. Reports can be built in several formats (PDF, HTML…) from data collected by JDBC…
|
|
| Ported by Jean-Yves Bourlès
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=ireport OpenVMS Free softwares]
|-
| libffi
| libffi is a library which allows a programmer to call any function specified by a call interface description at run-time and which is used by Java (JNA), Python (Ctypes) and Jruby (Jffi). libffi is written in C and published under a very liberal license.
|
|
| Ported by Philippe Vouters
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=libffi OpenVMS Free softwares]
|-
| muCommander
| muCommander is a file manager written in Java and published under GPL. It has also the additional features of (S)FTP, NFS, SMB client and ZIP, JAR, TAR archive brower.
|
|
| Ported by Thierry Uso
|
| [http://vmsfree.ouvaton.org/freen/index.php?s=mucommander OpenVMS Free softwares]
|-
| shasum
| A utility to print or check SHA checksums (FIPS PUB 180-2)
|
| [[VAX]], [[Alpha]]
| Alan Fay
|
| [https://github.com/alan-fay/openvms Github]
|-
| spop3
| Pop3 server
|
|
| Ruslan R. Laishev
|
| [https://sourceforge.net/projects/vms-ports/files/spop3/ Sourceforge]
|-
| vmsbackup
| Program to read OpenVMS backup save sets on non-VMS machines
| C
|
| Freddie Akeroyd
|
| [https://github.com/FreddieAkeroyd/vmsbackup Github]
|-
| vmsperlkit
| Kitting procedures for Perl on OpenVMS
|
|
| Craig A. Berry
|
| [https://sourceforge.net/projects/vmsperlkit/files/ Sourceforge]
|-
| vmsport
| Experiments in porting an OpenVMS Fortran / Decforms application to Linux and Gfortran
|
|
|
| Svante Lidman
| [https://github.com/Coreboost/vmsport Github]
|}

[[Category:Freeware]]

Axis2 - Easy Installation Guide

2021-10-07T15:40:21Z

Axel.elfving: /* Enabling HTTPS for Axis2 */

This is an easy installation guide that will take you through how to install and configure Apache Axis2 for use with the Tomcat web server on OpenVMS. Before starting the installation, it is a good idea to read through the “Tomcat (CSWS JAVA) - Easy Installation Guide” and make sure that you have you installed and configured Tomcat correctly.

The document also contains instructions for how to set up an AJP Connector between CSWS Apache Web Server and Apache Axis2 on Tomcat. If that is something you wish to do, you need to already have Apache installed and fully configured on your system. For instructions on how to install and configure Apache, consult either the Apache release notes or the “Apache (CSWS) - Easy Installation Guide”.

For more guides like this, check out the main page (coming).

=Introduction=

Go through the following steps to install Axis2.

* Unpack the kit with the $ RUN command

<pre>
$ run VSI-I64VMS-AXIS2-V0107-3-1.ZIPEXE
</pre>

:Then, install Axis2 with the command

<pre>
$ product install axis2
Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.AXIS2]
vsi-i64vms-axis2-v0107-3-1.pcsi$compressed;1 succeeded

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 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 AXIS2 V1.7-3

VMS Software Inc. and The Apache Software Foundation.

Minimum JDK software version not found on system, abort installation

This kit requires the minimum Java version of 1.8.

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 AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
%PCSIUI-I-COMPWERR, operation completed after explicit continuation
from errors
</pre>

:Comment for the highlighted part of the installation output: If you have OpenJDK8 installed on a system that previously did not have JAVA installed on it, 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 and Axis2.

=Configuration=

These instructions will guide you through how to define the necessary Axis2 logicals on start-up before showing you how to set up the AJP Connector.

==Automatic Start-up Commands==

Follow these instructions if you want Axis2 logicals to be defined automatically when rebooting the system.

* Edit the file SYS$MANAGER:SYLOGICALS.COM add the lines specified below (in the section where you are asked to define site-specific logicals) to define the Axis2 logicals on start-up. Make sure to specify the correct node for your system (highlighted in yellow).

<pre>
$ edit sys$manager:sylogicals.com

...

$! ******************************************************************
$! Define any site-specific logical names below:
$! ******************************************************************

...

$ IF NODE .EQS. "YOUR_NODE_NAME"
$ THEN
$ file := SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ <nowiki>if f$search("''file'") .nes. "" then @'file'</nowiki>
$ ENDIF

...
</pre>

==Defining Axis2 Logicals==

Now is a good time to manually define the Axis2 logicals.

* Run the same file you included in the start-up procedure in the previous section. Most notably, this will define the logical AXIS2$ROOT – giving us easy access to the Axis2 root directory.

<pre>
$ @SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ show logical *axis*

(LNM$PROCESS_TABLE)

(LNM$JOB_89235900)

"AXIS$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Deploying Axis2 WAR File in Tomcat==

To enable Axis2 and integrate it with Tomcat, we need to deploy the Axis2 WAR file in the directory TOMCAT$ROOT:[WEBAPPS].

* Copy the file AXIS2$ROOT:[OPENVMS]axis2.war to TOMCAT$ROOT:[WEBAPPS] and make sure the file has TOMCAT$WWW as owner and the appropriate protections.

<pre>
$ copy /log axis2$root:[openvms]axis2.war tomcat$root:[webapps]
%COPY-S-COPIED, AXIS2$ROOT:[OpenVMS]axis2.war;1 copied to TOMCAT$ROOT:[webapps]axis2.war;1 (19.27MB)

$ dir /sec tomcat$root:[webapps]axis2.*

Directory TOMCAT$ROOT:[webapps]

axis2.DIR;1 [TOMCAT$WWW] (RWED,RWED,RE,)
axis2.war;1 [TOMCAT$WWW] (RWED,RWED,RE,RE)

Total of 1 file.

$ set file /prot=(S:RWE,O:RWED,G,W) tomcat$root:[webapps]axis2.* /log
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.war;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps.axis2]axis2-web.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
...
</pre>

:If automatic deployment is configured correctly for Tomcat, the WAR file should be unpacked automatically during runtime, resulting in the creation of TOMCAT$ROOT:[WEBAPPS]axis2.DIR.

* If you are in a production environment, or for some other reason do not wish to use automatic deployment, you may wish to deploy your WAR files using the Tomcat interface – this will allow you to deploy WAR files from a separate directory and thus run a lower risk of unexpectedly overwriting files in use.

:You may also wish to disable automatic deployment, so that WAR files placed in your TOMCAT$ROOT:[WEBAPPS] directory do not automatically deploy and overwrite your existing configuration files. To do this, edit TOMCAT$ROOT:[CONF]server.xml and set autoDeploy to “false”, as shown below. Then restart Tomcat to implement the changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...

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

...
</pre>

:Lastly, to manually deploy AXIS2$ROOT:[OPENVMS]axis2.war directly from its directory, visit your Tomcat server and enter the Manager App. Under “Deploy directory or WAR file located on server”, enter the information shown below.

<pre>
Context Path (required): /axis2
XML Configuration file path:
WAR or Directory path: axis2$root:[openvms]axis2.war
</pre>

:Note: Although you set autoDeploy to “false”, Tomcat will still deploy WAR files on start-up. Therefore, to avoid unexpected deployment, it is advisable to keep WAR files you do not wish to deploy outside your TOMCAT$ROOT:[WEBAPPS] directory.

==Enabling HTTPS for Axis2==

* Change the Axis2 Administrator account username and password, edit the file TOMCAT$ROOT:[000000.webapps.axis2.WEB-INF.conf]axis2.xml and make sure that you change these two lines (located close to the top of the file) and set a secure password.

<pre>
$ edit tomcat$root:[000000.webapps.axis2.web-inf.conf]axis2.xml

...

<parameter name="userName">admin</parameter>
<parameter name="password">axis2</parameter>

...
</pre>

:In the same file, if you wish to use HTTPS with Axis2, scroll down until you find the section that reads

<pre>
...






</pre>

:Edit the lines directly underneath, adding the transportReceiver for HTTPS (highlighted in yellow), so that the two transportReceiver directives read

<pre>
<transportReceiver name="http"
class="org.apache.axis2.transport.http.AxisServletListener"/>
<transportReceiver name="https"
class="org.apache.axis2.transport.http.AxisServletListener"/>

...
</pre>

* Make sure to restart Tomcat so that the configuration changes are implemented.

<pre>
$ @sys$startup:tomcat$shutdown.com
$ submit/user=tomcat$www/queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com

$ show system
...
0000046F APACHE$TOMCAT HIB 4 70149 0 00:00:53.85 56117 47489 M
...
</pre>

* Lastly, connect to Axis2 using the HTTPS to test the connection with the URL shown below. If the connections fails, you may want to review this guide as well as the “Tomcat (CSWS JAVA) – Easy Installation Guide” or review the log files in TOMCAT$ROOT:[000000.logs].

<pre>
https://your.server.com:8443/axis2/
</pre>

==Setting up the AJP Connector==

This section will show you how to set up the AJP Connector, which will allow you to integrate Tomcat into an existing Apache Web Server installation so that you can access Axis2 through Apache. Thus, it is necessary for Apache to be installed and working correctly. For instruction on how to install Apache, see the “Apache (CSWS) - Easy Installation Guide”.

* Edit the file TOMCAT$ROOT:[CONF]server.xml and confirm that the following directive is uncommented and that redirectPort points to the HTTPS port you have specified for Tomcat. If any of the information is incorrect, make the necessary changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

...
</pre>

* Next edit Apache’s main configuration file APACHE$ROOT:[000000.CONF]HTTPD.CONF and scroll down until you reach the list of loadable modules. Uncomment the following modules by removing the number signs (#) in front of the LoadModule directives.

<pre>
$ edit apache$root:[000000.conf]httpd.conf

...

LoadModule proxy_module modules/mod_proxy.exe
LoadModule proxy_ajp_module modules/mod_proxy_ajp.exe

...
</pre>

:Next, add the <Location> directive shown below at the very bottom of the same file. The DNS name highlighted in yellow should match that of your server. It is possible to use your IP address instead, though that might by-pass the certificate you have in place for your server and unable you from establishing an HTTPS connection to Axis2.

<pre>
...

<Location "/axis2">
ProxyPass "ajp://example.eng.vmssoftware.com:8009/axis2"
</Location>

...
</pre>

:Lastly, for Apache to implement these changes, it needs to be restarted. You can do this with

<pre>
$ @sys$startup:apache$shutdown
$ @sys$startup:apache$startup
</pre>

* To see if the AJP connector has been set up correctly, connect to Axis2 on either port 80 (HTTP) or port 443 (HTTPS). The 8009 port specified for the AJP Connector is used internally.

<pre>
http://example.eng.vmssoftware.com:80/axis2/
https://example.eng.vmssoftware.com:443/axis2/
</pre>

=Removal=

To remove Axis2, follow these instructions. If you also want to remove Tomcat, make sure you remove Axis2 first.

* First, shut down Tomcat.

<pre>
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
</pre>

* Then, uninstall Axis2 using the command below.

<pre>
$ product remove axis2

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been removed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
</pre>

* If you do not wish to remove Tomcat, but want to do a complete removal of Axis2, you can selectively remove the files belonging to Axis2 to inside TOMCAT$ROOT:[000000.webapps].

<pre>
$ delete tomcat$root:[webapps]axis2.war;1 /conf
DELETE TOMCAT$ROOT:[webapps]axis2.war;1 ? [N]: Y
</pre>

:If using the $ DELETE /TREE command when deleting the Axis2.DIR directory structure inside TOMCAT$ROOT:[000000.webapps], make sure that you are not deleting any files by mistake before executing this command. All files will be deleted instantaneously, so use the command at your own risk.

<pre>
$ delete /tree TOMCAT$ROOT:[000000.webapps.AXIS2...]*.*;* /log
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]error.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]HappyAxis.jsp;1 deleted
(24KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]index.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listFaultyService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listGroupService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listServices.jsp;1
deleted (8KB)
...

$ delete TOMCAT$ROOT:[000000.webapps]AXIS2.DIR;1 /conf
DELETE TOMCAT$ROOT:[000000.webapps]axis2.DIR;1 ? [N]: Y
</pre>

* In addition to deleting the Axis2 files, you should also go through the configuration changes made earlier in this document and revert the relevant changes.
* If you want to completely remove any traces of Axis2 you should know that the AXIS2$ROOT logical is still defined, although it now points to a non-existent directory. You can remove the logical using the $ DEASSIGN command.

<pre>
$ show logical *axis2*

(LNM$PROCESS_TABLE)

(LNM$JOB_892FB880)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
$ deassign /sys axis2$root
</pre>

* If you have a look inside SYS$STARTUP, you can see that there are also some Axis2 remnants remaining in there. You can either remove these files individually or with a wildcard qualifier (as shown below) together with the /CONFIRM qualifier. It is always advisable to use extra caution when deleting files, especially in system directories, since deleted files are not recoverable unless backed up.

<pre>
$ dir sys$startup:*axis2*

Directory SYS$SYSROOT:[SYSMGR]

axis2$define_logicals.LOG;2 axis2$define_logicals.LOG;1
axis2-tmp-8889454529806580694^.tmp.DIR;1

Total of 3 files.

Directory SYS$COMMON:[SYSMGR]

axis2$define_logicals.com;1

Total of 1 file.

Grand total of 2 directories, 3 files.
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;2 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;1 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1 ? [N]: Y
%DELETE-W-FILNOTDEL, error deleting SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1
-RMS-E-MKD, ACP could not mark file for deletion
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty
DELETE SYS$COMMON:[SYSMGR]axis2$define_logicals.com;1 ? [N]: Y
</pre>

Axis2 - Easy Installation Guide

2021-10-07T15:37:34Z

Axel.elfving: /* Automatic Start-up Commands */

This is an easy installation guide that will take you through how to install and configure Apache Axis2 for use with the Tomcat web server on OpenVMS. Before starting the installation, it is a good idea to read through the “Tomcat (CSWS JAVA) - Easy Installation Guide” and make sure that you have you installed and configured Tomcat correctly.

The document also contains instructions for how to set up an AJP Connector between CSWS Apache Web Server and Apache Axis2 on Tomcat. If that is something you wish to do, you need to already have Apache installed and fully configured on your system. For instructions on how to install and configure Apache, consult either the Apache release notes or the “Apache (CSWS) - Easy Installation Guide”.

For more guides like this, check out the main page (coming).

=Introduction=

Go through the following steps to install Axis2.

* Unpack the kit with the $ RUN command

<pre>
$ run VSI-I64VMS-AXIS2-V0107-3-1.ZIPEXE
</pre>

:Then, install Axis2 with the command

<pre>
$ product install axis2
Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.AXIS2]
vsi-i64vms-axis2-v0107-3-1.pcsi$compressed;1 succeeded

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 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 AXIS2 V1.7-3

VMS Software Inc. and The Apache Software Foundation.

Minimum JDK software version not found on system, abort installation

This kit requires the minimum Java version of 1.8.

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 AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
%PCSIUI-I-COMPWERR, operation completed after explicit continuation
from errors
</pre>

:Comment for the highlighted part of the installation output: If you have OpenJDK8 installed on a system that previously did not have JAVA installed on it, 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 and Axis2.

=Configuration=

These instructions will guide you through how to define the necessary Axis2 logicals on start-up before showing you how to set up the AJP Connector.

==Automatic Start-up Commands==

Follow these instructions if you want Axis2 logicals to be defined automatically when rebooting the system.

* Edit the file SYS$MANAGER:SYLOGICALS.COM add the lines specified below (in the section where you are asked to define site-specific logicals) to define the Axis2 logicals on start-up. Make sure to specify the correct node for your system (highlighted in yellow).

<pre>
$ edit sys$manager:sylogicals.com

...

$! ******************************************************************
$! Define any site-specific logical names below:
$! ******************************************************************

...

$ IF NODE .EQS. "YOUR_NODE_NAME"
$ THEN
$ file := SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ <nowiki>if f$search("''file'") .nes. "" then @'file'</nowiki>
$ ENDIF

...
</pre>

==Defining Axis2 Logicals==

Now is a good time to manually define the Axis2 logicals.

* Run the same file you included in the start-up procedure in the previous section. Most notably, this will define the logical AXIS2$ROOT – giving us easy access to the Axis2 root directory.

<pre>
$ @SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ show logical *axis*

(LNM$PROCESS_TABLE)

(LNM$JOB_89235900)

"AXIS$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Deploying Axis2 WAR File in Tomcat==

To enable Axis2 and integrate it with Tomcat, we need to deploy the Axis2 WAR file in the directory TOMCAT$ROOT:[WEBAPPS].

* Copy the file AXIS2$ROOT:[OPENVMS]axis2.war to TOMCAT$ROOT:[WEBAPPS] and make sure the file has TOMCAT$WWW as owner and the appropriate protections.

<pre>
$ copy /log axis2$root:[openvms]axis2.war tomcat$root:[webapps]
%COPY-S-COPIED, AXIS2$ROOT:[OpenVMS]axis2.war;1 copied to TOMCAT$ROOT:[webapps]axis2.war;1 (19.27MB)

$ dir /sec tomcat$root:[webapps]axis2.*

Directory TOMCAT$ROOT:[webapps]

axis2.DIR;1 [TOMCAT$WWW] (RWED,RWED,RE,)
axis2.war;1 [TOMCAT$WWW] (RWED,RWED,RE,RE)

Total of 1 file.

$ set file /prot=(S:RWE,O:RWED,G,W) tomcat$root:[webapps]axis2.* /log
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.war;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps.axis2]axis2-web.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
...
</pre>

:If automatic deployment is configured correctly for Tomcat, the WAR file should be unpacked automatically during runtime, resulting in the creation of TOMCAT$ROOT:[WEBAPPS]axis2.DIR.

* If you are in a production environment, or for some other reason do not wish to use automatic deployment, you may wish to deploy your WAR files using the Tomcat interface – this will allow you to deploy WAR files from a separate directory and thus run a lower risk of unexpectedly overwriting files in use.

:You may also wish to disable automatic deployment, so that WAR files placed in your TOMCAT$ROOT:[WEBAPPS] directory do not automatically deploy and overwrite your existing configuration files. To do this, edit TOMCAT$ROOT:[CONF]server.xml and set autoDeploy to “false”, as shown below. Then restart Tomcat to implement the changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...

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

...
</pre>

:Lastly, to manually deploy AXIS2$ROOT:[OPENVMS]axis2.war directly from its directory, visit your Tomcat server and enter the Manager App. Under “Deploy directory or WAR file located on server”, enter the information shown below.

<pre>
Context Path (required): /axis2
XML Configuration file path:
WAR or Directory path: axis2$root:[openvms]axis2.war
</pre>

:Note: Although you set autoDeploy to “false”, Tomcat will still deploy WAR files on start-up. Therefore, to avoid unexpected deployment, it is advisable to keep WAR files you do not wish to deploy outside your TOMCAT$ROOT:[WEBAPPS] directory.

==Enabling HTTPS for Axis2==

* Change the Axis2 Administrator account username and password, edit the file TOMCAT$ROOT:[000000.webapps.axis2.WEB-INF.conf]axis2.xml and make sure that you change these two lines (located close to the top of the file) and set a secure password.

<pre>
$ edit tomcat$root:[000000.webapps.axis2.web-inf.conf]axis2.xml

...

<parameter name="userName">admin</parameter>
<parameter name="password">axis2</parameter>

...
</pre>

:In the same file, if you wish to use HTTPS with Axis2, scroll down until you find the section that reads

<pre>
...






</pre>

:Edit the lines directly underneath, adding the transportReceiver for HTTPS (highlighted in yellow), so that the two transportReceiver directives read

<pre>
<transportReceiver name="http"
class="org.apache.axis2.transport.http.AxisServletListener"/>
<transportReceiver name="https"
class="org.apache.axis2.transport.http.AxisServletListener"/>

...
</pre>

* Make sure to restart Tomcat so that the configuration changes are implemented.

<pre>
$ @sys$startup:tomcat$shutdown.com
$ submit/user=tomcat$www/queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
$ show system
...
0000046F APACHE$TOMCAT HIB 4 70149 0 00:00:53.85 56117 47489 M
...
</pre>

* Lastly, connect to Axis2 using the HTTPS to test the connection with the URL shown below. If the connections fails, you may want to review this guide as well as the “Tomcat (CSWS JAVA) – Easy Installation Guide” or review the log files in TOMCAT$ROOT:[000000.logs].

<pre>
https://your.server.com:8443/axis2/
</pre>

==Setting up the AJP Connector==

This section will show you how to set up the AJP Connector, which will allow you to integrate Tomcat into an existing Apache Web Server installation so that you can access Axis2 through Apache. Thus, it is necessary for Apache to be installed and working correctly. For instruction on how to install Apache, see the “Apache (CSWS) - Easy Installation Guide”.

* Edit the file TOMCAT$ROOT:[CONF]server.xml and confirm that the following directive is uncommented and that redirectPort points to the HTTPS port you have specified for Tomcat. If any of the information is incorrect, make the necessary changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

...
</pre>

* Next edit Apache’s main configuration file APACHE$ROOT:[000000.CONF]HTTPD.CONF and scroll down until you reach the list of loadable modules. Uncomment the following modules by removing the number signs (#) in front of the LoadModule directives.

<pre>
$ edit apache$root:[000000.conf]httpd.conf

...

LoadModule proxy_module modules/mod_proxy.exe
LoadModule proxy_ajp_module modules/mod_proxy_ajp.exe

...
</pre>

:Next, add the <Location> directive shown below at the very bottom of the same file. The DNS name highlighted in yellow should match that of your server. It is possible to use your IP address instead, though that might by-pass the certificate you have in place for your server and unable you from establishing an HTTPS connection to Axis2.

<pre>
...

<Location "/axis2">
ProxyPass "ajp://example.eng.vmssoftware.com:8009/axis2"
</Location>

...
</pre>

:Lastly, for Apache to implement these changes, it needs to be restarted. You can do this with

<pre>
$ @sys$startup:apache$shutdown
$ @sys$startup:apache$startup
</pre>

* To see if the AJP connector has been set up correctly, connect to Axis2 on either port 80 (HTTP) or port 443 (HTTPS). The 8009 port specified for the AJP Connector is used internally.

<pre>
http://example.eng.vmssoftware.com:80/axis2/
https://example.eng.vmssoftware.com:443/axis2/
</pre>

=Removal=

To remove Axis2, follow these instructions. If you also want to remove Tomcat, make sure you remove Axis2 first.

* First, shut down Tomcat.

<pre>
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
</pre>

* Then, uninstall Axis2 using the command below.

<pre>
$ product remove axis2

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been removed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
</pre>

* If you do not wish to remove Tomcat, but want to do a complete removal of Axis2, you can selectively remove the files belonging to Axis2 to inside TOMCAT$ROOT:[000000.webapps].

<pre>
$ delete tomcat$root:[webapps]axis2.war;1 /conf
DELETE TOMCAT$ROOT:[webapps]axis2.war;1 ? [N]: Y
</pre>

:If using the $ DELETE /TREE command when deleting the Axis2.DIR directory structure inside TOMCAT$ROOT:[000000.webapps], make sure that you are not deleting any files by mistake before executing this command. All files will be deleted instantaneously, so use the command at your own risk.

<pre>
$ delete /tree TOMCAT$ROOT:[000000.webapps.AXIS2...]*.*;* /log
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]error.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]HappyAxis.jsp;1 deleted
(24KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]index.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listFaultyService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listGroupService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listServices.jsp;1
deleted (8KB)
...

$ delete TOMCAT$ROOT:[000000.webapps]AXIS2.DIR;1 /conf
DELETE TOMCAT$ROOT:[000000.webapps]axis2.DIR;1 ? [N]: Y
</pre>

* In addition to deleting the Axis2 files, you should also go through the configuration changes made earlier in this document and revert the relevant changes.
* If you want to completely remove any traces of Axis2 you should know that the AXIS2$ROOT logical is still defined, although it now points to a non-existent directory. You can remove the logical using the $ DEASSIGN command.

<pre>
$ show logical *axis2*

(LNM$PROCESS_TABLE)

(LNM$JOB_892FB880)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
$ deassign /sys axis2$root
</pre>

* If you have a look inside SYS$STARTUP, you can see that there are also some Axis2 remnants remaining in there. You can either remove these files individually or with a wildcard qualifier (as shown below) together with the /CONFIRM qualifier. It is always advisable to use extra caution when deleting files, especially in system directories, since deleted files are not recoverable unless backed up.

<pre>
$ dir sys$startup:*axis2*

Directory SYS$SYSROOT:[SYSMGR]

axis2$define_logicals.LOG;2 axis2$define_logicals.LOG;1
axis2-tmp-8889454529806580694^.tmp.DIR;1

Total of 3 files.

Directory SYS$COMMON:[SYSMGR]

axis2$define_logicals.com;1

Total of 1 file.

Grand total of 2 directories, 3 files.
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;2 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;1 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1 ? [N]: Y
%DELETE-W-FILNOTDEL, error deleting SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1
-RMS-E-MKD, ACP could not mark file for deletion
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty
DELETE SYS$COMMON:[SYSMGR]axis2$define_logicals.com;1 ? [N]: Y
</pre>

Axis2 - Easy Installation Guide

2021-10-07T15:27:14Z

Axel.elfving: Created page with "This is an easy installation guide that will take you through how to install and configure Apache Axis2 for use with the Tomcat web server on OpenVMS. Before starting the inst..."

This is an easy installation guide that will take you through how to install and configure Apache Axis2 for use with the Tomcat web server on OpenVMS. Before starting the installation, it is a good idea to read through the “Tomcat (CSWS JAVA) - Easy Installation Guide” and make sure that you have you installed and configured Tomcat correctly.

The document also contains instructions for how to set up an AJP Connector between CSWS Apache Web Server and Apache Axis2 on Tomcat. If that is something you wish to do, you need to already have Apache installed and fully configured on your system. For instructions on how to install and configure Apache, consult either the Apache release notes or the “Apache (CSWS) - Easy Installation Guide”.

For more guides like this, check out the main page (coming).

=Introduction=

Go through the following steps to install Axis2.

* Unpack the kit with the $ RUN command

<pre>
$ run VSI-I64VMS-AXIS2-V0107-3-1.ZIPEXE
</pre>

:Then, install Axis2 with the command

<pre>
$ product install axis2
Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.AXIS2]
vsi-i64vms-axis2-v0107-3-1.pcsi$compressed;1 succeeded

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 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 AXIS2 V1.7-3

VMS Software Inc. and The Apache Software Foundation.

Minimum JDK software version not found on system, abort installation

This kit requires the minimum Java version of 1.8.

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 AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
%PCSIUI-I-COMPWERR, operation completed after explicit continuation
from errors
</pre>

:Comment for the highlighted part of the installation output: If you have OpenJDK8 installed on a system that previously did not have JAVA installed on it, 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 and Axis2.

=Configuration=

These instructions will guide you through how to define the necessary Axis2 logicals on start-up before showing you how to set up the AJP Connector.

==Automatic Start-up Commands==

Follow these instructions if you want Axis2 logicals to be defined automatically when rebooting the system.

* Edit the file SYS$MANAGER:SYLOGICALS.COM add the lines specified below (in the section where you are asked to define site-specific logicals) to define the Axis2 logicals on start-up. Make sure to specify the correct node for your system (highlighted in yellow).

<pre>
$ edit sys$manager:sylogicals.com

...

$! ******************************************************************
$! Define any site-specific logical names below:
$! ******************************************************************

...

$ IF NODE .EQS. "YOUR_NODE_NAME"
$ THEN
$ file := SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ if f$search("''file'") .nes. "" then @'file'
$ ENDIF

...
</pre>

==Defining Axis2 Logicals==

Now is a good time to manually define the Axis2 logicals.

* Run the same file you included in the start-up procedure in the previous section. Most notably, this will define the logical AXIS2$ROOT – giving us easy access to the Axis2 root directory.

<pre>
$ @SYS$COMMON:[SYSMGR]AXIS2$DEFINE_LOGICALS.COM
$ show logical *axis*

(LNM$PROCESS_TABLE)

(LNM$JOB_89235900)

"AXIS$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Deploying Axis2 WAR File in Tomcat==

To enable Axis2 and integrate it with Tomcat, we need to deploy the Axis2 WAR file in the directory TOMCAT$ROOT:[WEBAPPS].

* Copy the file AXIS2$ROOT:[OPENVMS]axis2.war to TOMCAT$ROOT:[WEBAPPS] and make sure the file has TOMCAT$WWW as owner and the appropriate protections.

<pre>
$ copy /log axis2$root:[openvms]axis2.war tomcat$root:[webapps]
%COPY-S-COPIED, AXIS2$ROOT:[OpenVMS]axis2.war;1 copied to TOMCAT$ROOT:[webapps]axis2.war;1 (19.27MB)

$ dir /sec tomcat$root:[webapps]axis2.*

Directory TOMCAT$ROOT:[webapps]

axis2.DIR;1 [TOMCAT$WWW] (RWED,RWED,RE,)
axis2.war;1 [TOMCAT$WWW] (RWED,RWED,RE,RE)

Total of 1 file.

$ set file /prot=(S:RWE,O:RWED,G,W) tomcat$root:[webapps]axis2.* /log
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps]axis2.war;1 file protection changed to
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, TOMCAT$ROOT:[webapps.axis2]axis2-web.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
...
</pre>

:If automatic deployment is configured correctly for Tomcat, the WAR file should be unpacked automatically during runtime, resulting in the creation of TOMCAT$ROOT:[WEBAPPS]axis2.DIR.

* If you are in a production environment, or for some other reason do not wish to use automatic deployment, you may wish to deploy your WAR files using the Tomcat interface – this will allow you to deploy WAR files from a separate directory and thus run a lower risk of unexpectedly overwriting files in use.

:You may also wish to disable automatic deployment, so that WAR files placed in your TOMCAT$ROOT:[WEBAPPS] directory do not automatically deploy and overwrite your existing configuration files. To do this, edit TOMCAT$ROOT:[CONF]server.xml and set autoDeploy to “false”, as shown below. Then restart Tomcat to implement the changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...

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

...
</pre>

:Lastly, to manually deploy AXIS2$ROOT:[OPENVMS]axis2.war directly from its directory, visit your Tomcat server and enter the Manager App. Under “Deploy directory or WAR file located on server”, enter the information shown below.

<pre>
Context Path (required): /axis2
XML Configuration file path:
WAR or Directory path: axis2$root:[openvms]axis2.war
</pre>

:Note: Although you set autoDeploy to “false”, Tomcat will still deploy WAR files on start-up. Therefore, to avoid unexpected deployment, it is advisable to keep WAR files you do not wish to deploy outside your TOMCAT$ROOT:[WEBAPPS] directory.

==Enabling HTTPS for Axis2==

* Change the Axis2 Administrator account username and password, edit the file TOMCAT$ROOT:[000000.webapps.axis2.WEB-INF.conf]axis2.xml and make sure that you change these two lines (located close to the top of the file) and set a secure password.

<pre>
$ edit tomcat$root:[000000.webapps.axis2.web-inf.conf]axis2.xml

...

<parameter name="userName">admin</parameter>
<parameter name="password">axis2</parameter>

...
</pre>

:In the same file, if you wish to use HTTPS with Axis2, scroll down until you find the section that reads

<pre>
...






</pre>

:Edit the lines directly underneath, adding the transportReceiver for HTTPS (highlighted in yellow), so that the two transportReceiver directives read

<pre>
<transportReceiver name="http"
class="org.apache.axis2.transport.http.AxisServletListener"/>
<transportReceiver name="https"
class="org.apache.axis2.transport.http.AxisServletListener"/>

...
</pre>

* Make sure to restart Tomcat so that the configuration changes are implemented.

<pre>
$ @sys$startup:tomcat$shutdown.com
$ submit/user=tomcat$www/queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
$ show system
...
0000046F APACHE$TOMCAT HIB 4 70149 0 00:00:53.85 56117 47489 M
...
</pre>

* Lastly, connect to Axis2 using the HTTPS to test the connection with the URL shown below. If the connections fails, you may want to review this guide as well as the “Tomcat (CSWS JAVA) – Easy Installation Guide” or review the log files in TOMCAT$ROOT:[000000.logs].

<pre>
https://your.server.com:8443/axis2/
</pre>

==Setting up the AJP Connector==

This section will show you how to set up the AJP Connector, which will allow you to integrate Tomcat into an existing Apache Web Server installation so that you can access Axis2 through Apache. Thus, it is necessary for Apache to be installed and working correctly. For instruction on how to install Apache, see the “Apache (CSWS) - Easy Installation Guide”.

* Edit the file TOMCAT$ROOT:[CONF]server.xml and confirm that the following directive is uncommented and that redirectPort points to the HTTPS port you have specified for Tomcat. If any of the information is incorrect, make the necessary changes.

<pre>
$ edit tomcat$root:[conf]server.xml

...


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

...
</pre>

* Next edit Apache’s main configuration file APACHE$ROOT:[000000.CONF]HTTPD.CONF and scroll down until you reach the list of loadable modules. Uncomment the following modules by removing the number signs (#) in front of the LoadModule directives.

<pre>
$ edit apache$root:[000000.conf]httpd.conf

...

LoadModule proxy_module modules/mod_proxy.exe
LoadModule proxy_ajp_module modules/mod_proxy_ajp.exe

...
</pre>

:Next, add the <Location> directive shown below at the very bottom of the same file. The DNS name highlighted in yellow should match that of your server. It is possible to use your IP address instead, though that might by-pass the certificate you have in place for your server and unable you from establishing an HTTPS connection to Axis2.

<pre>
...

<Location "/axis2">
ProxyPass "ajp://example.eng.vmssoftware.com:8009/axis2"
</Location>

...
</pre>

:Lastly, for Apache to implement these changes, it needs to be restarted. You can do this with

<pre>
$ @sys$startup:apache$shutdown
$ @sys$startup:apache$startup
</pre>

* To see if the AJP connector has been set up correctly, connect to Axis2 on either port 80 (HTTP) or port 443 (HTTPS). The 8009 port specified for the AJP Connector is used internally.

<pre>
http://example.eng.vmssoftware.com:80/axis2/
https://example.eng.vmssoftware.com:443/axis2/
</pre>

=Removal=

To remove Axis2, follow these instructions. If you also want to remove Tomcat, make sure you remove Axis2 first.

* First, shut down Tomcat.

<pre>
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
</pre>

* Then, uninstall Axis2 using the command below.

<pre>
$ product remove axis2

The following product has been selected:
VSI I64VMS AXIS2 V1.7-3 Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS AXIS2 V1.7-3 DISK$SYS1:[VMS$COMMON.]

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

The following product has been removed:
VSI I64VMS AXIS2 V1.7-3 Layered Product
</pre>

* If you do not wish to remove Tomcat, but want to do a complete removal of Axis2, you can selectively remove the files belonging to Axis2 to inside TOMCAT$ROOT:[000000.webapps].

<pre>
$ delete tomcat$root:[webapps]axis2.war;1 /conf
DELETE TOMCAT$ROOT:[webapps]axis2.war;1 ? [N]: Y
</pre>

:If using the $ DELETE /TREE command when deleting the Axis2.DIR directory structure inside TOMCAT$ROOT:[000000.webapps], make sure that you are not deleting any files by mistake before executing this command. All files will be deleted instantaneously, so use the command at your own risk.

<pre>
$ delete /tree TOMCAT$ROOT:[000000.webapps.AXIS2...]*.*;* /log
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]error.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]HappyAxis.jsp;1 deleted
(24KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]index.jsp;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listFaultyService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listGroupService.jsp;1
deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000.webapps.axis2.axis2-web]listServices.jsp;1
deleted (8KB)
...

$ delete TOMCAT$ROOT:[000000.webapps]AXIS2.DIR;1 /conf
DELETE TOMCAT$ROOT:[000000.webapps]axis2.DIR;1 ? [N]: Y
</pre>

* In addition to deleting the Axis2 files, you should also go through the configuration changes made earlier in this document and revert the relevant changes.
* If you want to completely remove any traces of Axis2 you should know that the AXIS2$ROOT logical is still defined, although it now points to a non-existent directory. You can remove the logical using the $ DEASSIGN command.

<pre>
$ show logical *axis2*

(LNM$PROCESS_TABLE)

(LNM$JOB_892FB880)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"AXIS2$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.axis2.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
$ deassign /sys axis2$root
</pre>

* If you have a look inside SYS$STARTUP, you can see that there are also some Axis2 remnants remaining in there. You can either remove these files individually or with a wildcard qualifier (as shown below) together with the /CONFIRM qualifier. It is always advisable to use extra caution when deleting files, especially in system directories, since deleted files are not recoverable unless backed up.

<pre>
$ dir sys$startup:*axis2*

Directory SYS$SYSROOT:[SYSMGR]

axis2$define_logicals.LOG;2 axis2$define_logicals.LOG;1
axis2-tmp-8889454529806580694^.tmp.DIR;1

Total of 3 files.

Directory SYS$COMMON:[SYSMGR]

axis2$define_logicals.com;1

Total of 1 file.

Grand total of 2 directories, 3 files.
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;2 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2$define_logicals.LOG;1 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1 ? [N]: Y
%DELETE-W-FILNOTDEL, error deleting SYS$SYSROOT:[SYSMGR]axis2-tmp-8889454529806580694^.tmp.DIR;1
-RMS-E-MKD, ACP could not mark file for deletion
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty
DELETE SYS$COMMON:[SYSMGR]axis2$define_logicals.com;1 ? [N]: Y
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:46:30Z

Axel.elfving: /* Removal */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

:Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

: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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

: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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

:Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier.

To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

:Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:45:45Z

Axel.elfving: /* A PHP Example */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

:Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

: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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

: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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

:Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:44:23Z

Axel.elfving: /* Optional – Convert Key and Certificate to DER Encoding */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

:Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

: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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

: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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:43:17Z

Axel.elfving: /* Configuring HTTPS */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

:Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:42:37Z

Axel.elfving: /* Creating a Self-Signed Certificate */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

:Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:41:36Z

Axel.elfving: /* Connecting to your Web Server */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

:If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

:Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:40:56Z

Axel.elfving: /* Starting Apache */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

:If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:40:17Z

Axel.elfving: /* Changes to the Main Configuration File */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

:Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

:Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:39:09Z

Axel.elfving: /* Ensuring SYS$SCRATCH Points To ODS-5 Device */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

:In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:38:37Z

Axel.elfving: /* Configuration */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Automatic Start-up and Shutdown Commands==

In this section we will set up commands for Apache 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.

<pre>
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

* Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.

<pre>
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:35:36Z

Axel.elfving: /* Running APACHE$CONFIG */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).

:Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:34:13Z

Axel.elfving: /* Installation */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).
Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T14:33:37Z

Axel.elfving: /* Introduction */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.

<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.

<pre>
$ show devices $1$YOURDISK: /full
</pre>

:Towards the bottom of the output, you will see the volume status.

<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command

<pre>
$ product remove csws
</pre>

:To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).
Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Tomcat (CSWS JAVA) - Easy Installation Guide

2021-10-07T14:31:21Z

Axel.elfving: 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..."

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).

=Introduction=

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.

:<nowiki>***</nowiki>Please note: HPE Java™ JDK V1.8u_144* is not recommended.***

:<nowiki>***</nowiki>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:

<pre>
$ show devices $1$YOURDISK: /full
</pre>

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

<pre>
Volumes Status: ODS-5, ...
</pre>

* 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.

::TOMCAT$ROOT:[CONF]tomcat-users.xml
::TOMCAT$ROOT:[CONF]context.xml
::TOMCAT$ROOT:[CONF]web.xml
::TOMCAT$ROOT:[CONF]server.xml

* Shut down the Tomcat webserver with the command

<pre>
$ @sys$startup:tomcat$shutdown.com
</pre>

* Remove Tomcat with the command

<pre>
$ product remove csws_java
</pre>

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

=Installation=

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

<pre>
$ run VSI-I64VMS-CSWS_JAVA-V0805-50A-1.ZIPEXE
</pre>

* Install Tomcat using the PCSI application.

<pre>
$ 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

VSI I64VMS CSWS_JAVA V8.5-50A

Post-installation tasks are required.

To start the Tomcat web server at system boot time, add the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:TOMCAT$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

To shutdown Tomcat at system shutdown time, add the following lines to
SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:TOMCAT$SHUTDOWN.COM
$ 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
</pre>

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.

=Configuration=

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:

<pre>
$!***SYS$SYSROOT:[SYSMGR]JAVA$80_SETUP.COM***
$!
$ @sys$sysdevice:[sys0.syscommon.openjdk$80.com]java$setup.com 'P1'
$ exit
</pre>

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.

<pre>
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
</pre>

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.

<pre>
$ set default sys$system
$ mcr sysgen
SYSGEN> USE CURRENT
SYSGEN> SHOW CHANNELCNT
Parameter Name Current Default Min. Max. Unit Dynamic
-------------- ------- ------- ------- ------- ---- -------
CHANNELCNT 32767 512 64 65535 Channels
SYSGEN> SHOW WSMAX
Parameter Name Current Default Min. Max. Unit Dynamic
-------------- ------- ------- ------- ------- ---- -------
WSMAX 900000 131072 16384 134217728 Pagelets
internal value 56250 8192 1024 8388608 Pages
</pre>

* 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.

<pre>
SYSGEN> USE CURRENT
SYSGEN> SET CHANNELCNT 32767
SYSGEN> SET WSMAX 900000
SYSGEN> WRITE ACTIVE
SYSGEN> WRITE CURRENT
</pre>

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:

<pre>
$ set default sys$system
$ mcr authorize
</pre>

* 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).

<pre>
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
</pre>

* The TOMCAT$WWW username should now look something like this:

<pre>
UAF> show tomcat$www

Username: TOMCAT$WWW Owner:
Account: TOMCAT UIC: [555,555] ([TOMCAT$WWW])
CLI: DCL Tables: DCLTABLES
Default: TOMCAT$ROOT:[000000]
LGICMD: LOGIN
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:
NETMBX TMPMBX
Default Privileges:
BYPASS IMPERSONATE NETMBX SYSPRV TMPMBX
</pre>

* If an account for Apache does not exist, you can create the account from scratch like so:

<pre>
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
</pre>

==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.

<pre>
$ @sys$manager:tomcat$define_logicals.com
</pre>

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*

<pre>
(LNM$PROCESS_TABLE)

(LNM$JOB_89326240)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"TOMCAT$ROOT" = "DISK$SYS1:[SYS0.SYSCOMMON.tomcat.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==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.

<pre>
$!
$ IF NODE .EQS. "YOUR_NODE_NAME"
$ THEN
$ if f$search("SYS$STARTUP:TOMCAT$STARTUP.COM") .nes. ""
$ then
$ submit/USER=TOMCAT$WWW/QUEUE=SYS$BATCH/PARAMETERS=(TOMCAT$WWW)
SYS$STARTUP:TOMCAT$STARTUP.COM
$ endif
$ ENDIF
$!
</pre>

: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:

<pre>
$ set terminal /width=132
</pre>

* Edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the following lines:

<pre>
$!
$ file := SYS$STARTUP:TOMCAT$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
$!
</pre>

==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).

<pre>
$ show logical tomcat$root
"TOMCAT$ROOT" = "YOURDISK:[SYS0.SYSCOMMON.tomcat.]" (LNM$SYSTEM_TABLE)

$ set default YOURDISK:[SYS0.SYSCOMMON]
$ set file /owner=[555,555] tomcat.DIR /log
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 modified

$ set file /owner=[555,555] [.tomcat...]*.*;* /log
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON.tomcat]bin.DIR;1 modified
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON.tomcat]BUILDING.txt;1 modified
%SET-I-MODIFIED, YOURDISK:[SYS0.SYSCOMMON.tomcat]conf.DIR;1 modified
...
</pre>

* Second, set the file permissions. First for the root directory and then for the rest of the directory structure.

<pre>
$ 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
S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON.tomcat]BUILDING.txt;1 file protection
changed to S:RWE,O:RWED,G:,W:
%SET-I-PROTECTED, YOURDISK:[SYS0.SYSCOMMON.tomcat]conf.DIR;1 file protection changed to
S:RWE,O:RWED,G:,W:
...
</pre>

* To verify that the owner and file protections were set correctly, you can issue the command
$ dir [.tomcat] /owner /prot

<pre>
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,,)
</pre>

==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:

<pre>
$!********************************************
$ ! Login.Com for Tomcat Web Server
$ !
$ ! exit
$ !
$ set process/parse =extend ! ODS-5 Support
$ set process/units = bytes ! ODS-5 Support (optional)
$ DEFINE JAVA$DONT_PRESET_LOGICALS "TRUE" ! TURN LOGICAL DEFS OFF IN LIB$INITIALIZE
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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
$ EXIT
</pre>

==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:

<pre>
$!***** SYS$STARTUP:TOMCAT$DEFS_LOCAL.COM*****
$! 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]
</pre>

* 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.

<pre>
$ submit /user=tomcat$www /queue=sys$batch/parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
</pre>

: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.

<pre>
$ 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:
NETMBX TMPMBX

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
</pre>

* If you want to shut down Tomcat, you can do so with the following command from a privileged account.

<pre>
$ @sys$startup:tomcat$shutdown.com
</pre>

==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.

<pre>
$ edit tomcat$root:[conf]tomcat-users.xml

...

<nowiki></nowiki>
<nowiki></nowiki>
<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"/>
</tomcat-users>
[End of file]
</pre>

* To allow access to Admin and Manager, permissions must be set to allow for connections. Edit these two files:

::TOMCAT$ROOT:[webapps.host-manager.META-INF]context.xml
::TOMCAT$ROOT:[webapps.manager.META-INF]context.xml

:Then add the comment delimiters highlighted in the lines below to both context.xml files, so that the relevant lines read

<pre>
...

<Context antiResourceLocking="false" privileged="true" >
<nowiki></nowiki>
<Manager sessionAttributeValueClassNameFilter=
"java\.lang\.(?:Boolean|Integer|Long|Number|String)|org\.apache\.c`
</Context>

...
</pre>

* Finally, restart Tomcat with the commands below.

<pre>
$ @sys$startup:tomcat$shutdown.com
$ submit /user=tomcat$www /queue=sys$batch /parameters=(tomcat$www) -
_$ sys$startup:tomcat$startup.com
</pre>

==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.

<pre>
$ edit tomcat$root:[conf]web.xml

...

<nowiki></nowiki>
<servlet>
<servlet-name>cgi</servlet-name>
<servlet-class>org.apache.catalina.servlets.CGIServlet
</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>executable</param-name>
<param-value></param-value>
</init-param>
<init-param>
<param-name>cgiPathPrefix</param-name>
<param-value>WEB-INF/cgi</param-value>
</init-param>
<load-on-startup>5</load-on-startup>
</servlet>

...
</pre>

: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.

<pre>
...



<nowiki></nowiki>
<servlet-mapping>
<servlet-name>cgi</servlet-name>
<url-pattern>/cgi-bin/*</url-pattern>
</servlet-mapping>

...
</pre>

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

<pre>
$ edit tomcat$root:[conf]context.xml

...

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

...
</pre>

===CGI Example===

* Create the directory structure TOMCAT$ROOT:[WEBAPPS.CGI.WEB-INF.CGI]. While in TOMCAT$ROOT, run the following command.

<pre>
$ create /dir [.webapps.cgi.web-inf.cgi] /log
%CREATE-I-CREATED, TOMCAT$ROOT:[000000.webapps.cgi.web-inf.cgi] created
</pre>

* 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].

<pre>
$ dir apache$root:[cgi-bin]

Directory APACHE$COMMON:[CGI-BIN]

TEST-CGI-VMS.COM;1 TEST-CGI-VMS.EXE;1

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
%COPY-S-COPIED, APACHE$COMMON:[CGI-BIN]TEST-CGI-VMS.EXE;1 copied to TOMCAT$ROOT:
[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
%COPY-S-COPIED, APACHE$COMMON:[CGI-BIN]TEST-CGI-VMS.COM;1 copied to TOMCAT$ROOT:
[webapps.cgi.web-inf.cgi]test-cgi-vms.cgi;1 (4KB)
</pre>

:Set the correct file ownership and protection and make sure to use the correct UIC for the TOMCAT$WWW user account.

<pre>
$ 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
E,O:RWED,G:,W:
...
</pre>

:And as a last step, make sure that ownership and permissions are correct.

<pre>
$ 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.
</pre>

* Create the file TOMCAT$ROOT:[WEBAPPS.CGI]index.html.

<pre>
$ create tomcat$root:[webapps.cgi]index.html
(Press Ctrl-Z)
</pre>

* 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.

<pre>
$ edit tomcat$root:[000000]STREAM_LF.FDL
FILE
ALLOCATION 4
BEST_TRY_CONTIGUOUS yes
EXTENSION 0
ORGANIZATION sequential
RECORD
BLOCK_SPAN yes
CARRIAGE_CONTROL carriage_return
FORMAT stream_LF
SIZE 0
[End of file]
</pre>

:Using this file, the conversion can now be performed with

<pre>
$ convert /fdl=tomcat$root:[000000]stream_lf.fdl -
_$ tomcat$root:[webapps.cgi]index.html tomcat$root:[webapps.cgi]
</pre>

:This will create a new version of the file for which you can verify that the record format is correct with the command below.

<pre>
$ dir /full tomcat$root:[webapps.cgi]index.html;2
...
Record format: Stream_LF, maximum 0 bytes, longest 0 bytes
...
</pre>

* Make sure that the ownership and permissions of the index.html file are as follows.

<pre>
$ 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.
</pre>

* 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.

<pre>
<nowiki>$ edit index.html
<HTML>
<HEAD>
<TITLE>CGI Application Example</TITLE>
<link href="hpweb_styles_win_ie6.css" rel="stylesheet"
type="text/css">
<style type="text/css">

</style>
</HEAD>
<BODY>
<h2> <class="colorE7E7E7bg color003366"> CGI Application Example</h2>
<h3> <class="colorE7E7E7bg color003366"> CGI from the TOMCAT Server</h3>
<a href="https://</nowiki>10.10.100.0:8443<nowiki>/cgi/cgi-bin/test-cgi-vms.exe">CGI-EXE from the TOMCAT Server. </a> 
<a href="https://</nowiki>10.10.100.0:8443<nowiki>/cgi/cgi-bin/test-cgi-vms.cgi">CGI-COM from the TOMCAT Server. </a> 
<hr>
</hr>
<h3> <class="colorE7E7E7bg color000066">CGI from the APACHE Web Server </h3>
<a href="https://</nowiki>10.10.100.0:443<nowiki>/cgi-bin/test-cgi-vms.exe">CGI-EXE from the APACHE Web Server.</a>
<a href="https://</nowiki>10.10.100.0:443<nowiki>/cgi-bin/test-cgi-vms.com">CGI-COM from the APACHE Web Server. </a>

Or you can Use the non-SSL URL of: http://</nowiki>10.10.100.0:8080<nowiki>/cgi/cgi-bin/test-cgi-vms.exe and the non-SSL URL of: http://</nowiki>10.10.100.0:80<nowiki>/cgi-bin/test-cgi-vms

Thank you! /VSI Support Team 

</BODY>
</HTML>
[End of file]</nowiki>
</pre>

: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.

<pre>
$ 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"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<display-name> A VSI CGI Example... </display-name>
<description>
Used as an example for showing how CGI apps can work with Tomcat V8.5-50
</description>
<session-config>
<session-timeout>
30
</session-timeout>
</session-config>
<welcome-file-list>
<welcome-file>
index.html
</welcome-file>
</welcome-file-list>
</web-app>
[End of file]
</pre>

* 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.

<pre>
$ edit tomcat$root:[conf]server.xml

...

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

...
</pre>

==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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

Follow these instructions to create a self-signed certificate.

* Create the subdirectories TOMCAT$ROOT:[SSLCERTS] and TOMCAT$ROOT:[SSLKEYS]

<pre>
$ 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
</pre>

:Double-check owner and permissions so they match the following:

<pre>
$ dir /sec ssl*.*
sslcerts.DIR;1 [TOMCAT$WWW] (RWE,RWED,,)
sslkeys.DIR;1 [TOMCAT$WWW] (RWE,RWED,,)
</pre>

* Start up SSL111 (OpenSSL) and enable the environment with

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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:

<pre>
$ 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
</pre>

* 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.

<pre>
$ 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.
</pre>

===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.

<pre>
$ 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
</pre>

:View the DER encoded certificates and keys with the commands

<pre>
$ 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
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

: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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ 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
</pre>

:To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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.

<pre>
$ 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
</pre>

: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

<pre>
$ 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
</pre>

: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.

<pre>
$ edit tomcat$root:[conf]server.xml

...

<nowiki></nowiki>

...

<nowiki></nowiki>
<Connector port="8443"
connectionTimeout="20000"
enableLookups="false"
maxKeepAliveRequests="1000"
maxThreads="200"
scheme="https"
secure="true"
SSLEnabled="true"
SSLCertificateFile="/tomcat$root/000000/sslcerts/server.crt"
SSLCertificateKeyFile="/tomcat$root/000000/sslkeys/server.key"
SSLVerifyClient="none"
SSLProtocol="TLSv1.1+TLSv1.2+TLSv1.3"/>

...
</pre>

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

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:8443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

=Removal=

To completely remove Tomcat, do the following:

* Shut down Tomcat with the command

<pre>
$ @sys$startup:tomcat$shutdown
%DCL-I-SUPERSEDE, previous value of JAVA$CLASSPATH has been superseded
</pre>

* 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.

<pre>
$ 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:
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS_JAVA V8.5-50A Layered Product
</pre>

* 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.

<pre>
$ show logical *tomcat*

(LNM$PROCESS_TABLE)

(LNM$JOB_892B9EC0)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"TOMCAT$ROOT" = "YOURDISK:[SYS0.SYSCOMMON.tomcat.]"
"TOMCAT$USER" = "tomcat$www"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

: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.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.tomcat...]*.*;* /log
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000]LOGIN.COM;2 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000]LOGIN.COM;1 deleted (8KB)
%DELETE-I-FILDEL, TOMCAT$ROOT:[000000]STREAM_LF.FDL;1 deleted (8KB)
...
</pre>

:Next, you can delete the directory YOURDISK:[SYS0.SYSCOMMON.tomcat] with the command

<pre>
$ delete YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 /conf
DELETE YOURDISK:[SYS0.SYSCOMMON]tomcat.DIR;1 ? [N]: y
</pre>

:There are also Tomcat files located in SYS$MANAGER. Use this command to find them

<pre>
$ dir sys$manager:*tomcat*

Directory SYS$SYSROOT:[SYSMGR]

TOMCAT$ARGS.DAT;2 TOMCAT$ARGS.DAT;1 TOMCAT$ARGS_LOCAL.DAT;2
TOMCAT$ARGS_LOCAL.DAT;1 tomcat$startup.LOG;1
tomcat-users_xml.TPU$JOURNAL;1

Total of 6 files.

Directory SYS$COMMON:[SYSMGR]

tomcat$define_logicals.com;1

Total of 1 file.

Grand total of 2 directories, 7 files.
</pre>

: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.

<pre>
$ delete sys$manager:*tomcat*.*;* /conf
DELETE SYS$SYSROOT:[SYSMGR]TOMCAT$ARGS.DAT;2 ? [N]: Y
DELETE SYS$SYSROOT:[SYSMGR]TOMCAT$ARGS.DAT;2 ? [N]: Y
...
</pre>

:Lastly, there is also the file SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT.

<pre>
$ del SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT;1 /conf
DELETE SYS$SYSDEVICE:[SYS0]TOMCAT$ARGS_LOCAL.DAT;1 ? [N]: y
</pre>

* 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.

<pre>
$ 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
</pre>

:To delete the logicals, use the $ DEASSIGN command.

<pre>
$ deassign /sys tomcat$user
$ deassign /sys tomcat$root
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T12:02:25Z

Axel.elfving: /* Removing Apache */

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.
<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.
<pre>
$ show devices $1$YOURDISK: /full
</pre>

Towards the bottom of the output, you will see the volume status.
<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command
<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command
<pre>
$ product remove csws
</pre>
To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).
Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removal=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>

Apache (CSWS) - Easy Installation Guide

2021-10-07T12:00:58Z

Axel.elfving: Created page with "This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist t..."

This is an easy installation guide for setting up an Apache web server (CSWS) on OpenVMS. As such, it will not go into explicit detail but should rather serve as a checklist to make sure nothing important was missed during the base install. For more guides like this, check out the main page (coming).

=Introduction=

Before installing Apache make sure the following prerequisites are met.

* OpenVMS Integrity servers Version 8.4-1H1 or higher.
* OpenSSL (SSL111) is needed to configure HTTPS for your Apache web server. SSL111 is not to be confused with SSL and SSL1, both of which come with OpenVMS. You can check if SSL111 is installed on your system with the command below.
<pre>
$ prod show prod ssl111
------------------------------------ ----------- ---------
PRODUCT KIT TYPE STATE
------------------------------------ ----------- ---------
VSI I64VMS SSL111 V1.1-1K Full LP Installed
------------------------------------ ----------- ---------

1 item found
</pre>

* It is required that you install CSWS on an ODS-5 enabled disk. The easiest way to check if the disk you are intending to install Apache on is ODS-5 enabled is to use the following command on a mounted disk.
<pre>
$ show devices $1$YOURDISK: /full
</pre>

Towards the bottom of the output, you will see the volume status.
<pre>
Volumes Status: ODS-5, ...
</pre>

* Optionally, if you intend to use PHP in conjunction with Apache, you should make sure your PHP distribution is up to date. This installation guide will briefly show you how to create a working example of a PHP web page. Using VSI CSWS Version 2.4-48A-1 together with HPE CSWS_PHP V5.2-17A or earlier causes a process crash.

Before you install Apache, if you are currently running an earlier version of the software on your system, it is strongly recommended that you

* Backup your important files. You may also wish to rename your configuration files so that the installation process can create new ones. Then use the old configuration files to transfer any modifications that would be required by your site. Do not use your old configuration files for your new installation. When transferring directives from a previous version, review the Apache documentation to ensure that the syntax is used correctly for the new version.

* Shut down the Apache web server with the command
<pre>
$ @sys$startup:apache$shutdown.com
</pre>

* Remove Apache with the command
<pre>
$ product remove csws
</pre>
To do a complete removal of Apache, follow the instructions in the last section of this document.

=Installation=

Before you install Apache, download the installation kit for CSWS (Apache) to your server and read through the release notes. Then follow these steps:

* Unpack the kit inside your chosen source directory with
<pre>
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
</pre>

* Install Apache using the PCSI application.
<pre>
$ product install csws

Performing product kit validation of signed kits ...
%PCSI-I-VSIVALPASSED, validation of $1$DGA100:[000000.APACHEKIT]VSI-I64VMS-CSWS-V0204-
38D-1.PCSI$COMPRESSED;1 succeeded

The following product has been selected:
VSI I64VMS CSWS V2.4-38D 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 V2.4-38D

VMS Software Inc. & The Apache Software Foundation.

* This product does not have any configuration options.

Execution phase starting ...

The following product will be installed to destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

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

The following product has been installed:
VSI I64VMS CSWS V2.4-38D Layered Product

VSI I64VMS CSWS V2.4-38D

Release notes are available in SYS$HELP:CSWS_2_4_38.release_notes.

VMS Software Inc. highly recommends that you read these release notes.

Post-installation tasks are required.

The OpenVMS Installation and Configuration Guide gives detailed directions.
This information is a brief checklist.

Configure OpenVMS aspects of the web server by:

$ @SYS$MANAGER:APACHE$CONFIG

If the OpenVMS username APACHE$WWW does not exist, you will be
prompted to create that username. File ownerships are set to UIC
[APACHE$WWW], etc.

After configuration, start the web server manually by entering:

$ @SYS$STARTUP:APACHE$STARTUP

Check that neither SYLOGIN.COM nor the LOGIN.COM write any output to
SYS$OUTPUT:. Look especially for a

$ SET TERMINAL/INQUIRE.

Start the web server at system boot time by adding the following
lines to SYS$MANAGER:SYSTARTUP_VMS.COM:

$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'

Shutdown the Apache server at system shutdown time by adding the
following lines to SYS$MANAGER:SYSHUTDWN.COM:

$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'

Test the installation using your favorite Web browser.
Replace host.domain in the following URL (Uniform Resource Locator)
with the information for the web server just installed, configured,
and started.

URL http://host.domain/ should display the standard introductory page
from the Apache Software Foundation. This has the bold text "It
Worked! The Apache Web Server is Installed on this Web Site!" at the
top and the Apache server logo prominently displayed at the bottom.
If you do not see this page, check the release notes, particularly
the Frequently Asked Questions section.

If you'd like to use secure connections then you'll need to create
a server certificate. We recommend that you start by creating a 30
day self-signed certificate using the following certificate tool:

$ @APACHE$COMMON:[OPENSSL.COM]OPENSSL_AUTO_CERT.COM

Once the certificate has been created you'll need to uncomment the
following directive in the APACHE$COMMON:[CONF]HTTPD.CONF file to
enable SSL.

Include /apache$root/conf/ssl.conf

Thank you for using the Secure Web Server.
</pre>

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

=Configuration=

This part of the easy installation guide will take you through how to complete a basic configuration of Apache. Along the way, some optional tips and tricks will be shared that can prove useful for trouble shooting or testing. As mentioned before, it is assumed that OpenSSL (SSL111) is already installed on your system so that you can set up HTTPS for your web server.

==Running APACHE$CONFIG==

The first thing you need to do after installing Apache is to run SYS$MANAGER:APACHE$CONFIG.COM. This will result in the creation of the APACHE$WWW user account and set it as owner to all of Apache’s files. It will also define logicals needed for Apache to run; one of these is the logical APACHE$ROOT, which gives us easy access to Apache’s root directory.

* Execute the configuration file and answer the questions one by one (highlighted in yellow in the output below). The Apache username is best kept as APACHE$WWW, since you won’t be prompted to create a new Apache user the next time you update Apache (answer with a carriage return) and the password you can choose at random (interactive login is disabled for the account).
Then, choose your own desired UIC number. If you do not know what UIC numbers are available, you can answer the question with a “?”, which will list the users on the system. As you may be aware, it is important not to specify a UIC of 1 or in the range 300-377 since these numbers are reserved by VSI.

<pre>
$ @sys$manager:apache$config

Secure Web Server for OpenVMS
[based on Apache]

This procedure helps you define the operating environment
required to run the Secure Web Server on this system.

[Creating OpenVMS username "APACHE$WWW" ]
[Starting APACHE$COMMON:[000000]APACHE$ADDUSER.COM ]

Press enter to continue...

PLEASE NOTE:

You will be prompted for the following information:

Full name for APACHE$WWW: ! Full name of site server administrator/owner.

Password: ! Password for the APACHE$WWW account

UIC Group Number: ? ! Question mark will display a list of all
! UIC groups currently in use. Quite useful.
! Please pick a group separate from all other
! usernames.
! Servers are usually given the first unused group,
! starting at [377,*] and working down. DO _not_
! go below SYSGEN parameter MAXSYSGROUP.

UIC Member Number: 1 ! Question mark will display a list of all
! UIC members currently in use in that group.
! %UAF-W-BADSPC, no user matches specification
! means the group is empty.

***************************************************************************
* Creating a NEW user account... *
* *
* If at ANY TIME you need help about a prompt, just type "?". *
***************************************************************************

*** Processing APACHE$WWW's account ***

Full name for APACHE$WWW:
Password (password is not echoed to terminal) [APACHE$WWW]:

UIC Group number [200]: ?

Each user has a specific User Identification Code (UIC) which consists of two
numbers, and is usually displayed in the format [group,member]. The first
number is the "group". People with the same group number can access each
other's files through the group protection code.

For instance, if you set protection using the following command:
$ SET PROTECTION=(GROUP:R,WORLD) NEWS.TXT
only people in the same group could read the file "NEWS.TXT".

The following is a list of UIC's that already exist on the system: (You do not
have to specify one of these groups, if you do not want to.)

Owner Username UIC Account Privs Pri Directory

SYSTEM MANAGER SYSTEM [1,4] SYSTEM All 4 SYS$SYSROOT:[SYSMGR]
...
TCPIP$TELNET TCPIP$TELNET [3655,1] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$TELNET]
TCPIP$FTP TCPIP$FTP [3655,2] TCPIP Normal 8 SYS$SYSDEVICE:[TCPIP$FTP]
TCPIP$SSH TCPIP$SSH [3655,3] TCPIP Normal 8 TCPIP$SSH_DEVICE:[TCPIP$SSH]

vUIC Group number [200]:

UIC Member number: 1

%UAF-I-ADDMSG, user record successfully added
%UAF-I-RDBADDMSGU, identifier APACHE$WWW value [000200,000001] added to rights database
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-MDFYMSG, user record(s) updated
%UAF-I-GRANTMSG, identifier APACHE$APR_ALL granted to APACHE$WWW
%UAF-I-DONEMSG, system authorization file modified
%UAF-I-RDBDONEMSG, rights database modified

Check newly created account:

Username: APACHE$WWW Owner:
Account: AP_HTTPD UIC: [200,1] ([APACHE$WWW])
CLI: DCL Tables: DCLTABLES
Default: APACHE$ROOT:[000000]
LGICMD: LOGIN
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: ----- No access ------ ----- No 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: 300 Bytlm: 200000
Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0
Maxdetach: 0 BIOlm: 300 JTquota: 4096
Prclm: 20 DIOlm: 300 WSdef: 15000
Prio: 4 ASTlm: 610 WSquo: 30000
Queprio: 4 TQElm: 610 WSextent: 30000
CPU: (none) Enqlm: 2000 Pgflquo: 250000
Authorized Privileges:
NETMBX TMPMBX
Default Privileges:
NETMBX TMPMBX
Identifier Value Attributes
APACHE$APR_ALL %X80010002
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-RDBNOMODS, no modifications made to rights database

Please verify that this account does not violate any site-specific
security policy. This account will be enabled and it will have no
expiration date.

Is everything satisfactory with the account [YES]:

PLEASE NOTE:

The APACHE$WWW account was created with the minimum SYSUAF quotas to
run the server. On almost all systems, the server should start but
these parameters will need to be increased to improve performance or
to keep up with increased demands.

See Release notes for details.

To operate successfully, the server processes must have read access
to the installed files and read-write access to certain other files
and directories. It is recommended that you use this procedure to
set the owner UIC on the CSWS files and directories to match the server.
You should do this each time the product is installed, but it only has
to be done once for each installation on a cluster.

Set owner UIC on CSWS files? [YES]

Do you want to enable the impersonation features provided by suEXEC?
If so, the server will support running CGIs using specified usernames.

Enable suEXEC? [NO]
Setting ownership on files. This could take a minute or two. . . .

Disabling suEXEC configuration. This could take a minute or two. . . .
Configuration is complete. To start the server:

$ @SYS$STARTUP:APACHE$STARTUP.COM
</pre>

* After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "$1$DGA100:[SYS0.SYSCOMMON.APACHE.SPECIFIC.ELMILE.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

==Ensuring SYS$SCRATCH Points To ODS-5 Device==

As was explained in the introduction of this installation guide, it is important that Apache is installed on an ODS-5 enabled device. This also holds true for the logical SYS$SCRATCH, which defines a location where Apache can store temporary files; some of these may utilize extended filenames and, thus, require the device where the SYS$SCRATCH directory is located to be ODS-5.

* Verify this with the commands shown below.
<pre>
$ show logical sys$scratch
"SYS$SCRATCH" = "SYS$SYSROOT:[SYSMGR]" (LNM$JOB_892B6E00)

$ show logical SYS$SYSROOT
"SYS$SYSROOT" = “YOURDISK:[SYS0.]" (LNM$SYSTEM_TABLE)
= "SYS$COMMON:"
1 "SYS$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.]" (LNM$SYSTEM_TABLE)

$ show device /full YOURDISK

...
</pre>

* An easy way to ensure that SYS$SCRATCH always points to an ODS-5 device is to create a scratch directory inside the Apache file structure.

<pre>
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log
%CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
</pre>

In the next section, we will define the logical SYS$SCRATCH inside the file APACHE$ROOT: [000000]LOGIN.COM to point to this directory. Since the logical will be defined on the process level, the directory will only be used by Apache.

==Utilizing LOGIN.COM==

Inside the root directory for Apache, you will find APACHE$ROOT:[000000]LOGIN.COM which is executed when CSWS is started. Inside this file, you will find a command procedure that cleans up log files inside Apache’s root directory – these are created each time a subprocess is spawned and tend to fill up the directory over time.

* To activate the command procedure, you will need to first comment out the preceding $ EXIT command. Then specify a version limit you find appropriate for each spawned subprocess; the default is 10. To edit the file, use the $ EDIT command.

<pre>
$ edit APACHE$ROOT:[000000]LOGIN.COM
$ ! Login.Com for Apache HTTP (WWW) Server
$ !
$ ! exit
$ !
$ ! Use the following DCL commands to prevent the APACHE$SPECIFIC:[000000]
$ ! directory from filling up with old LOG files by limiting the number of
$ ! versions of each file.
$ !
$ temp1 = f$trnlnm("apache$specific")
$ temp2 = f$length(temp1)
$ temp3 = f$extract(temp2-1,1,temp1)
$ if (f$extract(temp2-2,1,temp1) .eqs. ".")
$ then temp1 = f$extract(0,temp2-2,temp1) + temp3
$ else temp1 = f$extract(0,temp2-1,temp1) + temp3
$ endif
$ set directory /version_limit=10 'temp1'
$ !
$ exit
$ ! End of file
[End of file]
</pre>

* Optionally, you can also add the following lines of code prior to the command procedure. The comments to the side explain the purpose of the commands and defined logicals, which can be commented out if you deem them unnecessary. Then bottom command defines the SYS$SCRATCH logical mentioned in the previous section.

<pre>
$ set process/parse = extend ! ODS-5 Support
$ set process/units = bytes ! Changes Blocks to bytes, MB, GB etc...
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE ! ODS-5 Support
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE ! ODS-5 Support
$ 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 DECC$FILENAME_UNIX_NO_VERSION ENABLE ! Use this carefully.
$! DEFINE APACHE$SPL_DISABLED "TRUE" ! TRUE = ON FALSE = OFF For Troubleshooting startup issues.
$! DEFINE SYS$SCRATCH APACHE$ROOT:[SCRATCH] ! Redefining SYS$SCRATCH
</pre>

==Changes to the Main Configuration File==

Before starting up the web server, it is a good idea to specify the DNS name for the server (or the IP-address) in the main configuration file so that you can connect to it. In addition, since the release of version 2.4-48, it is recommended that you define the Mutex directive during the initial configuration; otherwise, directives that require a Mutex to be defined will cause the web server to fail to start.

* Edit the file APACHE$COMMON:[000000.CONF]HTTPD.CONF and scroll down until you find the section where you can define a Mutex directive. By removing the number sign (#), you can activate one of the prewritten directives. In this installation guide we will use vmsdlm (highlighted below).

<pre>
...

#
# Mutex: Allows you to set the mutex mechanism and mutex file directory
# for individual mutexes, or change the global defaults
#
# Uncomment and change the directory if mutexes are file-based and the default
# mutex file directory is not on a local disk or is not appropriate for some
# other reason.
#
# Mutex default:logs
# Mutex flock:/apache$root/logs
# Mutex sem
Mutex vmsdlm

...
</pre>

* Next, scroll down until you find the directive ServerName. Uncomment it and specify your DNS name (or IP-address if you do not have a DNS name) at port 80.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

ServerName example.eng.vmssoftware.com:80
# Also possible to use IP-address, as shown below
#ServerName 123.123.1.23:80

...
</pre>

*Just above the ServerName directive, you can also change the ServerAdmin directive. Change it to your email address to add yourself as the admin of the server.

<pre>
...

ServerAdmin you@your.address.com

...
</pre>

Press Ctrl-Z to exit the editor and save your changes.

===Optional - Activate Sever-Info and Server-Status===

* Once again, edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and uncomment the two modules shown below (you can find them in the list of modules further down in the document). You will also need to uncomment the directive ExtendedStatus On, which you can find directly beneath the modules.

<pre>
$ edit APACHE$COMMON:[000000.CONF]HTTPD.CONF

...

LoadModule info_module

...

LoadModule status_module

...

#
# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called. The default is Off.
#
ExtendedStatus On

...
</pre>

* In the same configuration file, scroll down until you almost reach the bottom and uncomment the server-status and server-info <Location> directives. Also, make sure that you change the “Allow from” directive to suit your preferred security settings. In this guide, to keep things simple, these directives have been set to “Allow from all”.

<pre>
...

#
# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
# Change the ".example.com" to match your domain to enable.
#
<Location /server-status>
SetHandler server-status
Order deny,allow
Deny from all
Allow from all
</Location>

#
# Allow remote server configuration reports, with the URL of
# http://servername/server-info (requires that mod_info.c be loaded).
# Change the ".example.com" to match your domain to enable.
#
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from all
</Location>

...
</pre>

Note: While these modules are handy when making changes to the web server, they should be disable or password protected at all other times to prevent others from using them.

==Starting Apache==

Having completed the changes to the main configuration file, you can now go ahead and start up the Apache web server.

* Execute the following start-up file to start the server.

<pre>
$ @sys$startup:apache$startup
</pre>

* To see if the process has started, you can use the command

<pre>
$ show system /proc=apache*
OpenVMS V8.4-2L1 on node YOURNODE 28-MAY-2021 06:10:20.81 Uptime 3 22:33:57
Pid Process Name State Pri I/O CPU Page flts Pages
00000486 APACHE$SWS LEF 6 822 0 00:00:00.22 862 913
00000487 APACHE$SWS0000 LEF 5 668 0 00:00:00.27 812 864
00000488 APACHE$SWS0001 LEF 5 666 0 00:00:00.39 812 863
00000489 APACHE$SWS0002 LEF 5 666 0 00:00:00.33 812 863
0000048A APACHE$SWS0003 LEF 5 669 0 00:00:00.36 812 863
0000048B APACHE$SWS0004 LEF 5 666 0 00:00:00.31 812 863
</pre>

If Apache fails to start, have a look at the log files in APACHE$SPECIFIC:[LOGS] and try to figure out why.

* You can shut down Apache by executing the command below.

<pre>
$ @sys$startup:apache$shutdown.com
</pre>

==Connecting to your Web Server==

After starting the web server, you should be able to connect to it using the HTTP protocol (HTTPS is not yet set up). This section offers two ways to test your connection.

* The easiest way to test the connection to your server is by simply using a web browser. This will display the default homepage file APACHE$COMMON:[HTDOCS]index.html - a file that consists of a single message written in HTML code saying “It works!”. If you activated the server-info and server-status modules, you can attempt to connect to them as well.

<pre>
http://example.eng.vmssoftware.com
http://example.eng.vmssoftware.com/server-info
http://example.eng.vmssoftware.com/server/status
</pre>

If your connection fails, shut down Apache and have a look at the log files located in APACHE$SPECIFIC:[LOGS] to figure out why the connection failed.

===Optional – Testing Connection with TELNET===

If you do not have a browser handy, a quick and easy way to test your unencrypted connection and see if your web server is working is to use TELNET.

* To connect to your webserver from the same system using TELNET, use the following commands.

<pre>
$ TELNET 0 80
%TELNET-I-TRYING, Trying ... 127.0.0.1
%TELNET-I-SESSION, Session 01, host localhost, port 80
-TELNET-I-ESCAPE, Escape character is ^]
(Press Enter and type the command below)
HEAD / HTTP/1.0
(Press Enter twice)
HTTP/1.1 200 OK
Date: Mon, 31 May 2021 10:52:10 GMT
Server: Apache/2.4.38 (OpenVMS)
Last-Modified: Fri, 28 May 2021 07:33:23 GMT
ETag: "2d-5c35ee3fe76c0"
Accept-Ranges: bytes
Content-Length: 45
Connection: close
Content-Type: text/html; charset=ISO-8859-1

%TELNET-S-REMCLOSED, Remote connection closed
-TELNET-I-SESSION, Session 01, host localhost, port 80
</pre>

Instead of using “HEAD / HTTP/1.0”, you can also try to use “GET /index.html HTTP/1.0” if you want to GET your index.html file.

==Flushing the Memory==

When you shut down Apache, the memory is automatically flushed to disk so that you can review the log files. It is not always convenient, however, to shut down the web server every time you need to have a look at the log files, which is why it could be useful to know how to manually flush the memory.

* First, you need to run the command procedure shown below to define the necessary symbol.

<pre>
$ @apache$root:[000000]apache$setup.com
$ show sym httpd
HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
</pre>

* Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.

<pre>
$ httpd -h
Usage: APACHE$HTTPD.EXE;1 [-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-k start|restart|graceful|graceful-stop|stop|flush]
[-v] [-V] [-h] [-l] [-L] [-t] [-T] [-S]
Options:
-D name : define a name for use in <IfDefine name> directives
-d directory : specify an alternate initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C "directive" : process directive before reading config files
-c "directive" : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
</pre>

* To flush the memory to disk, use the -k flag followed by the keyword “flush”.

<pre>
$ httpd -k flush
</pre>

==Setting Up HTTPS Support for Apache==

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

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

1 item found
</pre>

===Creating a Self-Signed Certificate===

To create a self-signed certificate, it is easiest to use the built-in utility APACHE$COMMON:[000000] APACHE$CREATE_ROOT.COM, which will guide you through the process.

* Run the command procedure and answer the questions to create your self-signed certificate:

<pre>
1. View a Certificate

2. View a Certificate Request

3. Create a Certificate Request

4. Create a Self-Signed Certificate

5. Create a Certificate Authority

6. Sign a Certificate Request

7. Hash Certificate Authorities

8. Hash Certificate Revocations

9. Exit

Enter Option: 4

...

Encrypt Private Key ? [N]
Encryption Bits ? [1024] 2048
Certificate Key File ? [OPENSSL_ROOT:[KEY]SERVER.KEY] apache$root:[conf.ssl_key]server.key
Certificate File ? [OPENSSL_ROOT:[CRT]SERVER.CRT] apache$root:[conf.ssl_crt]server.crt
Country Name ? [US]
State or Province Name ? [Massachusetts]
City Name ? [Burlington]
Organization Name ? [VMS SOFTWARE INC.]
Organization Unit Name ? [OPENVMS SUPPORT]
Common Name ? [example.eng.vmssoftware.com]
Email Address ? [you@your.address]
Display the Certificate ? [N] Y
</pre>

Pay special attention to the portions of the certificate creation that are highlighted in yellow. It is recommended that you use 2048 encryption bits instead of the default 1024. Furthermore, you also need to place the key and certificate files inside the Apache file structure.

* 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.

===Configuring HTTPS===

With key and certificate in hand, you can now configure Apache to allow for HTTPS connections.

* First edit the main configuration file APACHE$COMMON:[000000.CONF]HTTPD.CONF and, at the very bottom of the file, uncomment the Include directive that imports SSL-specific configuration directives from the file APACHE$ROOT:[CONF]SSL.CONF.

<pre>
$ edit apache$common:[000000.conf]httpd.conf

...

Include /apache$root/conf/ssl.conf
</pre>

* Next, edit APACHE$ROOT:[CONF]SSL.CONF and add the correct pathways to your key and certificate files. If you have obtained a certificate from a Certificate Authority, you can also specify the certificate chain file here. Alternatively, you might have a bundle file that contains key, certificate, and certificate chain file all together that you can specify instead.

<pre>
$ edit apache$root:[conf]ssl.conf
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /apache$root/conf/ssl_crt/server.crt
#SSLCertificateFile /apache$root/conf/ssl_crt/server-dsa.crt

# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /apache$root/conf/ssl_key/server.key
#SSLCertificateKeyFile /apache$root/conf/ssl_key/server-dsa.key

# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /apache$root/conf/ssl_crt/ca.crt

# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /apache$root/conf/ssl_crt
#SSLCACertificateFile /apache$root/conf/ssl_crt/DigiCertCA.crt
</pre>

Above, a self-signed certificate has been used and, so, only the paths to the key and certificate files have been specified (highlighted in yellow above). If you have acquired your certificate from a certificate authority, you might also need to add the CA Certificate File using the SSLCACertificateFile directive (highlighted in yellow at the end of the output above).

* Finally, restart the web server to implement the changes and connect to your web server via HTTPS. If the connection fails, you will need to review the log files and try to figure out why.

===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.

<pre>
$ openssl x509 -outform der -in apache$specific:[conf.ssl_crt]server.crt -out -
_$ apache$specific:[conf.ssl_crt]server_crt.der
$ openssl rsa -outform der -in apache$specific:[conf.ssl_key]server.key -out -
_$ apache$specific:[conf.ssl_key]server_key.der
</pre>

View the DER encoded certificates and keys with the commands

<pre>
$ openssl x509 -in apache$specific:[conf.ssl_crt]server_crt.der -inform der -text -noout
$ openssl rsa -in apache$specific:[conf.ssl_key]server_key.der -inform der -text -noout
</pre>

* 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.

<pre>
unable to load certificate
12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
</pre>

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.

<pre>
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
error:tasn_dec.c:380:Type=X509
</pre>

* To transform a DER encoded certificate and key to the PEM format, use

<pre>
$ openssl x509 -inform der -in apache$specific:[conf.ssl_crt]server_crt.der -out -
_$ apache$specific:[conf.ssl_crt]server_crt.pem

$ openssl rsa -inform der -in apache$specific:[conf.ssl_key]server_key.der -out -
_$ apache$specific:[conf.ssl_key]server_key.pem
</pre>

To now view the certificate and key files in the PEM format, use

<pre>
$ openssl x509 -in cert.pem -inform pem -text -noout
$ openssl rsa -in key.pem -inform pem -text -noout
</pre>

* 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 private key and public key into the same certificate. 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 command $ APPEND. Below, the contents of the key file and the certificate file are appended to the new, empty file cert_and_key.pem.

<pre>
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem
(Press Ctrl-Z)

$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem –
_$ apache$specific:[conf.ssl_crt]cert_and_key.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server.key;1 (input) and APACHE$SPECIFIC:[sslcerts]cert_and_key2.pem;1 (output) have incompatible attributes
</pre>

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

<pre>
$ append apache$specific:[conf.ssl_key]server_key.pem, -
_$ apache$specific:[conf.ssl_crt]server_crt.pem, -
_$ apache$specific:[conf.ssl_crt]CAcrt.pem –
_$ apache$specific:[conf.ssl_crt]cert_key_and_CA.pem
%APPEND-W-INCOMPAT, APACHE$SPECIFIC:[sslkeys]server_key.pem;1 (input) and APACHE$SPECIFIC:[sslcerts]]cert_key_and_CA.pem;1 (output) have incompatible attributes
</pre>

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.

===Optional – Testing HTTPS Connection Using OpenSSL===

If you cannot access your web server 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.

<pre>
$ @sys$startup:ssl111$startup.com
$ @ssl111$root:[com]ssl111$utils.com define
</pre>

* 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.

<pre>
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com:443 “-showcerts” “-state”
CONNECTED(00000003)

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
...
</pre>

==Optional - Setting up PHP for Apache==

This section will show you how to set up PHP for web development with Apache; to complete it, you need to already have PHP installed on your system.

===Loading PHP module===

The first thing you need to do is to load the PHP module in the Apache’s main configuration file.

* Copy over the file PHP$ROOT:[csws]mod_php5.exe to the directory where Apache stores its modules.

<pre>
$ copy php$root:[csws]mod_php5.exe apache$common:[modules] /log
%COPY-S-COPIED, PHP$ROOT:[csws]mod_php5.exe;1 copied to APACHE$COMMON:[modules]mod_php5.exe;1 (79KB)
</pre>

* To import the module, you need to make some changes in the main configuration file. A common and convenient practice is to keep the configuration for PHP separate, as was the case earlier in this document for SSL. Use the $ EDIT command to create the file APACHE$COMMON: [CONF]mod_php.conf and paste the lines below into the file.

<pre>
$ edit apache$common:[conf]mod_php.conf
## Load PHP module
LoadModule php5_module modules/mod_php5.exe
## Define types to be associated with MOD_PHP
AddType application/x-httpd-php .php .phtml
AddType application/x-httpd-php-source .phps
[End of file]
</pre>

* To incorporate these changes, add the following line at the very bottom of the main configuration file.

<pre>
$ edit apache$common:[conf]httpd.conf

...

Include /apache$root/conf/mod_php.conf
</pre>

* The last thing you need to do is restart Apache to load the changes in the main configuration file.

===A PHP Example===

Now that PHP has been set up with Apache, you can try to create a .php file and attempt to load it in your web browser. However, you need to make sure that the .php files have the correct file format Stream_LF in order for them to load correctly.

* First create a test file in the APACHE$SPECIFIC:[HTDOCS] directory with the .php extension and fill it with some PHP code.

<pre>
$ create apache$specific:[htdocs]test.php
<!DOCTYPE html>
<html>
<body>

<?php
echo "Testing the PHPINFO () function \n";
phpinfo (INFO_ALL);
?>

</body>
</html>
(Press Ctrl-Z)
</pre>

* Next, convert the file from the file format Variable Length to Stream_LF. There are several ways to do this on OpenVMS, the easiest of which to use the built-in utility that comes with the Apache installation APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM. Though, to convert .php files, we first need to make some changes to APACHE$ROOT:[000000]APACHE$CVT _TYPES.DAT. Edit the file and add the line highlighted in yellow below.

<pre>
$ edit apache$root:[000000]APACHE$CVT_TYPES.DAT
# APACHE$CVT_TYPES.DAT
#
# File types that get converted by APACHE$CONVERT_STREAMLF.COM
#

.HTM* #All HTML files (.HTM, .HTML, .HTML.FR, etc)
.SHTML #Server-side includes
.TXT #All TXT files
.PHP #All PHP Scripts
[End of file]
</pre>

Now, run APACHE$ROOT:[000000]APACHE$CONVERT_STREAMLF.COM to convert your .php file. The command procedure will ask you for the top directory for all the files you want to convert to Stream_LF, which in our case is APACHE$SPECIFIC:[HTDOCS] (highlighted in yellow).

<pre>
$ @apache$root:[000000]apache$convert_streamlf.com
Top Directory: apache$specific:[htdocs]

Starting conversion of apache$specific:[htdocs...]
This could take a while...

Conversions complete.
See SYS$SCRATCH:Convert_Dir.Log for a log of transactions.
</pre>

* This will create a new version of your php file, the file format of which you can find out with the command shown below.

<pre>
$ dir apache$specific:[htdocs]test.php;2 /full

Directory APACHE$SPECIFIC:[HTDOCS]

test.php;2 File ID: (11941,32,0)
Size: 0.50KB/8KB Owner: [APACHE$WWW]

...

Record format: Stream_LF, maximum 0 bytes, longest 43 bytes

...
</pre>

* As a last step, load the file in your browser by visiting your relevant address.

<pre>
https://example.eng.vmssoftware.com/test.php
</pre>

* After testing the test.php file, you should delete it since it lists sensitive information about your server.

=Removing Apache=

To completely remove Apache (and all its files), do the following:

* Shut down Apache.

<pre>
$ @sys$startup:apache$shutdown
</pre>

* Before you uninstall Apache, you should take note of where Apache is installed by taking a look at the Apache logicals. These will be removed with the removal of Apache.

<pre>
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

"APACHE$ODS5_AVAIL" = "1"

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

"APACHE$APR_SHR" = "APACHE$COMMON:[000000]APACHE$APR_SHR.EXE"
"APACHE$APR_SHRP" = "APACHE$COMMON:[000000]APACHE$APR_SHRP.EXE"
"APACHE$APU_SHR" = "APACHE$COMMON:[000000]APACHE$APU_SHR.EXE"
"APACHE$COMMON" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.]"
"APACHE$HTTPD_SHR" = "APACHE$COMMON:[000000]APACHE$HTTPD_SHR.EXE"
"APACHE$ROOT" = "APACHE$SPECIFIC"
= "APACHE$COMMON"
"APACHE$SPECIFIC" = "YOURDISK:[SYS0.SYSCOMMON.APACHE.SPECIFIC.YOURNODE.]"
"APACHE$VSIKITS" = "DSA0:[000000.]"

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
</pre>

* Uninstall Apache using the command below. If you want to completely remove Apache, you will want to answer “YES” to deleting the Apache Htdocs & Icons directory trees. The response is highlighted in yellow in the output.

<pre>
$ product remove csws

The following product has been selected:
VSI I64VMS CSWS V2.4-38D Layered Product

Do you want to continue? [YES]

The following product will be removed from destination:
VSI I64VMS CSWS V2.4-38D DISK$SYS1:[VMS$COMMON.]

Portion done: 0%

Deleting the Apache Htdocs & Icons directory trees will remove ALL user
data stored within.

Delete the Apache Htdocs & Icons directory trees ? [NO]: YES

This could take a minute or two. . . .

...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

The following product has been removed:
VSI I64VMS CSWS V2.4-38D Layered Product
</pre>

* If you wish to do a complete removal of Apache, you should know that there are still files located in APACHE$ROOT:[000000], which itself is a search list consisting of APACHE$COMMON:[000000] and APACHE$SPECIFIC:[000000], that have not been removed. Since these logicals are now gone, you will need to use the locations from the $ SHOW LOGICAL *APACHE* command you used earlier. To remove the entire APACHE$COMMON directory tree (and APACHE$SPECIFIC as it is located in the same directory structure), you can use the $ DELETE /TREE command. However, because all files are deleted without mercy, you need to be very careful and make sure you do not delete any important files by mistake. Use this command at your own risk.

<pre>
$ delete /tree YOURDISK:[SYS0.SYSCOMMON.APACHE...]*.*;* /log
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;6 deleted (8KB)
%DELETE-I-FILDEL, YOURDISK:[SYS0.SYSCOMMON.APACHE]LOGIN.COM;5 deleted (8KB)
...
$ delete $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 /conf
DELETE $1$DGA100:[SYS0.SYSCOMMON]APACHE.DIR;1 ? [N]: Y
$ delete /tree SYS$SYSDEVICE:[APACHE...] /log
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE]APACHE$CONFIG.DAT;1 deleted (8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.OPENSSL.COM]OPENSSL_EXIT_CMD.TPU;1 deleted
(8KB)
%DELETE-I-FILDEL, SYS$SYSDEVICE:[APACHE.SPECIFIC.YOURNODE]APACHE$HTTPD.DMP;1 deleted
(42.58MB)
...
$ delete SYS$SYSDEVICE:[000000]APACHE.DIR;1 /conf
DELETE SYS$SYSDEVICE:[000000]APACHE.DIR;1 ? [N]: Y
</pre>

* The last remnants of Apache are its username APACHE$WWW inside the SYSUAF and any Apache logicals that you may have defined. First, delete the username account.

<pre>
$ mcr authorize
UAF> remove apache$www
%UAF-I-REMMSG, record removed from system authorization file
%UAF-I-RDBREMMSGU, identifier APACHE$WWW value [000200,000201] removed from rights
database
</pre>

Then, to delete the logicals, use the DEASSIGN command.

<pre>
$ deassign /job APACHE$ODS5_AVAIL
$ deassign /sys APACHE$VSIKITS
$ show logical *apache*

(LNM$PROCESS_TABLE)

(LNM$JOB_892E1D00)

(LNM$GROUP_000001)

(LNM$SYSTEM_TABLE)

(LNM$SYSCLUSTER_TABLE)

(DECW$LOGICAL_NAMES)
%SHOW-S-NOTRAN, no translation for logical name *APACHE*
</pre>