Apache (CSWS) - Easy Installation Guide
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).
Contents
- 1 Introduction
- 2 Installation
- 3 Configuration
- 3.1 Running APACHE$CONFIG
- 3.2 Automatic Start-up and Shutdown Commands
- 3.3 Ensuring SYS$SCRATCH Points To ODS-5 Device
- 3.4 Utilizing LOGIN.COM
- 3.5 Changes to the Main Configuration File
- 3.6 Starting Apache
- 3.7 Connecting to your Web Server
- 3.8 Flushing the Memory
- 3.9 Setting Up HTTPS Support for Apache
- 3.10 Optional - Setting up PHP for Apache
- 4 Removal
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.
$ prod show prod ssl111 ------------------------------------ ----------- --------- PRODUCT KIT TYPE STATE ------------------------------------ ----------- --------- VSI I64VMS SSL111 V1.1-1K Full LP Installed ------------------------------------ ----------- --------- 1 item found
- 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.
$ show devices $1$YOURDISK: /full
- Towards the bottom of the output, you will see the volume status.
Volumes Status: ODS-5, ...
- 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
$ @sys$startup:apache$shutdown.com
- Remove Apache with the command
$ product remove csws
- 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
$ run VSI-I64VMS-CSWS-V0204-38D-1.ZIPEXE
- Install Apache using the PCSI application.
$ 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.
- 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.
$ @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
- After running the configuration file, you can use the $ SHOW LOGICAL command to see the newly created Apache logicals.
$ 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)
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.
$ file := SYS$STARTUP:APACHE$STARTUP.COM
$ if f$search("''file'") .nes. "" then @'file'
- Next, edit the file SYS$MANAGER:SYSHUTDWN.COM and insert the lines shown below.
$ file := SYS$STARTUP:APACHE$SHUTDOWN.COM
$ if f$search("''file'") .nes. "" then @'file'
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.
$ 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 ...
- 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.
$ create/directory apache$root:[000000.SCRATCH] /prot=(s:rwe,o:rwed,g:re) /log %CREATE-I-CREATED, APACHE$SPECIFIC:[000000.SCRATCH] created
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.
$ 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]
- 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.
$ 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
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).
...
#
# 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
...
- 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.
$ 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 ...
- 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.
... ServerAdmin you@your.address.com ...
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.
$ 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 ...
- 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”.
... # # 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> ...
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.
$ @sys$startup:apache$startup
- To see if the process has started, you can use the command
$ 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
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.
$ @sys$startup:apache$shutdown.com
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.
http://example.eng.vmssoftware.com http://example.eng.vmssoftware.com/server-info http://example.eng.vmssoftware.com/server/status
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.
$ 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
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.
$ @apache$root:[000000]apache$setup.com $ show sym httpd HTTPD == "$ APACHE$COMMON:[000000]APACHE$HTTPD.EXE"
- Next, to find out how to use the httpd utility, type it in at the command prompt followed by the -h flag for help.
$ 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
- To flush the memory to disk, use the -k flag followed by the keyword “flush”.
$ httpd -k flush
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.
$ prod show prod ssl111 ------------------------------------ ----------- --------- PRODUCT KIT TYPE STATE ------------------------------------ ----------- --------- VSI I64VMS SSL111 V1.1-1IA Full LP Installed ------------------------------------ ----------- --------- 1 item found
Creating a Self-Signed Certificate
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:
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
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.
$ edit apache$common:[000000.conf]httpd.conf ... Include /apache$root/conf/ssl.conf
- 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.
$ 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
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.
$ 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
View the DER encoded certificates and keys with the commands
$ 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
- If you get the following error when viewing your encoded certificate, it means that you are trying to view a DER encoded certificate when your certificate is in fact PEM encoded.
unable to load certificate 12626:error:0906D06C:PEM routines:PEM_read_bio:no start line:pem_lib.c:647:Expecting: TRUSTED CERTIFICATE
If you get the following error, it means that you are trying to view a PEM encoded certificate with a command meant for DER encoded certificates.
unable to load certificate. 13978:error:0D0680A8:asn1 encoding routines:ASN1_CHECK_TLEN:wrong tag:tasn_dec.c:1306: 13978:error:0D07803A:asn1 encoding routines:ASN1_ITEM_EX_D2I:nested asn1 error:tasn_dec.c:380:Type=X509
- To transform a DER encoded certificate and key to the PEM format, use
$ 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
To now view the certificate and key files in the PEM format, use
$ openssl x509 -in cert.pem -inform pem -text -noout $ openssl rsa -in key.pem -inform pem -text -noout
- In some cases, it is advantageous to combine multiple pieces of the X.509 infrastructure into a single file. One common example would be to combine both the 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.
$ create apache$specific:[conf.ssl_crt]cert_and_key.pem <b><span style="color:green">(Press Ctrl-Z)</span></b> $ 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
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
$ 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
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.
$ @sys$startup:ssl111$startup.com $ @ssl111$root:[com]ssl111$utils.com define
- Then, use the command below to see if you can establish an HTTPS connection. Make sure you specify the correct DNS name and port for your server.
$ OpenSSL s_client “-connect” example.eng.vmssoftware.com: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
...
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.
$ 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)
- 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.
$ 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]
- To incorporate these changes, add the following line at the very bottom of the main configuration file.
$ edit apache$common:[conf]httpd.conf ... Include /apache$root/conf/mod_php.conf
- 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.
$ 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)
- 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.
$ 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]
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).
$ @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.
- This will create a new version of your php file, the file format of which you can find out with the command shown below.
$ 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
...
- As a last step, load the file in your browser by visiting your relevant address.
https://example.eng.vmssoftware.com/test.php
- 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.
$ @sys$startup:apache$shutdown
- 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.
$ 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)
- 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.
$ 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
- 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.
$ 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
- 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.
$ 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
Then, to delete the logicals, use the DEASSIGN command.
$ 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*
