Axis2 - Easy Installation Guide

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 Open Source Software for OpenVMS page.

Introduction

Go through the following steps to install Axis2.

• Unpack the kit with the $ RUN command

$ run VSI-I64VMS-AXIS2-V0107-3-1.ZIPEXE 
 

Then, install Axis2 with the command

$ 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
 

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

$ 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

...
 

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.

$ @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)
 

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.

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

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.

$ edit tomcat$root:[conf]server.xml

...

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

...
 

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.

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

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.

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

...

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

...
 

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

...

<!-- ================================================= -->
    <!-- Transport Ins -->
    <!-- ================================================= -->

    <!-- The default configuration assumes that AxisServlet only receives requests
         through HTTP. To allow HTTPS as well, configure a second AxisServletListener
         with name="https" and specify the port parameter on both receivers.
         For more information, please have a look at the servlet transport documentation:
         http://axis.apache.org/axis2/java/core/docs/servlet-transport.html -->
 

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

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

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

$ @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
...
 

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

https://your.server.com:8443/axis2/
 

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.

$ edit tomcat$root:[conf]server.xml

...

<!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

...
 

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

$ edit apache$root:[000000.conf]httpd.conf

...

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

...
 

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.

...

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

...
 

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

$ @sys$startup:apache$shutdown
$ @sys$startup:apache$startup
 

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

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

Removal

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

• First, shut down Tomcat.

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

• Then, uninstall Axis2 using the command below.

$ 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
 

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

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

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.

$ 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
 

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

$ 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
 

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

$ 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