Deploy CCS Apache Tomcat and Configure Security

Deploy CCS Apache Tomcat and set up default security in your CCS Apache Tomcat Region.
ccsfzos15
This article describes how Systems Administrators and Programmers can deploy the appropriate CA Common Services for z/OS (CCS) SMP/E target libraries to the
CCS Apache Tomcat Deployment zFS
. This article also shows how Security Administrators can set up default certificates that all
CCS Apache Tomcat Regions
can use.
2
Deploy CCS Apache Tomcat to the CCS Apache Tomcat Deployment zFS
Follow these steps:
  1. Apply the latest CCS Apache Tomcat maintenance. CCS Apache Tomcat is updated regularly with the latest stable build of Apache Tomcat, as often as once a quarter. For information about how to apply maintenance to CCS Apache Tomcat, see one of the following articles:
    • Maintain Products Using CA CSM
    • Apply Preventative Maintenance
    For information about the latest CCS Apache Tomcat PTF that is published, see the Release Notes.
  2. Copy the following members from the CAW0JCL SMP/E target library to a library where you can customize them for your installation:
    The
    TOMKACF2
    (CA ACF2),
    TOMKTSS
    (CA Top Secret), and
    TOMKRACF
    (IBM RACF) members are jobs that let you configure the security for the
    CCS Apache Tomcat Region
    . Copy
    only
    the member that represents the security application at your site.
    • TOMDPLOY
    • TOMKACF2
    • TOMKRACF
    • TOMKTSS
    • TOMKXML
    • TOMSEDIT
  3. Edit the TOMSEDIT member for all the following required variables, starting at the section header named
    Deploy CCS Apache Tomcat to the CCS Apache Tomcat Deployment zFS
    .
    The
    CCSHLQ
    and
    SRCDIR
    variables reference the data sets and the files that exist in your environment after you installed CA Common Services. Contact the individual that installed CA Common Services to identify the installed values.
    • CCSHLQ
      Specifies the high-level qualifier for the CCS installation.
      Default:
      CAI
    • SRCDIR
      Specifies the mount point for the CCS Apache Tomcat SMP/E Target zFS (by default, .CEG1ZFS1). TOMDPLOY uses the path to copy CCS Apache Tomcat folders and files to the
      CCS Apache Tomcat Deployment zFS
      .
      Default:
      /cai/CASoftware/CCS150/tpv
    • DISKUNIT
      Specifies the name of the disk unit to be used when creating the
      CCS Apache Tomcat Deployment zFS
      data sets.
      Default:
      3390
    • VOLNAME
      Specifies the volume to be used when creating the
      CCS Apache Tomcat Deployment zFS
      data sets. Specify the parameter only when SMS is not active on the system. When you specify the keyword, the SMS allocation parameter that is named STORCLAS is not used.
      Default:
      The VOLNAME parameter is disabled by default (commented out).
    • STORCLAS
      Specifies the storage class to be used when creating the
      CCS Apache Tomcat Deployment zFS
      data sets. If you specify the VOLNAME parameter, do not specify STORCLAS.
      Default:
      SC01
      When creating data sets, you can specify
      STORCLAS
      or
      VOLNAME
      . If you specify both parameters, the
      VOLNAME
      parameter is used and
      STORCLAS
      is ignored.
    • DPLOYHLQ
      Specifies the high-level qualifier to be used to create the
      CCS Apache Tomcat Deployment zFS
      data set. For example, using the default value creates a zFS named CAI.CEG1ZFS1.
      Default:
      CAI
    • DPLOYDIR
      Specifies the directory that is used as the mount point for the
      CCS Apache Tomcat Deployment zFS
      . TOMDPLOY mounts the zFS and then copies CCS Apache Tomcat folders and files from the SMP/E target libraries to the
      CCS Apache Tomcat Deployment zFS
      .
      The
      CATALINA_HOME
      variable that is used by Apache Tomcat and various products refers to the
      tomcat
      directory at this mount point.
      Default:
      /cai/CADeploy/CCS150/tpv
      Default CATALINA_HOME:
      /cai/CADeploy/CCS150/tpv/tomcat
  4. Save and close TOMSEDIT. You define the remaining variables later in this article.
  5. Follow the steps in the TOMDPLOY job to create the
    CCS Apache Tomcat Deployment zFS
    .
    The
    CCS Apache Tomcat Deployment zFS
    can be shared by multiple
    CCS Apache Tomcat Regions
    .
  6. After you complete Steps 1 through 4, and the TOMDPLOY job completes, expect the following results:
    • The TOMDPLOY job completes with one of the following reason codes:
      • RC=0 when VOLNAME is not defined
      • RC=2 when VOLNAME is defined
      • If the return code equals 1 (RC=1) or it is greater than 2 (RC>2), an error occurred. To correct the problem, analyze the output and correct any errors or warnings that display.
    • The
      CCS Apache Tomcat Deployment zFS
      is created (CAI.CEG1ZFS1).
    • The
      CCS Apache Tomcat Deployment zFS
      is mounted and populated with a copy of the CCS Apache Tomcat SMP/E library.
  7. Choose
    one
    of the following security options for the CCS Apache Tomcat Region:
Configure Security for the CCS Apache Tomcat Region
After you deploy CCS Apache Tomcat to a
CCS Apache Tomcat Deployment zFS
, we strongly recommend that Security Administrators configure the security for the
CCS Apache Tomcat Regions
. If you do not complete the steps in this topic now, the owners of
CCS Apache Tomcat Regions
must configure the security for their regions, as desired.
If you plan to use AT-TLS security for the CCS Apache Tomcat Region, skip this procedure. Go to Configure a CCS Apache Tomcat Region.
The jobs that we provide let you complete the following tasks automatically. Complete the steps in this topic only once.
  • Create and connect an Internal Certificate Authority (CA) certificate and an Internal CA key ring.
  • Create and connect a Server certificate (signed by an Internal CA) and a Server key ring.
  • Connect the Internal CA certificate to Server key ring.
  • Update the active Connector in the TOMSVXML member (server.xml) to use the newly created Server key ring.
Security Administrators should review the commands that are in the jobs that we supply. Verify that the commands conform to the security requirements for your site.
The following steps describe how to create a default certificate that you can use for security in your
CCS Apache Tomcat Regions
.
TLS 1.3 support in CCS Apache Tomcat requires IBM Java Version 8 Service Refresh 6 FP25 or later.
Follow these steps:
  1. Ensure that the steps in Deploy CCS Apache Tomcat to the CCS Apache Tomcat Deployment zFS were completed successfully.
  2. Edit the TOMSEDIT member for all the following required variables, starting at the section header named
    Configure Security for the CCS Apache Tomcat Region
    .
    • DPLOYDIR
      Specifies the mount point of the
      CCS Apache Tomcat Deployment zFS
      created in
      Deploy CCS Apache Tomcat to the CCS Apache Tomcat Deployment zFS
      .
    • COMPANY
      Specifies the company name
    • ORG
      Specifies the organization name
    • COUNTRY
      Specifies the country name
    • SRVID
      Specifies the user ID that is associated with the Server Certificate
    • SRVCERT
      Specifies an 8-byte Server Certificate name
    • SRVLABL
      Specifies the Server Certificate label
    • SRVKYRNG
      Specifies key ring name for the Server Certificate
    • SRVCN
      Specifies the Server Certificate common name
    • SRVEXPDT
      Specifies the Server Certificate expiration date:
      • CA ACF2:
        mm/dd/yy
        Range:
        mm/dd/50 to mm/dd/48 (1950 through 2048)
      • CA Top Secret:
        mm/dd/yy
        Range:
        mm/dd/50 to mm/dd/49 (1950 through 2049)
      • IBM RACF:
        yyyy-mm-dd
        Range:
        1950-mm-dd to 9997-mm-dd (1950 through 9997)
    • SRVEXPTM
      Specifies the Server Certificate expiration time. The format of the variable is
      hh:mm:ss
      .
    • CAID
      Specifies the user ID that is associated with the Internal CA Certificate
    • CACERT
      Specifies an 8-byte CA Certificate name
    • CALABL
      Specifies the Internal CA Certificate Label (ACF2/RACF only)
    • CAKYRNG
      Specifies the Key ring name for the Internal CA Certificate
    • CACN
      Specifies an Internal CA Certificate common name
    • CAEXPDT
      Specifies the Internal CA Certificate expiration date:
      • CA ACF2:
        mm/dd/yy
        Range:
        mm/dd/50 to mm/dd/48 (1950 through 2048)
      • CA Top Secret:
        mm/dd/yy
        Range:
        mm/dd/50 to mm/dd/49 (1950 through 2049)
      • IBM RACF:
        yyyy-mm-dd
        Range:
        1950-mm-dd to 9997-mm-dd (1950 through 9997)
    • CAEXPTM
      Specifies the Internal CA Certificate expiration time. The format of the variable is
      hh:mm:ss
      .
  3. Save and close TOMSEDIT. You define the remaining variables later in this article.
  4. Edit and run the job that corresponds with the security product that is active in your environment. The job creates a default certificate that all
    CCS Apache Tomcat Regions
    can use and configure the TOMSVXML member.
    • CA ACF2:
      TOMKACF2
    • CA Top Secret:
      TOMKTSS
    • IBM RACF:
      TOMKRACF
    Ensure that you mount the deployment file system to the same system on which you run the TOMK* security job. This approach ensures that you can update the
    server.xml
    file with correct certificate information.
After you complete Steps 1 through 3 and the TOMK* job completes, expect the following results:
  • The TOMK* job completes successfully with return code zero (RC=0).
  • The TOMK* job creates a file that is named
    TOMSVXML_keyring
    . This file is in the
    DPLOYDIR/tomcat/conf
    directory with the necessary updates to use the newly created certificate.
  • When the TOMK* job completes with a return code that is greater than zero (RC>0), an error or warning occurs. To correct the problem, analyze the output and correct any errors that display.