Install and Set Up Web Services

As a web services administrator, you can configure and deploy the Web Services component. This component is a prerequisite for the Eclipse-Based UI. In addition, you can use Web Services to connect your user-written program to the API.
ce18
As a web services administrator, you can configure and deploy the Web Services component. This component is a prerequisite for the Eclipse-Based UI. In addition, you can use Web Services to connect your user-written program to the
CA Endevor
API.
For information on how to configure Web Services with the the z/OSMF web interface, see Configure
CA Endevor
Web Services with z/OSMF
.
The process of configuring and deploying Web Services on your z/OS system is performed in a UNIX System Services (USS) environment. During this process, you complete the following objectives:
  • Create a dedicated Tomcat instance for Web Services on your Tomcat server.
  • Deploy Web Services to the Tomcat instance.
When you want to run Web Services under a new release of Tomcat, we recommend that you create a new Web Services deployment in a new Tomcat directory tree. For more information, see How to Run Web Services Under a New Release of Tomcat.
How to Configure and Deploy Web Services
Follow these steps:
  1. Review the prerequisite information for an understanding of how Web Services works. For more information, see How to Enable Web Services
  2. Open the Tomcat start job member (delivered as WSTOMSTC in CSIQJCL).
    1. Verify that the STEPLIB value points to the installed data set CSIQPLD.
      Web Services are not working if the STEPLIB value does not point to the data set CSIQPLD!
    2. Add a jobcard.
      If you don't add a jobcard manually, a jobcard is added automatically that uses the JOBCARD1-4 parameters from the ENWSInstallOptions.properties file.
  3. Verify and edit the parameters in the ENWSInstallOptions.properties file according to your environment. For more information about the parameters, see Installation Properties File or the comments in the file.
    If you don't want to run the installation manually, skip the following steps 4 to 7. Instead, run the WSTOMCCS job in CSIQJCL with parameter ENWS set to INSTALL and continue with step 8.
  4. Start the TSO OMVS environment from the USS command prompt.
    You cannot invoke the installation script (ENWSIns.sh) from a z/OS Telnet session or from an ISHELL command shell.
  5. Verify that you are using a userid with UID(0), if you want to run the installation under root (parameter RUN_AS_ROOT in ENWSInstallOptions.properties is set to YES).
    To switch to UID(0), perform the su command.
    If you don't run the installation script under root (UID(0)), the files copied during the installation are created under the user running the script. Therefore the permissions on the copied files do not guarantee the highest security.
  6. From the OMVS command prompt, execute the following command to change to the install directory where the script ENWIns.sh resides:
    cd <USS install directory>/tpv
  7. Execute the following script:
    sh ENWSIns.sh
    The script completes the following actions:
    • Validates if the user running the script has the necessary permissions to complete the installation.
      • Systems programmers might not have the access that is required to run this script, and might need to request access from their security administrator.
      • This validation step takes place only if the parameter RUN_AS_ROOT in
        ENWSInstallOptions.properties
        is set to NO.
    • Validates parameters specified in the ENWSInstallOptions.properties file.
    • Creates a dedicated Tomcat instance for Web Services on your Tomcat server.
    • Adds Runtime libraries (including Axis2 1.6 and Jersey 2.7) to this Tomcat instance.
    • Deploys Web Services to the Tomcat instance.
    • Configures the installation based on parameters in the ENWSInstallOptions.properties file.
    • Validates the created Tomcat instance.
    The install script can be interactive based on the options that are specified in the ENWSInstallOptions.properties.
  8. Start the Apache Tomcat server.
    Work with your systems administrator to ensure that the WSTOMSTC task starts after an IPL. The JCL is customized so that the Apache Tomcat server starts in its own address space.
  • Create a configuration file, using ENDEVOR.cfg as a template, for the configuration (instance of
    CA Endevor
    ) that Web Services access.
    Deploy the file by saving it tto the following location:
    /cai/CADeploy/ESCM/tpv/tomcat/webapps/endevor
    For more information, see Configuration Files.
    You can create more than one configuration file. Possible scenarios for creating more than one configuration file include supporting different code page needs; reserving pooled and unpooled started task usage; or running alternate copies of
    CA Endevor
    (testing and production).
Completing these steps sets up Web Services to use the Eclipse Plug-in. For more information about client stubs, see SOAP Clients.
Edit the Tomcat Configuration File
To enable this instance of Tomcat to communicate with Web Services, edit the Tomcat configuration file.
Edit the
server.xml
file that is located at:
/cai/CADeploy/ESCM/tpv/tomcat/conf
Change the server, connector, and redirect port numbers as necessary for your site. Confirm that you have a unique TCP/IP port number for this instance of the Tomcat server for communications. Each program on an LPAR using TCP/IP for communications must have a unique port number.
The server.xml file is ASCII encoded and it must stay that way. One method to edit the server.xml file is to use ISPF EDIT. This method is described next.
Follow these steps:
  1. Enter the following command on your ISPF panel:
    TSO ISH
    The UNIX System Services ISPF Shell panel opens.
  2. Type the following pathname where server.xml is located and then press Enter:
    /cai/CADeploy/ESCM/tpv/tomcat/conf/
    A directory list opens.
  3. Type E next to server.xml and press Enter.
    The server.xml file opens.
  4. Modify as required, and exit the file.
    The file is updated for your site and remains an ASCII encoded file.
If you require an HTTPS implementation of Tomcat, see to How to Configure Tomcat as an HTTPS server.
How to Configure Tomcat as HTTPS
You can optionally use HTTPS instead of HTTP for user access. This option lets you specify a user name and password to minimize concerns about the data being exposed in clear text on the network.
Follow these steps
:
  1. Complete the following steps to generate a keystore:
    1. In OMVS, enter the following command:
      $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
      A prompt appears.
    2. Specify a password, press Enter, and answer the questions.
      • We recommend using the host name that Tomcat runs on for the Common Name value so that when you are prompted to accept the certificate, it is clear which server it is coming from.
      • Optionally, specify a different location for the default keystore by replacing
        /path/to/my/keystore
        in the following command:
        $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore
      A default keystore is created in your home directory with one self-signed certificate inside.
  2. Update the Apache Tomcat configuration parameters in the
    server.xml
    file that is located in the tomcat_install_dir/conf directory as follows:
    • Uncomment or replace the SSL/TLS connector information to specify site-specific values for the port and keystoreFile parameters.
      Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer (SSL) are the same type of security protocol, with TLS being the newer version of SSL. Other documentation may still refer to TLS as SSL even when talking about one of the newer TLS versions.
      We recommend using TLS, because the older SSL is no longer considered secure.
      For example, to force usage of only the latest TLS version (1.2), set the parameter sslEnabledProtocols to ”TLSv1.2”. You need a Tomcat version of at least 7 to use this parameter and a Java version of at least 7 (or Java 6 with a service pack) to use TLS version 1.2.
      For more information about Tomcat V7 and TLS, see SSL/TLS Configuration HOW-TO.
      For more information about other versions of Tomcat and TLS, search on https://tomcat.apache.org.
      Ensure that the keystorePass value matches the password that is specified in Step 1.
      Sample SSL/TLS connector data follows:
      <!-- Define a SSL HTTP/1.1 Connector on port 8443… <Connector port="8040" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" sslEnabledProtocols=”TLSv1.2” keystorePass="<productcode>ssl" keystoreFile="/ca/.keystore"/>
    1. Edit the redirectPort value in the standard HTTP connector information to match the value that is specified in the SSL connector data:
      <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8040" />
  3. Add the following lines before </web-app> at the end of the
    web.xml
    file that is located in tomcat_install_dir/conf:
    <security-constraint> <web-resource-collection> <web-resource-name>Tomcat</web-resource-name> <url-pattern>*.html</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
After you start the Apache Tomcat server, you are prompted to indicate whether you trust the defined certificate. Click Yes to import it to your trusted certificates.